PMK Shadowbox

Copyright © by Peter Klein, Stefan Galinski <pmk@no spam pleaseio.dk>
Published under the Open Content License available from http://www.opencontent.org/opl.shtml

Table Of Contents

• 1. EXT: PMK Shadowbox
  • 1.1. Shadowbox is licensed under version 3.0 of the license. This means that it is absolutely free for personal, noncommercial use provided that you 1) make attribution to the author and 2) release any derivative work under the same or a similar license.
  • 1.2. If you would like to use Shadowbox for commercial purposes, you can purchase a license ($20) that allows you to use Shadowbox in your projects. See for more details.
  • 1.3. Read online
  • 1.4. Introduction
    • What Does It Do?
  • 1.5. The extensions integrates the shadowbox from Michael J. I. Jackson into TYPO3. As a result you can open specially marked links and images with an enabled click-enlarge option into a shadowbox. We don't use any dirty Xclassing for reaching this goal. It's completely configurable by typoscript and it's developed to be very performant in each setup.
    • Shadowbox Overview
  • 1.6. Shadowbox is an online media viewer application (Lightbox clone) that supports all of the web's most popular media publishing formats. Shadowbox is written entirely in JavaScript and CSS and is highly customizable. Using Shadowbox, website authors can showcase a wide assortment of media in all major browsers without navigating users away from the linking page.
    • Shadowbox Features
  • 1.7. What sets Shadowbox apart from every other "box" out there?
  • 1.8. Standards
  • 1.9. Shadowbox uses HTML markup that validates. It doesn't depend on phony HTML attributes in your anchor tags to make it work. The web has enough problems with standards compliance as it is and Shadowbox does its best to not perpetuate them.
  • 1.10. Free from Frameworks
  • 1.11. Although Shadowbox has the unique ability to adapt to whatever JavaScript framework you choose, it's just as easy to run it as a standalone application, giving the developer a great deal of flexibility.
  • 1.12. Flexible
  • 1.13. Shadowbox supports all of the web's most popular media publishing formats including images, QuickTime, Windows Media Player, Flash, FLV, HTML, and even external web pages. This makes it easy to display your content, no matter what it is.
  • 1.14. Smart
  • 1.15. Shadowbox uses a smart plugin detection mechanism behind the scenes that can spare your users from confusing torn image or puzzle piece icons when they don't have the plugins they need to view your content. Also, it will never overflow the viewport, forcing those obnoxious scrollbars.
  • 1.16. Customizable
  • 1.17. Shadowbox supports a host of options that make it highly configurable. If you don't like the way something works, chances are very good that you can change it without digging through the code.
  • 1.18. Universal
  • 1.19. Shadowbox ships with support for many of the world's most-spoken languages, and it's not difficult to configure Shadowbox to communicate with your visitors in their native tongue.
  • 1.20. Neat and Compact
  • 1.21. The Shadowbox code is neat and modular. And it's smart enough to only include the code you need to run your application so it's as light weight as possible.
  • 1.22. Plays Well with Others
  • 1.23. Shadowbox tries to be as unobtrusive as possible. If your client doesn't have JavaScript enabled, it will stay completely out of the way and allow the page to function normally.
    • Browsers
  • 1.24. Shadowbox supports the following browsers:
  • 1.25. Read online
    • Shadowbox Licence
  • 1.26. The shadowbox is free for non-commercial projects, but anyone else must pay for the usage. The code shouldn't be distributed on your own. We got a special permission from Michael J. I. Jackson, the author of the Shadowbox script, to redistribute the shadowbox code with the PMK Shadowbox TYPO3 extension.
  • 1.27. Further details on the licencing issues can be found in the file.
    • Screenshots
  • 1.28. The above picture shows 4 pictures inserted with the standard TYPO3 “Image” element.
  • 1.29. The above picture is a screenshot of how the ShadowBox looks when you click on one of the images.
  • 1.30. Users manual
  • 1.31. Nothing new is available to the user, as the extension just changes the way the click-enlarge function works.
  • 1.32. Administration
  • 1.33. Once the extension is installed, you need to include the static TypoScript of the extension, in order for the ShadowBox script to be activated. Also you should include the click-enlarge script that activates the shadowbox to show enlarged images inside such a nice box.
  • 1.34. Note: Add the “ShadowBox (pmkShadowbox)” script AFTER “CSS Styled Content (css_styled_content)”
  • 1.35. There are two additional PMK Shadowbox static templates. One for tt_news integration, and one for tt_products integration. These must be added AFTER the main PMK Shadowbox static template, otherwise it won't work correctly.
    • How does it work?
  • 1.36. This extension is done using only TypoScript. The TypoScript code for integration Shadowbox in TYPO3 is located in page.headerData.1229 to page.headerData.1233. So make sure your own code and other extensions doesn't overwrite this location.
  • 1.37. The page header informations are splitted in many small pieces to simplify the possible replacement of the css or javascript files. At least a replacement of the final build javascript file shouldn't be that important, because we are generating the build javascript file for shadowbox on-the-fly. Each time you change a configuration option that changes the final javascript, like players or the adapter, we regenerate a new build file. If you need to manually delete the files, you can use the new clear cache menu entry in the tobbar of the  TYPO3 backend.
  • 1.38. For more information on how the shadowbox javascript is working, I suggest  you visit the official homepage:
    • Markup
  • 1.39. After you have installed and configured the PMK shadowbox extension, images will automatically open in the shadowbox if the click-enlarge option is enabled. If you want to use shadowbox on links you generate yourself, you need to tell shadowbox which links you want it to open. The simplest way to do this is through your HTML markup. If you're going to take this route, at the very least you must add a rel="shadowbox" attribute to each link. For example, say you have this link to an image on your page:
  • 1.40. <a href="myimage.jpg">My Image</a>
  • 1.41. Read online
  • 1.42. In order to set up this link for use with Shadowbox, simply change it to this:
  • 1.43. <a href="myimage.jpg" rel="shadowbox">My Image</a>
  • 1.44. That's it! Clicking on this link should now open up the image in Shadowbox.
  • 1.45. NOTE: The word lightbox will also work here. This feature was added for compatibility with the original Lightbox script. Also note that HTML area tags do not support the rel attribute, you cannot use this method to set them up for the usage with Shadowbox. Instead, use Shadowbox.setup as described below.
  • 1.46. If you would like to display a title for your image, simply add a title attribute to the link.
  • 1.47. <a href="myimage.jpg" rel="shadowbox" title="My Image">My Image</a>
  • 1.48. Read online
  • 1.49. You must explicitly tell Shadowbox the dimensions to use to display content other than images. This is done by adding a few parameters to the end of the rel attribute, separated by semi-colons. To specify a movie's height and width (in pixels), use the height and width parameters.
  • 1.50. <a href="mymovie.swf" rel="shadowbox;height=140;width=120">My Movie</a>
  • 1.51. Read online
  • 1.52. Additionally, you may set Shadowbox options on a per-link basis. To do this, you must include a JSON-formatted parameter called options.
  • 1.53. <a href="myimage.jpg" rel="shadowbox;options={animate:false}">My Image</a>
  • 1.54. Read online
  • 1.55. In addition to displaying single images and movies, Shadowbox is also capable of displaying galleries of content. In order to designate a link as part of a gallery, you must add the gallery name to the rel attribute between square brackets immediately following the word shadowbox. The following markup creates a gallery called "Vacation" with two pictures.
  • 1.56. <a href="beach.jpg" rel="shadowbox[Vacation]">The Beach</a>
  • 1.57. <a href="pier.jpg" rel="shadowbox[Vacation]">The Pier</a>
  • 1.58. Galleries may be composed of content of many different types. The following markup demonstrates how various media can be combined into a single gallery.
  • 1.59. <a rel="shadowbox[Mixed];" href="vanquish.jpg">jpg</a>
  • 1.60. <a rel="shadowbox[Mixed];width=520;height=390" href="caveman.swf">swf</a>
  • 1.61. <a rel="shadowbox[Mixed];width=292;height=218" href="kayak.mp4">movie</a>
  • 1.62. <a rel="shadowbox[Mixed]" href="index.html">iframe</a>
    • Advanced
  • 1.63. If you don't want to add to your markup, you don't have to. Shadowbox may be manipulated with pure JavaScript. This use is slightly more complex, but it has several benefits including the fact that your HTML markup will be cleaner and you can more easily integrate Shadowbox into an existing project.
  • 1.64. If you were paying attention in the section about markup, you'll notice that there are several parameters that commonly accompany Shadowbox content. These parameters are listed in the table below.
  • 1.65. Read online
  • 1.66. When using the markup method, each of these options may be present in one form or another. A link's gallery name, height, and width may all be configured within the link's rel attribute. Similarly, its title is contained in the title attribute and the content value defaults to the link's href. The content type is then derived from the extension on the linked file.
  • 1.67. Configuration
  • 1.68. All configuration of the extension is done using TypoScript constants. Use the “Constants Editor” of TYPO3 to change these options. You can change things like the transitions, sizes, colors and many more.
    • Reference
    • Read online
    • Additional Reference (tt_content; Click-Enlarge)
  • 1.69. If the static template for implementing Shadowbox in tt_content (Click-Enlarge) is installed, the following extra constants are available:
    • Additional Reference (tt_news)
  • 1.70. If the static template for implementing Shadowbox in tt_news is installed, the following extra constants are available:
    • Additional Reference (tt_products)
  • 1.71. If the static template for implementing Shadowbox in tt_products is installed, the following extra constants are available:
  • 1.72. Tutorial
    • How to change the images?
  • 1.73. The layout of the shadowbox window is template based, so you can create your own HTML/CSS template, and get the window to look exactly like you want. See the official Shadowbox homepage for more information on how to create your own skins or look into the skin modifications in the resources directory of this extension.
    • How to open another page inside the ShadowBox?
  • 1.74. This is quite simple, all you have to do is add a REL attribute to the A tag. This can be done like this in typoscript:
  • 1.75. lib.myLink = TEXT
  • 1.76. lib.myLink {
  • 1.77. value = This link opens in a Shadowbox
  • 1.78. typolink {
  • 1.79. parameter = 1
  • 1.80. ATagParams = rel="shadowbox;plugin=iframe;width=600;height=400"}}
    • How to use SB on links created in HTMLArea RTE?
  • 1.81. It is possible to “fool” the HTMLArea RTE into opening links inside the Shadowbox, by adding the rel=”shadowbox” attribute to the title parameter in the link popup window.
  • 1.82. To do this you must add the the title like this:
  • 1.83. title" rel="shadowbox;plugin=iframe;width=600;height=400
  • 1.84.  
  • 1.85. Note: When you edit the link again, the title field will be “cleaned” of the extra parameter, and only show the title.
    • How to use SB on links created in TinyMCE RTE?
  • 1.86. If you use the TinyMCE RTE, then there's a patch in TinyMCE RTE you can apply. After the patch is applied, you can set the rel=”shadowbox” directly from the TinyMCE linkhandler.
    • How to get Shadowbox to work in tt_content (Click-Enlarge)?
  • 1.87. Just install the additional static template “tt_content (Click-Enlarge).
    • How to get Shadowbox to work in tt_news?
  • 1.88. Just install the additional static template “PMK Shadowbox (tt_news).
  • 1.89. Then an extra set of constants will be available in the “Constants Editor”, where you can choose in which tt_news views the images should be display inside the Shadowbox.
  • 1.90. You can also choose if you want the tt_news singleView displayed inside the Shadowbox, using the “Constants Editor”.
    • How to get Shadowbox to work in tt_products?
  • 1.91. Just install the additional static template “PMK Shadowbox (tt_products).
  • 1.92. Then an extra set of constants will be available in the “Constants Editor”, where you can choose in which tt_products views the images should be display inside the Shadowbox.
    • How to enhance the Shadowbox functionality
  • 1.93. You can enhance the Shadowbox functionality using the functions “onOpen”, "onFinish", "onChange" & "onClose" functions.
  • 1.94. Due to the way TYPO3 handles () {} brackets, it is not possible to insert the JavaScript functions directly into the typoscript setup. Instead you should create your JavaScript function in a separate file, and then enter the function name in the typoscript constants/setup.
  • 1.95. Example javascript function which will perform a check on the browserheight before opening an HTML page inside the Shadowbox.
  • 1.96. If the Browser height is less than 400px, then the page will open in a new browserwindow instead of opening inside the Shadowbox.
  • 1.97. function checkBrowserHeight() {    if (Shadowbox.getCurrent().player == "iframe" && $(window).height()<400) {        window.open(Shadowbox.getCurrent().content,"shadowbox");        return false;    }}
  • 1.98. Then in the Shadowbox constants/setup you set the “onOpen” function to point to the JavaScript function above, like this:
  • 1.99. plugin.pmkshadowbox.onOpen = checkBrowserHeight
  • 1.100. Read online
  • 1.101. Note: The above example requires jQuery installed.
  • 1.102. Known problems
  • 1.103. The Javascript and CSS gets loaded into the typoscript object/properties “page.headerData.1229” to “page.headerData.1233”, so if you are using that for something else, you have to include the javascript and CSS manually. The same applies if you don't use the “page” object.
  • 1.104. PMK Shadowbox conflicts with the following TYPO3 extensions and possibly many more. Please send us a small note if you think that this list is incomplete. Thanks!
  • 1.105. Read online
  • 1.106. To-Do list
  • 1.107. Please contact us if you have any suggestion about this extension or report the suggestion at our .
  • 1.108. ChangeLog
  • 1.109. Read online

This document is related to version 3.2.1 of the extension pmkshadowbox.