VERC: Using Definition Pop-ups in your Collective Articles Last edited 3 months ago2024-09-09 18:23:55 UTC

The use of proper technical terminology in your article (also known as scary words to people not familiar with them) presents a dilemma for any VERC Collective author. Do I use the technical term? Will I need to explain what it means? Will it confuse my readers? Will any given explanation detract from my subject matter? And perhaps while the issue isn't really of great concern, there is a neat elegant solution available for all authors to exploit: the Collective pop-up. (and no, these aren't the type of popups that populate your desktop everytime you just happen to accidentally visit a pornographic site.)

Collective pop-ups are simply neat little windows that pop-up when you click on a word or phrase, which provide a definition of the term from the Collective's database. Click here for an example. They are ideal for terms like Leaf, Portal, Vertex, Binary Space Partition, and other such words or phrases that your reader may be unfamiliar with.

To create a link to a pop-up in your article, you should use the following special tag:

popup=keyword[description]popup

• keyword is the pop-up's unique keyword identifier or pop-up id (more information below).
• description is the term or phrase that you want to appear in your article. In the case of the above example, the description is "Click here for an example".

A pop-up's keyword identifies the popup to display. Obviously, in order to use a specific pop-up, you need to know its specific keyword. Currently, most of the pop-up keywords are documented in the Glossary of Terms article, beside each term in light grey font (note, that not all terms have pop-ups associated with them).

For example, if I were writing an article about the way the Half-Life engine worked, it would probably involve lots of technical terms, and I really can't be bothered structuring my article around interwoven explanations of these terms. Hence, if I wanted to link the term Leaf, I would first check the Glossary of Terms to get the pop-up id for that particular term. I would then use something similar to the following in my article: which would produce: and the effect is complete.

However, as popups use a special tag, the above is only applicable to articles written in text mode. Articles written in HTML mode will not be able to use the popup tag; authors will have to implement popups manually by linking their pop-up terms to the following address: (and if you don't know what that means or don't understand HTML, then you shouldn't be writing in HTML mode.)

When you preview your article, and test your popups, you might recieve the following message: While it is possible that I have forgotten to generate a particular pop-up, or have typo'ed a pop-up keyword (in which case please do email me or contact autolycus so the problem can be fixed!), the problem might also be at your end. Check to make sure that you have correctly entered the pop-up id (or keyword). Pop-up keywords are in general all lowercase with no spaces or strange symbols (with exception to the underscore).

As a final note, while Collective pop-ups are fine and dandy, don't feel the need to use them everywhere. Often, the first couple instances of a term in an article will be enough, and not every single term that can possibly be linked to a pop-up has to be. It is at your discretion, as an author that knows the target audience, how you use the resources at your disposal (of which, pop-ups are only one).