»Magic« Links

In ACE text objects, »magic« links allow special effects and conveniences that add spice to SCD web sites. Here is a brief overview of the most important ones (there are others which are in a state of flux or not quite done, and will be documented here in due course).

Images

Simple Images

It is easy to include images in ACE text objects. ACE supports the most important image formats, namely JPEG, PNG, and GIF (we could probably add more if there is interest). The simplest way of including an image is with a link like

<<img:st-andrews.jpg>>

Here is what happens: Image – you see that the image is included right in the middle of the text. So it often makes more sense to have the link be its own paragraph.

On the Web, images often include short explanatory »alternative texts« which describe the image for people who can't see or who have an older system that cannot display images. You can include such a text by simply including it in the link, separated by a vertical bar:

<<img:st-andrews.jpg|St Andrews Castle>>

Floating Images

Often one would like a slightly fancier way of including images. In a longer document, it is nice if the text »flows« around the image. You can do this by appending either »left« or »right« to the link, after yet another vertical bar:

<<img:st-andrews.jpg|St Andrews Castle|left>>

St Andrews Castle
As you can see, this also adds a border and a »drop shadow« to make the image look better. Obviously, if you put »left«, then the image appears at the left edge of the document, and if you put »right«, it ends up on the right-hand side.

St Andrews Castle
(If you'd rather not have the border and drop shadow, there are ways of getting that fixed but they involve deeper magic which is, as yet, undocumented. We may get around to it in time. Also consider that we spent rather a lot of effort to get the border and drop shadow just so, and we would be terribly disappointed if you didn't enjoy them.)

Images with Thumbnails

Large images often don't fit the screen very well, and they can also be tedious to download. What people like to do is to include a small version of an image – a »thumbnail« – together with a hyperlink to the original version. That way people can get an inkling of what the image looks like and then view the larger version at their leisure. ACE helps you here by automatically generating the thumbnail if you use the »imgt« scheme rather than the »img« scheme to include your image, and give the desired size for the thumbnail. For example,

<<imgt:st-andrews-large.jpg|St Andrews Castle|200x100:left>>

St Andrews Castle
produces a thumbnail that will fit in a box that is 200 by 100 pixels large, regardless of the size and aspect ratio of the original image. That is, the thumbnail will be at most 200 pixels wide and 100 pixels high – but if the original picture is 500 pixels wide and 1000 pixels high, what you will end up with is a 50-by-100 picture since 100 pixels is the maximum height allowable and the picture is twice as high as it is wide. (Click on the thumbnail to see the original picture.)

