Wiz CMS Tutorials

Using Gallery & Slider Editors

Video Tutorial

Gallery & Slider Editor

The Gallery & slider editor is an editor you can use to edit most galleries or sliders. It operates under a few assumptions that apply to most galleries/sliders:

  1. Galleries and sliders usually only need the markup changed in order to add/remove/edit their content. There may be a lot of JS and CSS involved, but simply manipulating the content does not usually require editing them.
  2. Markup-wise they all have a part where the same HTML markup is repeated, 1 for each "item" in the gallery or "slide" in the slider.
  3. Those repeated parts of HTML usually only need a maximum of 4 bits of editable content within them. Usually they would be called thumb, feature, title, and description (though those titles should be editable to accommodate more varied usage). Some may use some of those, some may use all of those.

Through making a CMS that allows you to set a snippet of HTML that will be repeatedly output filled with those 4 bits of data which are editable for each iteration, you can basically make a gallery/slider editor that will be able to edit most galleries and sliders that people make and use.

With being able to rename what those 4 bits of data are called in your CMS, you are also able to perform some pretty wide functions. For example, call the feature "Video" in your CMS and now you can easily content manage a video gallery with thumbs leading to video in a lightbox. Or turn off the thumb and call the feature "Slide Background" and the description "Content" and now you can edit a slider with a slide background, title, and content. You can even manipulate whether the feature and thumb editable bits of data are just typed text or allow for image upload/selection from a folder. Meaning if you turned off image upload/selection for the feature there's no reason you couldn't use the manager to output a menu system with an icon, link, title, and subtext bit of text (because you can just rename the editable parts of the CMS to those 4 terms, you define the HTML that gets put out, and what you do with that HTML output is your business, make the CSS and JS use it as a menu if you want). That should give you an idea of how versatile this manager is!

If all of that was a little hard to follow, don't worry. It's a lot to try to explain as an intro. However, it'll click into place as you go through the tutorial and actually set up a gallery.

Planning Stage

For ease of writing I'm just going to say "gallery" from now on instead of "gallery/slider/any other repeated HTML editor". For the planning stage we need to figure out where our gallery is going to draw images from (i.e. what folder on the website is going to be allowed to upload/manipulate files in, I suggest it be one dedicated to this gallery), and what URL we want the user to go to in order to edit it. We also need to figure out what we want to call our (up to) 4 bits of editable data for each item in the gallery within the CMS.

For this example I'm going to make a gallery in a homepage on a fake site. I want the folder containing any images for the gallery to be in the website root and be named galimages and I want the user to go to mysite.com/galleryeditor/ in order to edit said gallery. It's going to be a video gallery that has a thumb that when clicked opens a video in a lightbox, with a title showing over the video. To demonstrate turning off one of the 4 bits of possible data I'll not use the description. Of course we'll assume that I already built this gallery into my website and now we're just making it content managed, so we already know what our markup will need to be and how it will need to be edited to change the gallery.

Step 1

Now that we've figured out what we want, we can get to work on plugging our CMS into our existing gallery.

The first step is to simply put the gallery editor where we need it. In the EXTRA folder on your website you'll find a folder named wiz-slider-n-gallery-manager. Make a copy of that folder in the website root and rename it galleryeditor since that makes a visit to mysite.com/galleryeditor/ end up in the folder of our editor like we wanted. Since we already built the gallery with it's markup being static HTML first, I'm assuming the galimages folder is already there in the site root and filled with some of the images the gallery is currently showing in our page.

Step 2

Like usual the first thing we need to edit in the CMS instance is the username and password. In your (now named) galleryeditor folder open up the index.php file. There you find $username and $password variables right there at the top. Obviously it's a good idea to give the editor your own username and password by editing those.

Step 3

Now go into the utils folder open up the file-manager.js file. There's two variables in here (right at the top) we'll need to edit. The first is managerPathToAssets and that needs to be set to a path to the galimages folder, relative from the gallery editor folder (not from this file itself). So in this case we need to go up one level (../) to get out out of the galleryeditor folder, and then to the galimages folder. So when you're done with that it'll look like this:

// a relative path from the gallery folder to the folder it's managing assets in
var managerPathToAssets = '../galimages/';

