What is a custom link?
How is a custom link created?
A Practical Application: Light box Popups
What can light boxes do for me?
How do I use this code?
Live Demo and Download
Creating the Light box Links
Example Links
Note: This approach is now considered out-of-date, and its documentation is kept here mainly to support customers already using it. If you are looking to create a new set of light boxes and have not already started with this approach, you would be better served by our directly built-in light box functionality. You may find an overview of all three light box solutions we offer in this article:
Lightbox Solutions Overview
This solution is requires use of the Zmags Embedded Viewer API. It assumes that readers have general knowledge of embedding the viewer already. If this is not the case, feel free to click the link above for more information. It allows for customizing each light box size and appearance individually, and works with both the Standard and VERGE viewer.
What is a custom link?
A custom link is a special kind of link created in Zmags Enriched which is able to pass variables to Javascript in the HTML page your publication is embedded in. This usually involves passing a standard URL as well as several other parameters such as 'width' or 'height'.
How is a custom link created?
1) Log into the Zmags Publicator and go to "All Publications".
2) In the 'Enriched' column, click on the icon 
to the right of your publication.
3) Click the link icon 
on the left, and then select "external link".
4) Draw a link box and set appearance settings (opacity, color, etc) as normal.
5) In the "URL:" field at the top, create a link using the following format:
{url=www.website_address.com&var1=1&var2=2&var3=3}
6) In the "Open link in" drop-down menu, select "Custom". To the right of that, type a target in the box. (By default, you will leave this as "_blank".)
7) Click "File" > "Save All".
In the URL format above, the "website_address" should be the destination of your link, and the variables "var1", "var2", and so on are custom parameters to be passed to the embedded viewer page.
A Practical Application: Light box Popups
One of the most common and useful things done with these custom links is the creation of light box popups. These are boxes that pop up on top of the rest of the page and contain HTML content from an outside source. They look something like this:
What can light boxes do for me?
Some useful applications of using light box links include:
- Load images from another page, such as elsewhere on your website.
- Embed HTML elements such as contact forms and surveys.
- Embed product information pages with text, images, and external links.
- Embed external videos from YouTube and other providers in your publication.
- Directly load other file types that can be understood by a web browser, such as TXT.
Almost any HTML page can be loaded into a light box to be called up upon clicking a light box link, which itself can take the form of text, image, or a flash call-to-action.
Live Demo and Download
Click here to view the example in action!
Click here to download the example code.
Click here to download the example product windows.
Note: The full-screen button is not compatible with this solution, as light box popups will appear below the full-screen layer. This is unfortunately a limitation of Flash which is not possible to correct at this time. One workaround is to use a Javascript-Based Fullscreen solution instead.
Note: Android 2.3.x devices are not fully supported at this time, but that functionality is on the way!
How do I use this code?
Setting these light boxes up on your own publications is a relatively straightforward process, but you will require access to a web server:
1) Download the example code above.
2) Right-click (or command-click on a Mac) the .zip file and extract it.
3) Open up "index.html" with your favorite text editor, and follow the instructions near the top of the document. At the minimum, you will need to edit the "publicationID" line so that it matches the ID of your own publication. (Found in the Zmags Publicator; click on the publication in the "All Publications" list.) Save the file when finished.
4) Place both the "index.html" file and the "cslf_files" folder in the same location on your website.
5) The code is now enabled on your website! Next you'll need to create light box links in your publication.
Creating the Light box Links
To create light box links, follow the procedure for creating custom links above, but use the following (more specific) formats. In all cases, use "Custom" and "_blank" for the "Open window in" setting.
For regular links:
{url=http://www.YOUR_URL_HERE.com&width=YOUR_WIDTH&height=YOUR_HEIGHT}
In this and all other light box links, "width" and "height" are what define the size in pixels of the light box popup.
For YouTube links:
{url=http://www.youtube.com/embed/YOUTUBE_ID_HERE?html5=1&width=YOUR_WIDTH&height=YOUR_HEIGHT}
The "YouTube ID" can be found at the end of the URL when viewing the viddeo on youtube. It is a 11-character long string of numbers, letters, and symbols. Typical dimensions for a YouTube light box is 640 x 480.
Click-based Positioning:
It is also possible to create links which instead of centering on the screen will base their position on where the mouse was when you clicked it. This currently only works on the flash viewer however, not the mobile / HTML5 viewer. Simply tack &pos=1 onto the end of any regular or YouTube link, like so:
{url=http://www.YOUR_URL_HERE.com&width=YOUR_WIDTH&height=YOUR_HEIGHT&pos=1}
Predefined Coordinate Positioning:
An alternative which does work on all viewers is predefined positioning. In addition to adding &pos=1, simply add &top=Y and &left=X as well, where X and Y are swapped out for the position (in pixels) you want the upper-left corner of the light box to be located:
{url=http://www.YOUR_URL_HERE.com&width=YOUR_WIDTH&height=YOUR_HEIGHT&top=Y&left=X&pos=1}
Example Links
Assuming you are using the example product windows, and their folder is located in the same place as "index.html" and "cslf_files" on your server, here is the links you would use to recreate the light boxes you saw in the live demo earlier:
YouTube: {url=http://www.youtube.com/embed/3FIkvzI6bp0?html5=1&width=640&height=480}
Contact Us: {url=./DPWs/contactform.html&width=400&height=270}
Buy Now: {url=./DPWs/cereal.html&width=450&height=450}
View Image*: {url=../DPWs/cheetah-picture.jpg&width=625&height=450}
Text File: {url=./DPWs/loremipsum.txt&width=450&height=450}
Slideshow: {url=./DPWs/slideshow&width=480&height=300}
Click-based Positioning*: {url=../DPWs/computer.png&width=250&height=250&pos=1}
Predefined Coordinate Positioning*:
{url=../DPWs/computer.png&width=250&height=250&top=100&left=200&pos=1}
{url=../DPWs/computer.png&width=250&height=250&top=400&left=400&pos=1}
{url=../DPWs/computer.png&width=250&height=250&top=600&left=300&pos=1}
* Note the second period at the start of the URL for these. This is because direct image links are run through the "image loader", which is a folder lower than the index.html file. We use ".." to mean "parent folder" rather than "." to mean "this folder".