Gallery.XML Setup, Installation and Help Topics
Gallery.XML is a lightweight, crossbrowser, customizable and extremely easy to use component for displaying images in cool Web 2.0 looking style and a lightbox.
The script is so easy to use that it may be up and running in a couple of minutes without writing a single line of complicated JavaScript. All you have to do is to register the runtime script of the component, enter the admin or manually add, upload, delete or modify images in your gallery.
View online demo of Gallery.XML or download it straight away. Buy via PayPal.
Because the component or parts of it are rendered entirely on the client, and the source is not available via the standard View Source command of the browser, it is recommended that you use IE DevToolBar or FireBug or other troubleshooting and code inspection tool (such as Opera Dragonfly or the development tools of Safari and Google Chrome) in order to inspect the HTML and the CSS classes.
Requirements
- Standards-compliant (XHTML1.0/1.1, HTML5) or skinny doctype page - the control will not initialize on non-standards-compliant pages.
- Web-server (Apache, IIS)
Supported Browsers
- 6
- 7
- 8
- 9
Installing and Running the Default Configuration of the Component
To copy a chunk of code from the listings below and keep its indentation, double click to select it, then right click and choose "Copy" from the context menu or use Ctrl + C.
1. Copy the entire Gallery.XML/ directory in the root of the website that you are going to use the control at. If you have a special third party controls folder or just want to add Gallery.XML in a Scripts folder, you may use the rootfolder property of the control. This is explained later in the manual. If you have added Gallery.XML/ in the root, your folder structure should look like this:
/Gallery.XML
index.php
some-page.php
2. In the header (between the <head>...</head> tags) section of the page where the Gallery.XML will reside, add the runtime directive that will render the necessary scripts:
<script type="text/javascript" src="Gallery.XML/Scripts/Gallery.XML.js"></script> <script type="text/javascript" src="Gallery.XML/RoundedCornersPanel.JS/RoundedCornersPanel.JS.js"></script>
3. In the <head>...</head> section of the same page, below the runtime directive, add the page settings of the control in a <script>...</script> tag:
galleryxml.settings = {
rootfolder: "",
viewerbgcolor: "#000000",
clicktoclosettoltiptext: " (Press ESC or click outside to close)",
dithercolor: "#474747",
buttonswidth: 40,
buttons: true,
buttonsposition: "bottom",
previousbuttontext: "«",
nextbuttontext: "»",
caption: true,
captionposition: "top",
overlaycolor: "#000000",
animate: true,
animationduration: 500,
finetunecssfile: "FineTune-1.css"
}
4. To create a gallery, add its initialization method to the page below the galleryxml.settings() from the previous step:
galleryxml.pageload({
datafile: "Photos/ESP_SV_AcidMartin/ESP_SV_AcidMartin.xml",
using: galleryxml.settings
});
Properties of the galleryxml.pageload() Method
datafile
Required property. This is the gallery feed file. It is a simple .xml file with a couple of properties, where image items are added.
using
Required property. This will import the page settings of Gallery.XML.
Properties of galleryxml.settings()
rootfolder
If you have a special third party control folder or would like to add the Gallery.XML directory as a child of another folder, not at the root of your website, you may use this property. For example, if you add Gallery.XML in Scripts folder, then the value of rootfolder will be:
rootfolder: "Scripts/"
QUICK TIP: Do not forget the trailing slash ("/") after the folder name, otherwise Gallery.XML will not initialize correctly.
viewerbgcolor
The value of this property should be a valid hex color, which will be set as color of the viewer and its previous / next buttons.
clicktoclosettoltiptext
An optional string that will be appended to the tooltip of the enlarged image informing that the viewer can be closed by pressing the ESC key or clicking outside the viewer.
dithercolor
This should be a valid hex color, which will be applied as antialiasing color of the rounded corners of the viewer and the navigation buttons.
buttonswidth
Integer, which will be set as width in pixels of the navigation buttons. Do not add "px", as the unit will be added automatically.
buttons
Boolean (true or false) value. If set to false, the previous and next buttons will not be visible in the viewer.
buttonsposition
Can accept three values - "top", "middle" and "bottom", and allows positioning the navigation buttons vertically in the viewer.
previousbuttontext
Text for the previous button of the viewer.
nextbuttontext
Text for the next button of the viewer.
caption
Boolean (true or false) value. If set to false, the images will not have a caption.
captionposition
Can accept two values - "top" and "bottom", and allows positioning the caption of the images vertically in the list and in the viewer.
overlaycolor
This should be a valid hex color, and will be set as a background color of the modal overlay. The opacity of the overlay and be further set in Gallery.XML/Scripts/Gallery.XML.css file.
animate
Boolean (true or false) value. If set to false, the modal background will not be animated upon opening an image in the viewer.
animationduration
Integer, representing the animation speed of the modal overlay in milliseconds. The greater the number, the longer the animation duration.
finetunecssfile
This will import an additional .css file where the appearance of the galleries on the page can be further set. The fine-tune CSS files are stored in the Gallery.XML/FineTune.CSS/ folder of the control, and the path is added automatically.
The Gallery Datafile
The datafile represents a single gallery that will be loaded on the page and is a simple .xml file. The typical datafile of Gallery.XML looks like this:
<?xml version="1.0" encoding="utf-8" ?> <ajaxgallery enabled="true" enableenlarge="true" loaderid="gallery-2" albumfolder="Photos/ESP_MH_100_AcidMartin" thumbwidth="175" thumbheight="131"> <item filename="image_01.jpg" description="ESP MH-100" visible="true" onclientclick="" /> <item filename="image_03.jpg" description="ESP MH-100" visible="true" onclientclick="" /> <item filename="image_04.jpg" description="ESP MH-100" visible="true" onclientclick="" /> <item filename="image_05.jpg" description="ESP MH-100" visible="true" onclientclick="" /> </ajaxgallery>
Properties of <ajaxgallery />
enabled
Boolean (true or false) value. If set to false, the gallery will not render on the page.
enableenlarge
Boolean (true or false) value. If set to false, images will render, but users will not be able to enlarge them in the viewer.
loaderid
ID of an existing <div /> element on the page where the gallery will render.
albumfolder
The folder where the images are stored.
thumbwidth
Integer, representing the width of the thumbnails in pixels. Do not add "px", as units are added automatically.
thumbheight
Integer, representing the height of the thumbnails in pixels. Do not add "px", as units are added automatically.
Properties of <item />
filename
The filename and extension of the image represented by the current <item />.
description
Text for the caption of the image the current <item />.
visible
Boolean (true or false) value. If set to false, the current image will not render in the gallery.
onclientclick
Allows the execution of custom function when the image in the list is clicked. See demo page for more information.
The Admin Panel of Gallery.XML
The admin of Gallery.XML is available with the full version of the control only. The full version costs USD20 and can be purchased from this page.
Admin Panel Browser Support
- 6
- 7
- 8
- 9
Admin Panel Requirements
- Client: Internet Explorer 7, Internet Explorer 8, Internet Explorer 9, Mozilla FireFox, Opera, Google Chrome and Safari with enabled JavaScript / AJAX.
- Server: Apache or another web-server with PHP support.
Before Running the Admin
1. Make sure that the Admin/ directory is copied in the Gallery.XML/ folder of the distribution of the control. This is the default location, and it cannot be changed, because it is relative to the Gallery.XML/Admin/Assets folder in the same directory.
2. If you are using Gallery.XML on a live server, make sure that you have set full CHDMOD rights (r-w-e) recursively the following files and directories, so the admin operates correctly:
- Photos Folder
- Gallery.XML/Admin/Assets/delete-gallery.php
3. Open Gallery.XML/Admin/processlogin.php with your text editor, and change the default values for username ($user_name) and password ($password) with your own values. The defaults are admin / admin and it is recommended to change these before uploading to a production server.
$user_name = "admin"; $password = "admin";
4. The admin can be localized. The localization files are stored in the Gallery.XML/Admin/Localizations folder. Currently there is one localization - English (en-US.js, set by default).
If you create your own localization, make sure you use entities for non Unicode characters; otherwise the admin will fail to initialize. The localization is set via the language property of the init() method of the admin in the Gallery.XML/Admin/index.php:
galleryxmladmin.init({
language: "en-US"
});
The name of the localization should be the name of the .js file - if you have bg-BG, then the localization file name should be bg-BG.js.
Files and Folders Structure
To ensure that the admin is working properly, the following folder / file structure for images should be used on the website:
./root/ index.php some-other-file.php /Gallery.XML/ /Admin/ /photos/ /gallery-1/ image1.jpg image2.jpg gallery-1.xml /gallery-2/ image1.jpg image2.jpg gallery-2.xml
The photos/ folder name should be set in the rootfolder property of galleryxmladmin.init() property of the admin:
galleryxmladmin.init({
rootfolder: " ../../../Photos"
});
The photos/ folder name as well as the nested folder names are arbitrary, but the structure should be observed as shown in the picture below:
Difference Between the Trial and the Full Version
The trial version of the control is for consideration and testing purposes only and its usage on live websites is prohibited. Using the trial version on live websites unlawful and legal steps may be taken against websites that use it. Please, refer to the License Agreement included in the distribution of the script prior to using it.
The trial version is fully functional, but:
- Displays a trial message watermark on each image in a gallery.
- The admin panel is not included
If you wish to use Gallery.XML on a live website without trial messages, you may purchase the full version for USD20 via PayPal from this page.
If you consider purchasing more than one Acid.JS component you may create and order a custom Creative Web 2.0 Bundle and save money. More information about the Creative Web 2.0 Bundle program is available on my blog.
Upgrade to the Full Version after Purchase
After getting the full version you will notice that it contains only certain files, not the entire distribution required to run the script - the rest of the skins and JavaScript. You have to replace the files in the trial version distribution with the ones that you have received after having purchased the full version manually. After this, the control should work without trial notices and the emails sent by it will not contain trial strings.