The other variable to change is the htmlPathToAssets variable. This is basically the text that will be prepended to any filename you upload to the galimages folder within the output HTML. So in this case our gallery is in the site home, galimages in the site root, so if we upload an image.jpg file we'll want the html to output galimages/image.jpg in the output HTML. Therefore we'll set this variable to 'galimages/' so that that's what it prepends. Once done it'll look like this:

// this is the path that the HTML output for the gallery will have to the folder with the images
// so either use a url that is relative to where you'll put the gallery or use a non-relative
// url like leading with a slash for the site root (like '/assets/')
var htmlPathToAssets = 'galimages/';

Step 4

Now from back out in our gallery managing folder you'll see a folder called scripts. Go in there and open the file named settings.php and you'll find a $folderToManage variable. This needs to be set to a path to the galimages folder relative from this file. That means up two levels to get outside the scripts and galleryeditor folders, then to our galimages folder. Once edited it'll look like this:

// the folder to manage, relative from this file including the trailing slash
$folderToManage = "../../galimages/";

Step 5

Now the gallery manager knows how and where to edit/upload files. Now it's time to actually start editing the CMS options to match what we need. So in the galleryeditor folder you'll find a file named _settings.js that you'll need to open up. This is where you determine what of the 4 bits of data are used, what they'll be named in the editor, etc. I'll show you how I'm editing mine first:

var stg_listItemLabel = "Gallery Item";

var stg_useThumb = true;
var stg_thumbCMSTitle = "Thumb:";
var stg_thumbCMSHelp = "Select a thumb image for this gallery item.";
var stg_allowThumbUploader = true;

var stg_useFeature = true;
var stg_featureCMSTitle = "Video:";
var stg_featureCMSHelp = "Copy/paste a YouTube video URL here to determine the video for this gallery item.";
var stg_allowFeatureUploader = false;

var stg_useTitle = true;
var stg_titleCMSTitle = "Title:";
var stg_titleCMSHelp = "This title will show above the video when it opens in the lightbox.";

var stg_useDescription = false;
var stg_descriptionCMSTitle = "none";
var stg_descriptionCMSHelp = "none";

First off I changed the stg_listItemLabel because "Gallery Item" just seemed to fit what we're doing here. Then I changed the help text for the thumb, then changed the feature to be labeled as "Video" in the CMS, and obviously changed the help text for that too. Then I set stg_allowFeatureUploader to false since I intend for them to paste in a URL to a YouTube video, not upload/set an image for it. Of course I changed it's help text as well. The only thing I needed to change about the title was the help text. And lastly I set stg_useDescription to false because we're not using it. I then set it's title and help text to "none" not because I needed to, but just to illustrate that they weren't being used. In the end this will create a gallery editing interface that looks like this:

The help text will display next to its corresponding item when the "?" is rolled over. Notice that the feature is now labeled "Video:", and doesn't show a link to upload/select images since we said not to allow the uploader for that item. Also notice there is no description showing. If there were there'd be a fourth sub-area for it, but there's only 3 now. Now we've basically got the editor visually set up like we want for editing our particular gallery.

Step 6

Now we need to tell it how to format the HTML it outputs for each item in the gallery. For this we use a little XSLT. So in the galleryeditor folder open up a file named _template.xslt for editing. The only area of this file you should worry about is the part between the <!-- ** BEGIN/END EDITING HERE ** --> comments. This is both where you'll define what the output HTML looks like for each item as well as tell it where to put any thumb/feature/title/description output within that HTML. Note that regardless of what you named those bits in the _settings.js for this file you're still using the original names of the bits of data (thumb, feature, title, and description). It's only internal, so it doesn't affect the end user. So lets pretend that our gallery markup looks like this:

<div class="vid-gal-item">
    <a href="https://www.youtube.com/watch?v=22vH2HXfuzA">
        <img src="galimages/thumb01.jpg" class="vid-gal-thumb" />
    </a>
    <span class="hidden-gal-title">A Neat Video</span>
</div>

How your JS/CSS turns that repeated markup into a gallery, the editor doesn't care in the slightest. It just needs to be able to print it out and fill in the right data into the right spots within it.

