Created: 15/04/2011
By: Nilok Bose
Email: cosmocoder@gmail.com
Thank you for purchasing my item. If you have any questions that are beyond the scope of this help file, please feel free to email via my user page contact form here. Thanks so much!
CCGallery is a HTML5 multimedia gallery. It is very simple to use and can be configured easily through a XML file. It acts as a template which displays all your images, audio files and video files in a sleek and attractive interface. You get to browse the items in Coverflow mode or in a Thumbnail grid mode. You can easily switch between the two display modes and can even filter the items by displaying only images, or audio files, or video files. As of version 1.3 filtering of items by custom categories is also supported. Also as of version 2.0 CCGallery incorporates a responsive design so that the gallery display fits in various screen sizes ranging from mobile phones to desktop browsers. The gallery features full touch-screen support which is noted especially in the Coverflow mode. CCGallery has been designed in such a way that it is extremely easy to browse through a large number of items and also with enough eye candy!
Please note that as of version 4.0 CCGallery utilises CSS 3D Transforms in browsers that support this feature to produce the Coverflow mode. This results in smooth animation which is especially noticeable in mobile devices such as iPhone/iPad. Currently CSS 3D Transforms are supported in Firefox 12.0+, Chrome 20.0+, Safari 5.1+, iOS 3.2+, Android 3.0+. If the browser does not support 3D Transforms then the gallery will use HTML5 Canvas for the Coverflow effect. Currently browsers that support Canvas include Firefox 3.0+, Safari 3.0+, Chrome 3.0+, Opera 9.5+ and IE9+. Internet Explorer 6, 7 and 8 do not support Canvas. Browsers which do not support Canvas will see a fallback animated effect when browsing files in the Coverflow mode. Hence visitors to your web page using old browsers will still see a nicely working gallery. The Thumbnail mode works in almost all browsers.
If you want to test this item locally then keep one thing in mind. Both Chrome and Safari have some security restrictions which does not allow the use of images in Canvas when operated locally. If you want to see the Coverflow mode in action in Chrome/Safari then you have to run the gallery from a server. A local server environment like XAMPP, MAMP, WAMP or LAMP will do very well. There are no such complications in Firefox and Opera. There also appears to be another restriction on Chrome, Safari and Opera and that is that they do not allow AJAX requests to be performed locally. The AJAX request is required to gather information from the XML file. There are no such problems in Firefox. So in summary if you want to test the gallery locally then your best bet is Firefox, otherwise you have to run the gallery from a server.
To use CCGallery first you have to fill out the XML file. That file will contain links to your thumbnail images, large images, audio files, video files and titles and descriptions for each file. An example block of code is below:
<file type="photo"> <cover>media/photos/covers/photo-cover.jpg</cover> <thumb>media/photos/thumbs/photo-thumb.jpg</thumb> <source>images/largeImage.jpg</source> <title>Photo example</title> <description>A short description of the photo</description> </file> <file type="audio"> <cover>media/audios/covers/audio-cover.jpg</cover> <thumb>media/audios/thumbs/audio-thumb.jpg</thumb> <source>media/audios/audio-file.ogg</source> <source>media/audios/audio-file.mp3</source> <title>Audio example</title> <description>A short description of the audio piece</description> </file> <file type="video"> <cover>media/videos/covers/video-cover.jpg</cover> <thumb>media/videos/thumbs/video-thumb.jpg</thumb> <source>media/videos/video-file.mp4</source> <source>media/videos/video-file.webm</source> <source>media/videos/video-file.ogv</source> <title>Video example</title> <description>A short description of the video clip</description> </file>
In the above code block it has been illustrated how to configure all three file types for the gallery. The usage of each tag in the code block is explained below.
<file>
The file tag must have the attribute type, which must be set equal to photo if the file is an image. The other available values are obviously audio and video.
<cover>
Here you must mention the path of the image that will be used in the Coverflow mode. Images used for Coverflow can be of different sizes, but for better performance please try to keep the image dimensions to no larger than around 200px × 200px.
<thumb>
Here the path for the thumbnails to be used in the Thumbnail mode has to be mentioned. These thumbnails have to be of fixed size and that size is 200px × 150px. Please note that you can change the dimensions of the thumbnails according to your needs by editing the gallery css file.
<source>
This tag contains the path to the large version of the image which will be displayed in a modal overlay box. In case of audio and video files there can be multiple
<source> tags. This is because different browsers need different formats to play HTML5 audio and video natively. For audio you can provide a mp3 file
and an ogg file. For video you can provide mp4, or webm or ogv files. For details on which audio and video files to include please see the next section.
<title>
Enter the title of the item in this tag which will be displayed in the gallery.
<description>
Here you have to enter a short description (like a caption) of the item.
If you need to enter special characters in your title and description tags like & or / then don't enter them as such. If you just enter special characters in these tags then the browser will fail to parse the XML file and thus your gallery will not be loaded and displayed. To avoid this scenario you must wrap the content for these tags in CDATA tags. Also if you need to enter html content in your description or title tags then in that case the CDATA tag can again come in handy. An example of entering a link inside the CDATA tag is shown below:
<file type="photo">
<cover>media/photos/covers/photo-cover.jpg</cover>
<thumb>media/photos/thumbs/photo-thumb.jpg</thumb>
<source>images/largeImage.jpg</source>
<title>Photo example</title>
<description>
<![CDATA[
A short description of the photo with a <a href="#">Link</a>
]]>
</description>
</file>
If you do enter html content inside your description or title then you may also need to style them according to your needs. In order to so you have to remember that these are shown in the Coverflow/Thumbnails section and also inside the modal overlay box, the title being displayed inside a h2 tag and the description inside a p tag. So if for example you want to target the title and description in the modal overlay then find the section called Overlay Styling in the css file and there you will style find blocks for #overlayContent h2 and #overlayContent p.
As of version 1.3 CCGallery supports the filtering of items by custom categories. To place an item in a particular category you have to
use the tag <category> inside which you will have to write the category name. If an item belongs to multiple categories
then just use multiple category tags. As an example of this see the code block below:
<file type="photo">
<category>category one</category>
<category>category two</category>
<cover>media/photos/covers/photo-cover.jpg</cover>
<thumb>media/photos/thumbs/photo-thumb.jpg</thumb>
<source>images/largeImage.jpg</source>
<title>Photo example</title>
<description>A short description of the photo</description>
</file>
<file type="audio">
<category>category two</category>
<cover>media/audios/covers/audio-cover.jpg</cover>
<thumb>media/audios/thumbs/audio-thumb.jpg</thumb>
<source>media/audios/audio-file.ogg</source>
<source>media/audios/audio-file.mp3</source>
<title>Audio example</title>
<description>A short description of the audio piece</description>
</file>
<file type="video">
<category>category three</category>
<cover>media/videos/covers/video-cover.jpg</cover>
<thumb>media/videos/thumbs/video-thumb.jpg</thumb>
<source>media/videos/video-file.mp4</source>
<source>media/videos/video-file.webm</source>
<source>media/videos/video-file.ogv</source>
<title>Video example</title>
<description>A short description of the video clip</description>
</file>
Based on the category names that you have entered in the XML file you can create corresponding buttons in the HTML file, which when clicked will filter the items based on your custom categories. The instructions for creating those buttons are in the section called HTML Setup.
As of version 2.0 CCGallery supports in making the thumbnails in the Coverflow and Thumbnails sections behave as links. To make a thumbnail
for an item behave as a link you have to add a tag called <link> to the item details in the config.xml file. An example code is shown below
<file type="photo">
<cover>media/photos/covers/photo-cover.jpg</cover>
<thumb>media/photos/thumbs/photo-thumb.jpg</thumb>
<source>images/largeImage.jpg</source>
<title>Photo example</title>
<description>A short description of the photo</description>
<link>http://google.com</link>
</file>
When links are added in this way then if the corresponding thumbnails are clicked, the page that is pointed to in the link url will be loaded. If links are added then the default action of opening a modal overlay on clicking the thumbnails will not occur, no matter what file type the item is. So in terms of practical use this feature will only be suitable when items are of the file type photo. By default the links open in the same window as the gallery but you can make them open in new windows. The way to do this has been explained below.
As already stated CCGallery supports images, audio and video. In case of images if the dimensions of the large version of the image is bigger than the browser window dimensions then that image will be resized to fit inside the browser window. For playing audio and video CCGallery uses Mediaelement.js. This is a HTML5 audio and video player. For browsers that do not support HTML5 audio or video playback, Mediaelement.js enables fallback to Flash and Silverlight. Now different browsers require different file formats for native playback of HTML5 audio and video. For audio you must upload a mp3 version of the file which is supported by Safari, Chrome and IE9. You must upload an ogg version if you want to have native playback in Firefox and Opera. The ogg format is also supported by Chrome. But you can upload only the mp3 version and Mediaelement.js will use Flash to play the audio file in Firefox and Opera. Similarly for the case of video playback, if you want to have a wide range of browsers natively play the video, then you must upload mp4, webm and ogv versions of the video. But here also you can only upload a mp4 version (h.264) and Mediaelement.js will use Flash or Silverlight to play the video in browsers that do not support that format. If you use only mp4 (h.264) videos and find that when there is Flash fallback in unsupported browsers, the entire video needs to be downloaded before it can be watched, then the index of the mp4 file is placed at the end. To remedy this case use the utility QTIndexSwapper on your mp4 files. If you find that after uploading CCGallery to your server your browser is not able to play video files then you may need to configure your server in order to enable it to stream video files. For an Apache server place the following code in an .htaccess file and place it at the root of your website.
AddType video/ogg .ogv AddType video/mp4 .mp4 AddType video/webm .webm
For details about what file version to upload and also for detailed instructions on configuring your server for proper streaming of video files if needed, check out the website of Mediaelement.js.
CCGallery also allows you to link to Youtube and Vimeo videos. In that case the <source> must contain the link to the video.
For Youtube the link must be of the type http://www.youtube.com/watch?v=xxxxxxxxxxx, and for Vimeo the link must be of the form http://vimeo.com/12345678.
Please note that if the Youtube and Vimeo links are in any other form than what is shown above then video embedding won't work. You must provide the links only in the format as shown above.
Also note that you have to associate image files with Youtube/Vimeo items (just like regular items) to be used in the Coverflow and Thumbnails modes. Without these the gallery will fail to load.
You have the option to choose whether CCGallery will open in the Coverflow or in the Thumbnails mode first. To do that open up the index.html file in your code editor and find div#displayButtons. There you will see two buttons which are used for activating the Coverflow and Thumbnails mode. If you want CCGallery to open in the Coverflow mode first then add the class active to a#gocoverflow like this:
<a class="navbuttons active" id="gocoverflow">Coverflow</a>
If you instead want CCGallery to open in the Thumbnails mode first then add the class active to a#gothumbs just as shown above. By default CCGallery loads the Coverflow mode first.
If you want to filter your items by custom categories, and have mentioned the category names as described in the XML Setup section, then you will have now to create buttons which when clicked will filter the items based on custom categories. For each category that you have there has to be a corresponding button. These buttons must be placed in the container div#sortButtons. For example if you have a category called “category one” then the code for creating the filter button for that category is:
<a class="navbuttons" data-category="category one">Category One</a>
The value inside the custom data attribute data-category should be exactly equal to the name that you have set in the XML file, including the casing of the letters. This data attribute is used to determine items of what category are to be displayed, so please ensure that you specified the same exact category name as you have done in the XML file. If you want then you can only have filter buttons corresponding to custom categories as shown above, and can delete the default buttons that filter items based on file type, i.e photos, audios and videos. Even if you delete the default filtering buttons, take care not to delete the button which when clicked shows all the items in the gallery. The code for that button looks like this:
<a id="all" class="navbuttons" data-type="all">All</a>
As of version 1.4 you also have the option to display only a particular category when the page first loads. To do this you will have to proceed almost exactly as for the case when you have to choose the Coverflow or Thumbnails mode to load first. So if for example you only want the photos category to be displayed on page load then you must add the class active to the category's button like this
<a class="navbuttons active" id="photos" data-type="photo">Photos</a>
Needless to say that this holds for any category, whether it be a category based on file type or a custom defined category.
As of version 1.2 CCGallery provides the option of detecting mobile devices such as smart phones and tablets in order to serve them an alternate XML file where you can declare paths to low resolution videos. The reason being that most mobile devices have limited bandwidth and hence it would be better to serve videos that are smaller in size. Also many mobile devices are unable to play HD videos or videos with high enough resolution, so it is better to serve them a low resolution video (something like 640 × 480). If you want to serve desktop browsers high quality videos but also don't want to neglect mobile devices, then create a new XML file called config-mobile.xml. This new XML file should be almost a duplicate of config.xml, the only difference being that config-mobile.xml will have paths to low quality videos which will be served to mobile devices. You only need to make mp4 videos for mobile devices. In the index.html file find div#ccgallery and add the data-mobile attribute to it like so
<div id="ccgallery" data-mobile="true"> . . . </div>
When this attribute is set to "true" then CCGallery will detect if it is being viewed in a mobile device and serve it the config-mobile.xml file. If your original videos are of small enough resolution, then of course you don't need to detect for mobile devices and all browsers, whether desktop or mobile, will get the same xml file.
Also as of version 1.4 you have the option to make the audio and video files autoplay when the modal overlay box containing the media player shows up. Youtube and Vimeo videos will also be autoplayed if this option is enabled. To enable this option you must add the data-autoplay attribute to div#ccgallery like this
<div id="ccgallery" data-autoplay="true"> . . . </div>
As of version 2.0 you have the option to make audio and video files play in a loop. However Youtube and Vimeo videos won't be affected. To enable this option you must add the data-loop attribute to div#ccgallery like this
<div id="ccgallery" data-loop="true"> . . . </div>
As of version 4.1 you have the option to store the volume of the audio/video player. If this option is enabled then whenever you change the volume of the player, close it and open it again, to play the same file or some other file, then the volume that you had set earlier will still be retained. To enable this functionality you have to add the data-store-volume attribute to div#ccgallery like this
<div id="ccgallery" data-store-volume="true"> . . . </div>
Also as of version 2.0 you have the option of mentioning which item in the Coverflow section will be the starting item or the highlighted item when the page first loads. By default the middle-most item is highlighted in the beginning, but if you want to change that then you must mention the number of the starting item of your choice in this way
<div id="ccgallery" data-cover-start-item="4"> . . . </div>
As of version 3.0 you can choose to disable the fading effect at the edges of the Coverflow images section. In order to make this faded effect the background had to be of solid colour and no images or gradients in the background would work. By default the faded effect is turned on and in order to disable it write this:
<div id="ccgallery" data-coverflow-fade="false"> . . . </div>
Also as of version 3.0 you can mention the colour of the background that will be read to generate the faded effect in the Coverflow images section. Earlier the background colour of the body element was read automatically and thus the wrappers of the gallery could not have any backgrounds themselves. But now you can have separate background colours for the gallery wrapping containers and can mention that colour value which will be used to generate the faded effect in the Coverflow. The colour values should be either in hexadecimal or rgb form. Remember that if nothing is passed then by default the background colour of the body element will be read. You can mention the background colour value like this:
<div id="ccgallery" data-background="#444"> . . . </div>
From version 3.1 you have the option to disable the reflection of the coverflow images if you so wish. In order to do so you have to write
<div id="ccgallery" data-no-reflection="true"> . . . </div>
Also as of version 3.1 you can choose if the links added to the gallery thumbnails will open in a new window. By default the links open in the same window as the gallery. In order to make the links open in a new window you have to write
<div id="ccgallery" data-new-window-links="true"> . . . </div>
As for the rest of the HTML file you should not alter anything inside div#ccgallery. But you are free to change the header and footer so that you can incorporate it into your project. If you want to add any additional elements inside the HTML file then you must put them outside of div#ccgallery.
After setting up the XML file you do not need to do anything else. Just run the gallery and you will see everything working. Since CCGallery is designed in the form of a template you can modify the CSS file to change the design of the gallery to more to your taste. In the CSS file you are free to change the background colours and gradients. You can change the width and height of most elements but please be careful while doing so because in some cases the functionality of the gallery might be disrupted. If you don't want to show any section of the gallery then hide it by using display none in the css but don't delete it from the html file.
CCGallery also provides some handy keyboard shortcuts to facilitate easier browsing. Most of these shortcuts are however effective only in the Coverflow mode. When in the Coverflow mode you can press LEFT and RIGHT keys to flip through the images. This also of course highlights the appropriate item in the list below the images. When a particular item is highlighted you can then press ENTER to open the modal overlay box. In order to close the overlay you can then press ESC. Note that this last shortcut also works when the overlay is opened from the Thumbnails section. Also if the thumbnails are made to behave as links (through the process described in the XML Setup section) then on pressing ENTER, when an item is highlighted, will load the page pointed to in the link url.
As of version 3.0 two colour schemes are provided - dark and light. The stylesheets for these two colour schemes are ccgallery-dark.css and ccgallery-light.css which contain all the styling required for CCGallery and are well commented. As of version 4.0 CCGallery features a fluid design which means that not only will the gallery adapt itself to changes to the browser window width, but also will fit into any container and adapt itself according to that containers dimensions. You can change the styling of any element to better suit your project. For most elements you are free to set the width, height, background. Besides that a reset.css and css files for embedding fonts has been used. For demo purposes a style.css and style-light.css files have been provided for the the dark and light colour schemes respectively. Also to make CSS3 gradients, border-radius and box-shadow work in IE, CSS3 PIE has been used, which is in the form of a htc file.
IE requires that HTC behaviors are served up with a content-type header of "text/x-component", otherwise it will simply ignore the behavior, IE9 being especially strict in this regard. Many web servers are preconfigured to serve the correct content-type, but others are not. If you have problems with the PIE behavior not being applied, check your server configuration and if possible update it to use the correct content-type. For Apache, you can do this in a .htaccess file:
AddType text/x-component .htc
By default htc files must have their paths set relative to the html file, but Dean Edwards' IE9.js corrects this non-standard behavior in IE and allows its path to be set relative to the css file. However IE9 still requires the htc file path to be relative to the html file. So in order to serve the CSS3 PIE htc file to all versions of IE you must have two copies of the htc file – one copy in the css folder, and one copy in the same level as the html file.
The complete list of javascript files used is given below:
Please note that the html file provided with this package references the minified version of jquery.ccgallery.js, i.e. jquery.ccgallery.min.js. If you want to make changes to this javascript file then you can do so in the un-minified version provided and then minify that to replace the original minified version when you deploy your project.
Also to make IE < 9 behave as a standards compliant browser Dean Edwards IE9.js has been used, and to enable it to understand new HTML5 tags HTML5 Shiv has been used.
You should follow best practices and include the javascript files at the very end of your document, just before the closing body tag. This allows faster loading
of web pages and that is how the javascript files are included in the gallery.
The original code for projective texturing of images in HTML5 Canvas was developed by Steven Wittens. This code has been modified slightly to better suit this project.
I hope that you like this item and it makes your web page more stunning. If you find any bugs then don't hesitate to let me know. Also if you want to see some new features in this item or have any ideas to make the overall item much better then you can send me the details. All future updates are of course free !
Once again, thank you so much for purchasing this item. As I said at the beginning, I'd be glad to help you if you have any questions relating to this item. No guarantees, but I'll do my best to assist. If you have a more general question relating to the items on Codecanyon, you might consider visiting the forums and asking your question in the "Item Discussion" section.
Nilok Bose