Issue #1933956 by frjo | davidd07: Behaviors Attach and cbox_complete.
[project/colorbox.git] / README.txt
1 Drupal colorbox module:
2 ------------------------
3 Maintainers:
4   Fredrik Jonsson (http://drupal.org/user/5546)
5 Requires - Drupal 7
6 License - GPL (see LICENSE)
7
8
9 Overview:
10 --------
11 Colorbox is a light-weight, customizable lightbox plugin for jQuery 1.4.3+.
12 This module allows for integration of Colorbox into Drupal.
13 The jQuery library is a part of Drupal since version 5+.
14
15 Images, iframed or inline content etc. can be displayed in a
16 overlay above the current page.
17
18 * jQuery - http://jquery.com/
19 * Colorbox - http://www.jacklmoore.com/colorbox/
20
21
22 Features:
23 ---------
24
25 The Colorbox module:
26
27 * Excellent integration with Image field and Image styles
28 * Choose between a default style and 5 example styles that are included.
29 * Style the Colorbox with a custom colorbox.css file in your theme.
30 * Drush command to download and install the Colorbox plugin in
31   sites/all/libraries
32
33 The Colorbox plugin:
34
35 * Supports photos, grouping, slideshow, ajax, inline, and iframed content.
36 * Appearance is controlled through CSS so it can be restyled.
37 * Preloads upcoming images in a photo group.
38 * Completely unobtrusive, options are set in the JS and require no
39   changes to existing HTML.
40 * Compatible with: jQuery 1.3.2+ in Firefox, Safari, Chrome, Opera,
41   Internet Explorer 7+.
42 * Released under the MIT License.
43
44
45 Installation:
46 ------------
47 1. Download and unpack the Libraries module directory in your modules folder
48    (this will usually be "sites/all/modules/").
49    Link: http://drupal.org/project/libraries
50 2. Download and unpack the Colorbox module directory in your modules folder
51    (this will usually be "sites/all/modules/").
52 3. Download and unpack the Colorbox plugin in "sites/all/libraries".
53     Make sure the path to the plugin file becomes:
54     "sites/all/libraries/colorbox/jquery.colorbox-min.js"
55    Link: https://github.com/jackmoore/colorbox/archive/1.x.zip
56    Drush users can use the command "drush colorbox-plugin".
57 4. Go to "Administer" -> "Modules" and enable the Colorbox module.
58
59
60 Configuration:
61 -------------
62 Go to "Configuration" -> "Media" -> "Colorbox" to find
63 all the configuration options.
64
65
66 Use the Views Colorbox Trigger field:
67 ------------------------------------
68 TODO
69
70
71 Add a custom Colorbox style to your theme:
72 ----------------------------------------
73 The easiest way is to start with either the default style or one of the
74 example styles included in the Colorbox JS library download. Simply copy the entire
75 style folder to your theme and rename it to something logical like "mycolorbox".
76 Inside that folder are both a .css and .js file, rename both of those as well to match
77 your folder name: i.e. "colorbox_mycolorbox.css" and "colorbox_mycolorbox.js"
78
79 Add entries in your theme's .info file for the Colorbox CSS/JS files:
80
81 stylesheets[all][] = mycolorbox/colorbox_mycolorbox.css
82 scripts[] = mycolorbox/colorbox_mycolorbox.js
83
84 Go to "Configuration" -> "Media" -> "Colorbox" and select "None" under
85 "Styles and Options". This will leave the styling of Colorbox up to your theme.
86 Make any CSS adjustments to your "colorbox_mycolorbox.css" file.
87
88
89 Load images from custom links in a Colorbox:
90 --------------------------------------------
91
92 Add the class "colorbox" to the link and point the src to the image
93 you want to display in the Colorbox.
94
95
96 Load content in a Colorbox:
97 ---------------------------
98 Check the "Enable Colorbox load" option in Colorbox settings.
99
100 This enables custom links that can open content in a Colorbox.
101 Add the class "colorbox-load" to the link and build the url like
102 this "[path]?width=500&height=500&iframe=true"
103 or "[path]?width=500&height=500" if you don't want an iframe.
104
105 Other modules may activate this for easy Colorbox integration.
106
107
108 Load inline content in a Colorbox:
109 ----------------------------------
110 Check the "Enable Colorbox inline"  option in Colorbox settings.
111
112 This enables custom links that can open inline content in a Colorbox.
113 Inline in this context means some part/tag of the current page, e.g. a div.
114 Replace "id-of-content" with the id of the tag you want to open.
115
116 Add the class "colorbox-inline" to the link and build the url like
117 this "?width=500&height=500&inline=true#id-of-content".
118
119 It could e.g. look like this.
120
121 <a class="colorbox-inline" href="?width=500&height=500&inline=true#id-of-content">Link to click</a>
122
123 <div style="display: none;">
124 <div id="id-of-content">What ever content you want to display in a Colorbox.</div>
125 </div>
126
127 Other modules may activate this for easy Colorbox integration.
128
129
130 Drush:
131 ------
132 A Drush command is provides for easy installation of the Colorbox
133 plugin itself.
134
135 % drush colorbox-plugin
136
137 The command will download the plugin and unpack it in "sites/all/libraries".
138 It is possible to add another path as an option to the command, but not
139 recommended unless you know what you are doing.
140
141
142 Image in Colorbox not displayed in Internet Explorer 8:
143 -------------------------------------------------------
144
145 If your theme has CSS like this (popular in responsive design):
146
147 img {
148   max-width: 100%;
149 }
150
151 Internet Explorer 8 will have problems with showing images in the Colorbox.
152 The fix is to add this to the theme CSS:
153
154 #cboxLoadedContent img {
155   max-width: none;
156 }
157