ACE generates the thumbnail the first time the ACE text object is displayed in a browser, and keeps it around for a while afterwards (we do remove thumbnails that haven't been looked at in a week, which isn't a big problem since when they are asked for again they are easily regenerated – it's more of a method to get rid of old thumbnails where you decided that you wanted the thumbnail in a different size after all, and thus they're never needed anymore; disk space is cheap nowadays but there's still no reason to waste it on extraneous stuff).

YouTube videos

You can include videos from YouTube by simply giving their YouTube ID to the »youtube« link scheme:

<<youtube:id:5DJXsfi_7ZM||right>>

Again, the »right« or »left« at the end makes the video box float to one side of the page and adds the decorative border and drop shadow. Note the two vertical bars before the »right«; one would probably suffice but two are better for consistency with the »img« and »imgt« schemes. Just remember that the text between the bars is the alternative description (which does not exist for videos) and the stuff after the second bar describes the formatting for ACE.

The method of embedding these videos is basically pinched from the HTML text that YouTube gives for the videos. There are ways of adapting this but again this is skirting the realm of the Dark Arts.

If you'd rather not use YouTube you can also include video content in ACE text objects, using the »video« magic link scheme. Tell Anselm if you would like to do this and he will explain. See also Videos on my.strathspey.

Please do not host very large files such as videos on your personal my.strathspey page, or a my.strathspey site that you are administering. They tend to clog up the ACE system, which is fairly efficient but not really geared towards serving up huge files piecemeal, and will make everything slower for everybody else. We have a special »media« server which uses a more direct way of getting these files out to people, and again if you would like to use this, tell Anselm and he will set you up for it. See also Videos on my.strathspey.

Dances from the online database

Simple cases

SCD-related content frequently mentions the names of dances; for example, Anselm keeps a diary of dances taught in his class, effectively publishing a »dance blog«. ACE makes it very convenient to connect these names to the Strathspey SCD Database, simply by writing something like

<<ddd:Braes of Breadalbane>>

which will result in a link to the database page for The Braes of Breadalbane. The link will display the name from the database rather than what you gave, and ACE uses a certain amount of trickery to deal with »The«, »A« and differences in case in order to find an entry for the dance. You will note that the link when displayed said »The Braes …« even though in our input we had just »ddd:Braes …«.

Again, you can give an alternate text to be displayed instead of the name of the dance, as in

We did <<ddd:Braes of Breadalbane|a very popular dance>> and then ...

which gives

We did a very popular dance and then …

Formatting References

Normally the link is displayed as simply the dance name (or alternate text). However, you can select exactly what is to be displayed from a variety of options by specifying a »format«, like

<<ddd:Braes of Breadalbane||%N (%r, %S)>>

which shows up as

The Braes of Breadalbane (S32, 3/4L)

after the percent-something »formatting keys« have been replaced by the corresponding bits from the actual entry.

Here's a list of available formatting keys:

Key Meaning
%b Number of bars per turn
%D The dance source
%N Link to the dance page, with text from the link or dance name
%P Link to the dance publication's page in DanceData
%r Dance type and number of bars per turn
%S The set shape
%T Name of the dance type (»Jig«, »Reel«, »Strathspey«, …)
%t »Short« name of the dance type (»J«, »R«, »S«, …)
%% A percent sign

There are also a few »pre-cooked« formats: »short« is equivalent to »%N (%r, %S)« while »shortsrc« is the same as »%N (%r, %S, %D)«:

<<ddd:Braes of Breadalbane||short>>
<<ddd:Braes of Breadalbane||shortsrc>>

gives

The Braes of Breadalbane (S32, 3/4L)
The Braes of Breadalbane (S32, 3/4L, RSCDS XXI 7)

It would of course be tedious in the extreme to have to specify the same format for all dance links on a long page. You can set a default format for all »ddd:« links in an ACE text object by including a line like

near the beginning of the file. All of the line after the colon will become the default format for this object. (This is such powerful mojo that you get to use it but once for every ACE text object.) This default format can be overridden in the usual way by giving a format on an actual dance link; if you want just the link and the dance name or replacement text, use

<<ddd:Braes of Breadalbane||%N>>

Ambiguous or Non-Existing Dances

Sometimes a dance name occurs several times in the database, or none at all. In the first case, ACE displays an ambiguous link such as

<<ddd:Anniversary Reel>>

like Anniversary Reel – which should make the problem fairly obvious. You can go to the desired dance in the database and add the greyish number to the right of the page header to the link like this:

<<ddd:Anniversary Reel#183>>

This results in an unambiguous link like Anniversary Reel.

If you'd rather not deal with funny numbers, you can also give the (last) name of the deviser like so:

<<ddd:Anniversary Reel@Muir>>

This also gives you an unambiguous link, like Anniversary Reel.

If a dance is not found at all, it shows up like this: The Nonexistent Reel

Cribs

It is possible to fetch cribs from DanceData's collection of cribs by using a magic link like

<<crib:Braes of Breadalbane>>

which gives

The Braes of Breadalbane

S32 · 3/4L · Thomas Skillern: RSCDS XXI 7 · DanceData entry
1-8
1s turn RH cast 1 place, turn LH & 1L casts up as 1M casts down to form lines of 3 across facing each other
9-16
1L+2s & 1M+3s set twice then 1s cast back to 2nd places & turn RH ending on own sides
17-24
2s+1s+3s set twice & turn partners 2H
25-32
2s+1s dance R&L
Crib accuracy is unknown · Source: MiniCrib

The same observations regarding dance names apply to cribs; if there is no crib available for a dance, a »crib-like object« is generated that does not contain an actual crib but at least gives the dance info and links to the corresponding page in DanceData:

The Vollmerz Square Eight

J128 · 4S · Anselm Lingnau: Nine Weddings (And No Funeral) · DanceData entry

Other Stuff from DanceData

It would be reasonable to make other classes of DanceData items (like entries for recordings, albums, or tunes) available in the same manner, but so far this hasn't happened – more out of sloth than anything else. Do let Anselm know if you would like to use such features, and stay tuned; we might add more of this sort of our own accord as we need it for the site(s).