“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

Markdown Images

You can add images to your ACE text pages by simply using standard Markdown syntax:

![St Andrews Castle](st-andrews.jpg "St Andrews Castle!")

The phrase between the square brackets is what your browser will display if the actual image, for whatever reason, cannot be shown; immediately after the left parenthesis there is the URL of the image on your web server (or wherever), while the quoted string to the left of the right parenthesis is “mouseover” text that your browser will display if you move the mouse over the image. (Which is why it’s called “mouseover”. Clever.)

This will make the image appear right in the middle of your text, or as a separate paragraph if you leave blank lines before and after it:

The standard Markdown method, however, gives you very little control about how the image should appear. With ACE, there is a much more nifty way of including images by way of a “magic link”. Read on!

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: – you see that the image is included right in the middle of the text, too. 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>>

This text also serves as the “mouseover” text.

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>>

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.

(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,

<<img:st-andrews-large.jpg|St Andrews Castle|right@t:200x100>>

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.)

Note that if the image already fits into the thumbnail box as it is (because it is very small to begin with), it will not be enlarged to fill the box. Instead, there will be white space to the right or below it.

If you’re only interested in a thumbnail and don’t want to do fancy mathematics, then

<<img:st-andrews-large.jpg|St Andrews Castle|right@t:200>>

will let you give just the width; the height will be calculated to keep the aspect ratio of the image constant. In our example, the image rendering code will figure out that the image is about 1.7 times as wide as it is high, and reasonably decide that if the width of the thumbnail box is supposed to be 200 pixels, the height of the thumbnail box should be 119 pixels.

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).

Images with Captions

Images can have captions that explain what the image shows, who took it, and what license it is under (the latter is mostly important to comply with Creative Commons licensing rules. For example,

<<img:st-andrews.jpg|caption="St Andrews Castle",by="Anselm Lingnau",
  license="CC BY-SA 4.0"|right>>

ACE tries to put in a link to the Creative Commons license grant if possible (i.e., if the license tag starts with “CC ” and the remainder is comprehensible).

Note that by default, the width of the included image will depend on that of the image itself and that of the caption (whichever is larger). If you want to make sure, use a thumbnail specification because that will force the width of the caption to be at most the width of the image:

<<img:st-andrews-large.jpg|caption="St Andrews Castle",by="Anselm Lingnau",
  license="CC BY-SA 4.0"|right@t:200>>

Captioned images don’t have a “mouseover” text because they already have a caption and presumably don’t need one.

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 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:

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).