This section discusses the basic boxplus syntax in Joomla as well as tips and tricks with boxplus.
Embedding boxplus with an activation tag
The boxplus activation tag has the following syntax:
{boxplus param1=value1 param2="value2" /}
{boxplus param1=value1 param2="value2"}text or HTML content{/boxplus}
The activation tag is either a compact tag (first line) or a regular tag (second line). The compact tag is used to override configuration settings defined in the Joomla administration back-end that applies to the article the tag is in. The regular tag is used to place links that open in a boxplus pop-up window but with passing along parameters that apply to that instance of the pop-up window only. For example, the activation tag
{boxplus theme=lightsquare href=image.jpg}Link text{/boxplus}
is transformed into a regular hyperlink Link text, or in code
<a id="boxplus001" href="/levente/image.jpg">Link text</a>
which invokes the boxplus window when clicked. Unlike a regular link, however, this hyperlink has dedicated settings embedded into the page head such that the window is displayed with the light square theme even if another theme is configured as the default in the administration back-end.
Important: You must have either the regular tag or the compact tag on a page to have boxplus activated. The Joomla plug-in dispatcher invokes enabled plug-ins one after the other and each content plug-in decides when it is called whether it wants to process the article being displayed. This saves processing time as plug-ins like boxplus activate only if they have to. If boxplus finds no activation tag on a particular page, it will short-circuit and never register its initialization routines, and no link will be transformed into a boxplus-enabled link, even if it has the rel attribute value boxplus. If you want to use boxplus without passing any parameters then just write
{boxplus /}
When you pass the rel attribute in the activation tag, settings from tags that share the same rel attribute are combined, and the items are displayed as a gallery. The following example illustrates the point:
{boxplus rel=example href="/levente/image1.jpg" theme=lightsquare}First image{/boxplus}
{boxplus rel=example href="/levente/image2.jpg" autofit=false}Second image{/boxplus}
{boxplus rel=example href="/levente/image3.jpg" autocenter=false}Third image{/boxplus}
These links are then formatted as follows: First image, Second image and Third image. Observe how the light square theme is applied and that neither is the pop-up window re-sized to fit a small browser window, nor is it re-centered when you scroll the page with the mouse.
Tips and tricks
Compatibility with sigplus
The stand-alone extension boxplus and sigplus 1.4.x do not get along well. This is because stand-alone boxplus ships with a more recent boxplus engine version (called boxplus for MooTools) whereas sigplus 1.4.x ships with a less recent version (called boxplus for jQuery). However, both sigplus 1.4.x and the next-generation series 1.5.x support viewing single images if you put a full reference to an image file (extension included) in between the activation start and end tags. In addition, sigplus 1.5.x supports the activation tag which gives direct access to the underlying boxplus pop-up window implementation, essentially acting as a full substitute for the stand-alone extension boxplus, supporting videos, locations on a map, web pages, etc. Usage of the activation tag {lightbox} with the boxplus engine integrated in sigplus 1.5.x is illustrated with a couple of examples below.
The first example uses a relative link and shows how to display a single image:
{lightbox href="/levente/images/sampledata/parks/landscape/800px_pinnacles_western_australia.jpg"
title="Description of image"}Link to an image
The second example uses an absolute URL and illustrates how to show a YouTube video:
Link to a video
The third example shows how to display a location with Google Maps:
Link
The compatibility issue arises only if you use boxplus and sigplus 1.4.x on the same page. If you have such a setup, you might want to consider switching to sigplus 1.5.x so that you use one extension for both purposes. (Please note that sigplus 1.5.x is currently officially in beta even though it is generally stable.)
Displaying a pop-up window when the page loads
boxplus can display any content when the page loads it can normally display inside the lightbox pop-up window. As an example, consider the following code snippet placed in the head section of the HTML page:
<script type="text/javascript"><!--
window.addEvent("load", function () {
new boxplus(new Element('a', {
href: "http://www.adobe.com/products/flashplayer/include/marquee/design.swf?width=792&height=294"
})).show();
});
// --></script>
The code above registers a new event handler to be fired when the page has finished loading. The handler creates a new anchor (a) element that is not attached to the document, and assigns a href attribute to the anchor that points to a Flash resource (extension .swf). The dimensions required to display the Flash movie are passed in the URL query parameters width and height. The boxplus window is then initialized using the anchor. Finally, the show() method displays the window.