For that you need to know a little XSLT. Fortunately it's little enough that I can teach it to you right here. First off, your HTML snippet here must be XHTML formatted for XSLT to work with it. That means close your tags. For example, use <br/> instead of <br>. That doesn't mean your HTML page has to be XHTML (HTML5 can accept XHTML code, and it's just this snippet you need to have proper XHTML style tag closings). Second, there's two ways that you'd determine where a variable goes in XSLT. For example we'll use the "thumb". If you're outputting it into an attribute in your HTML you'd use the format {thumb} and if you're outputting it outside of an attribute you'd use the <xsl:value-of select="thumb"/> format.

If that went over your head that's fine, it'll click when you look through the example below. So back to our XSLT file and the space between the <!-- ** BEGIN/END EDITING HERE ** --> comments. For our HTML bit I'll make it look like this:

<!-- ** BEGIN EDITING HERE ** -->
<div class="vid-gal-item">
    <a href="{feature}">
        <img src="{thumb}" class="vid-gal-thumb" />
    </a>
    <span class="hidden-gal-title"><xsl:value-of select="title"/></span>
</div>
<!-- ** END EDITING HERE ** -->

Notice that where I wanted the feature (Video) output to go I put {feature} (because it's in an attribute), where I want the thumb url to output I put {thumb} (since it's also in an attribute), and where I wanted the title to output I put <xsl:value-of select="title"/> (since it's not in an attribute). Notice I didn't use the description at all (duh, because we're not gonna use one).

Step 7

Now back in your galleryeditor folder you'll find a output-html.php file. You need to open that up and edit two variables inside, named $xmlDataFile and $xsltTemplateFile. Both of these need to point to your galleryeditor folder's data.xml file and _template.xslt file respectively. The trick is that those paths need to be relative from the page in which your gallery is used! So since our gallery is in the home page and our galleryeditor folder is also in the root, ours would look like this after editing:

$xmlDataFile = 'galleryeditor/data.xml';
$xsltTemplateFile = 'galleryeditor/_template.xslt';

Step 8

Now you simply need to replace the HTML for the gallery in your page with the PHP snippet that will output the gallery HTML. This needs its own snippet (different from the one we were using in earlier tutorials). So you'll find that the gallery editing folder has its own PASTE-IN-HTML-SNIPPET.txt file. Inside is the snippet to use on the first line. Simply replace the part of your gallery HTML that is the repeating HTML code we set up the gallery editor to output with that snippet, and change the path-to-gallery-editor part to be a relative path from the page where the gallery is used to the gallery editing folder and the output-html.php file inside it. For our example once done that'll look like this:

<?php require('galleryeditor/output-html.php'); ?>

Optional Step 9

Optionally you can populate the data.xml file. Basically, that's where the CMS will store its edited info, using it like a database for the gallery. Obviously you could just open up the gallery editor and populate it via the interface...but it's sometimes nice to just do it right in the file itself and open up the editor to an already populated list.

To do that you'd open the data.xml file in the galleryeditor folder. Inside you'll find it has a structure like this:

<xml>
    <item>
        <thumb></thumb>
        <feature></feature>
        <title></title>
        <description></description>
    </item>
    <item>
        <thumb></thumb>
        <feature></feature>
        <title></title>
        <description></description>
    </item>
</xml>

Each xml->item node represents an item in the gallery. Each of those contains a thumb, feature, title, and description node that you can populate with the 4 bits of data for that item. Keep the original names for those nodes even if you changed the name of it for the editor, this is for internal usage only. And if you shut off one of the bits of data (like for example we shut off the description for ours) don't delete that node here. Just leave it blank. So just populate that XML file however you need if you'd rather start out with some data in there before opening the editor.

Done

You're now done. You can just go to mysite.com/galleryeditor/ and log in and edit away! There's a lot of steps here, but once you've gone through it once and understand it there's a shortcut way of going about it, as follows.

The Shortcut

For each of the files the variables you need to edit are at the top and well commented. So the quickie process is to just write down what files need editing, open them up, and follow the comments at the top. Those files (relative from the gallery editing folder) are index.php (for username/password), scripts/settings.php and utils/file-manager.js (to set paths to the folder where images will be stored), _settings.js (to set up the CMS options), _template.xslt (to declare the HTML output format), and output-html.php (to give paths to the data and template files). Then put the PASTE-IN-HTML-SNIPPET.txt snippet in your code and optionally edit data.xml to populate it with data if you want. When it's summed up like that, it can actually be a pretty quick process. I typically set up gallery editing in around 5 minutes. Not bad at all!

Tutorial Menu Next Tutorial ❯