====== NP_ColorBox ====== NP_ColorBox is a simple plugin to add [[http://colorpowered.com/colorbox/|ColorBox]] functionality to Nucleus blogs. NP_ColorBox will automatically create a thumbnail of the image, and when clicked, will show the full size image in ColorBox style. Can also be used to display pages and other things in a colorbox window. ^General Plugin info ^^ ^Author: | [[http://revcetera.com/ftruscot/|Frank Truscott]], based on [[lightbox|NP_LightBox]] by [[http://www.mebluedragon.com/|Seventoes]] | ^Current Version: | 1.37 | ^Download: | [[http://revcetera.com/ftruscot/downloads/nucleus_plugins.html#colorbox|Here]]| ^Demo: | [[http://revcetera.com/ftruscot/plugins/colorbox_demo.html|Here]] | ^Forum Thread: |[[http://forum.nucleuscms.org/viewtopic.php?t=19276|Here]]| =====Installing===== - Unzip the file and upload the contents to your plugin directory - Install the plugin... - Add <%ColorBox%> to your skins, which will include all of the needed css/js files. If you want to keep your pages (X)HTML complient, keep that tag in your pages section. - Remember to edit the plugin's options to your needs, since NP_ColorBox will not work without the imageURL option set properly. =====How to use the plugin===== Using NP_ColorBox is very easy. To make an automatic thumbnail, and add colorbox functionality to an image, just follow this format while writing your post: ''<%ColorBox(//imagepath//|//Caption//|//boxtype//)%>'' The format used by Seventoes' NP_LightBox plugin is accepted as well: ''!~~imagepath|Caption|boxtype~~!'' **You must use Seventoes' format, in posts, if you use one of the parsing editor plugins like TinyMCE, WYSIWYG, bbcode, Markup, etc...** **You must use the standard nucleus tag format (<%ColorBox(...)%>) in skins, for all installs.** where: * //imagepath// is the path to the image relative to the imageURL option setting which defaults to your media directory. Optionally, as of 1.36, if you append a number, inside parentheses, to the end of the //imagepath// parameter, it will limit the thumbnails displayed, but not the set. For instance, //common/vacation(3)// would create a set of all the images in your media/common/vacation folder, but only the first 3 thumbnails will show (and be loaded) on your page. Appending //(0)// will keep all thumbnails from displaying. This is useful if you are creating a set using multiple individual images but only want certain ones to display a thumbnail on the page. If you need to show more than 100 thumbnails on a page, you will need to append a number higher than 100 (the default limit). It can also be the URL to an external image or page. * //Caption// is the caption you want used shown when a user hovers over the image. Optional, defaults to image filename. * //boxtype// is the type of object being displayed in the colorbox. The options are listed below. Required (but defaults to elastic). * **elastic** - elastic transition effect between images in set. Images displayed at actual size in colorbox. * **fade** - fade transition effect between images in set. Images displayed at actual size in colorbox. * **none** - no transition effect between images in set. Images displayed at actual size in colorbox. * **fixed_elastic** - elastic transition effect between images in set. Images resized to fit within colorbox at 75% of screen. * **fixed_fade** - fade transition effect between images in set. Images resized to fit within colorbox at 75% of screen. * **fixed_none** - no transition effect between images in set. Images resized to fit within colorbox at 75% of screen. * **slideshow_elastic** - elastic transition effect between images in slideshow. Images displayed at actual size in colorbox. * **slideshow_fade** - fade transition effect between images in slideshow. Images displayed at actual size in colorbox. * **slideshow_none** - no transition effect between images in slideshow. Images displayed at actual size in colorbox. * **iframe** - show an external page in a colorbox iframe taking 80% of the screen. * **colorbox** - show an external page in a colorbox iframe taking 100% of the screen. This can be used to display AJAX or flash pages. * **youtube** - show a youtube video inside a colorbox. Link to the video. No embed code required. The nucleus <%popup()%> behavior can also be replaced with NP_ColorBox according to a plugin option setting. This is disabled by default. Here's an example: ''<%Popup(img.jpg|200|100|Caption)%>'' Width and height are ignored, so you dont need them. Normal HTML image links may be replaced according to a plugin option setting. This is disabled by default. '''' The link's location must be the same as the image's source. =====Examples===== Here are some examples (assuming the imageURL plugin option is left as default media directory): ''<%ColorBox(myNewBaby.jpg|Isnt it cute?|fade)%>'' This shows a thumbnail of the image called myNewBaby.jpg in the media directory, with a caption of "Isn't it cute?". When the thumbnail is clicked, the regular sized image will be shown using the ColorBox effect. ''<%ColorBox(myNewBaby.jpg|Isnt she cute?|fixed_elastic)%>'' ''<%ColorBox(firstbath.jpg|Looking even cuter|fixed_elastic)%>'' ''<%ColorBox(bundledup.jpg|All cozy now|fixed_elastic)%>'' This will show thumbnails of the three images listed from the media directory, with their respective captions. When a thumbnail is clicked, a fixed sized image will be shown using the ColorBox effect. The user will be able to click Prev and Next links in the ColorBox window to navigate to the other images in the set. ''<%ColorBox(1/vacation/thehotel.jpg|Right on the ocean|none)%>'' This shows a thumbnail of the image called thehotel.jpg in the media/1/vacation directory, with a caption of "Right on the ocean". When the thumbnail is clicked, the regular sized image will be shown using the ColorBox effect. ''<%ColorBox(1/vacation|Right on the ocean|slideshow_fade)%>'' This will show thumbnails of all the files in the directory media/1/vacation. When a user clicks on a thumbnail, the regular sized image will be shown using the ColorBox slideshow with a fade effect between images. ''<%ColorBox(1/vacation(3)|Right on the ocean|slideshow_fade)%>'' (new in 1.36) This will show thumbnails of the first three files in the directory media/1/vacation. When a user clicks on a thumbnail, the regular sized image will be shown using the ColorBox slideshow with a fade effect between images. ''%%<%ColorBox(http://www.nucleuscms.org/|Nucleus CMS Home Page|iframe)%>%%'' This will show the Nucleus CMS Home Page in a colorbox comprising the 80% of the full available screen. Scrollbars are provided as needed. ''%%<%ColorBox(http://www.nucleuscms.org/|Nucleus CMS Home Page|colorbox)%>%%'' This will show the Nucleus CMS Home Page in a colorbox comprising the full available screen. Scrollbars are provided as needed. ''%%<%ColorBox(http://www.youtube.com/v/617ANIA5Rqs|Embedded youtube video|youtube)%>%%'' This will show the linked youtube video in a colorbox of dimensions 650px by 550px. =====Available SkinVars/TemplateVars===== ''<%ColorBox%>'' - Used to add required css and javascript files to pages. Put in the head section of your skins. ''<%ColorBox(scripts,//style_name//)%>'' - Advanced. Used to add required css and javascript files to pages. Put in the head section of your skins. Can be used to override the style set in the plugin options for the current skin. //style_name// is the name of the style to be used. ''<%ColorBox(//imagepath//|//Caption//|//boxtype//)%>'' - Used to add colorbox activated images and links in the skins =====Options===== **URL to your image folder** The URL to the base directory in which your images will be held. This option MUST be set correctly, or NP_ColorBox WILL NOT work. Defaults to your media URL and does not need to be changed for most installations. Must end with a trialing slash '/'. **Absolute filesytem path to your image folder** The full filesystem path to the base directory in which your images will be held. This option MUST be set correctly, or NP_ColorBox WILL NOT work. Defaults to your media directory path and does not need to be changed for most installations. Must end with a trialing slash '/'. **Relative filesytem path to your image folder** The relative filesystem path from the plugins/colorbox/ folder to the base directory in which your images will be held. This option MUST be set correctly, or NP_ColorBox WILL NOT work. Defaults to ../../../media/ and does not need to be changed for most installations. Must end with a trialing slash '/'. New in 1.3. **Which path should be used by thumbnail.php to find image files?** Which of the path methods above should be used by your thumbnail.php file to find the image files. Default to URL and should work for most cases. If the thumbnails appear as a black box with a red X, try one of the other methods. Relative is generally a better idea than Full for most cases. New in 1.3. **URL to your colorbox root directory** The URL to the base directory in which your colorbox files are installed (js and css). This option MUST be set correctly, or NP_ColorBox WILL NOT work. Defaults to your URL for this plugin's folder and does not need to be changed for most installations. Must end with a trailing slash '/'. **Name of folder in colorbox root directory containing styles for your colorbox** The folder name of the folder hoding the colorbox style you wish to use. The folders must reside in the colorbox root directory, usually nucleus/plugins/colorbox. Five styles are included, style1, style2, style3, style4, style5, but you can create your own, too. **Opacity of overlay layer** A percentage between 1 - 100 indicating the opacity level of the overlay layer. Defaults to 85. **Text to be displayed if no caption is provided** The text which should be displayed if no caption is provided. This option can be set to TB_imageName to show the image's filename. **Do you want to display thumbnails?** Whether or not to display thumbnails, if not, the caption will be displayed. Defaults to yes. If supported by your version of the PHP GD module, thumbnails can be generated for jpg, gif, png, and wbmp formats. **What is the maximum size for thumbnails?** The maximum size in pixels that thumbnails can be. The largest side of the image will be reduced down to this size. **Replace the default nucleus <%popup()%> behavior with colorbox?** Whether or not to replace nucleus <%popup%> behavoir with NP_ColorBox behavior. Defaults to no. **Replace normal image links with colorbox?** Whether or not to replace normal HTML image links with NP_ColorBox behavior. =====Compatibility===== If you use a WYSIWYG, TinyMCE, Markup, BBCode, or other item parsing plugin to format your posts, you will need to use the !~~imagepath|Caption|setname|boxtype|width|height~~! syntax for this plugin. Otherwise, you will see errors including Disallowed(...) instead of your images. (Thanks, danielck). Also, if you use a skin that employs the nicetitle.js script (such as the default skin), the images will display fine, but the captions will not display with your images. If the captions are important, you will need to remove the call to nicetitle.js in the head.inc of your skin, or shoose a skin that doesn’t use this script. It may conflict with the javascripts behind NP_LightBox2 , NP_ThickBox, and NP_GreyBox, so you may not be able to use these plugins together in the same skin. There may be other compatibility issues with skins (like Laila) that use a title attribute in the link tag calling the main css file. There may also be conflicts with other javascript files. **The Thumbnail feature will not work if your site hotlink protection enabled, unless the direct requests are allowed.** Please report any other compatibility issues to the forum thread for discussion: [[http://forum.nucleuscms.org/viewtopic.php?t=19276|Forum Thread]]. If you are getting scrollbars on your images, it is likely that something in your site's CSS is adding border, margin, or padding to the images. The nonzero skin has this issue. You can probably fix it by adding this to your site's CSS file (near the bottom): #cboxPhoto{ border:0px none; margin:0px; padding:0px; } =====Wishlist===== * =====Bugs===== * =====History===== * Version 1.37 10/19/2009 - initial release. Versioned to match NP_LightBox2 ===== Plugin review ===== NP_ColorBox version 1.37 works with Nucleus CMS version 3.50 - 2009-10-20 ftruscot