Recommended Sites
[your link here... ]
OK, so now you've been through the user guide, you've been through the reference guide. What next? You'd like to know how to add some extra stuff to the skin and possibly also modify parts of the skin. You've probably edited a skin or two in your time, or you'd like cut your teeth on this one. If you are an experienced skin designer you should probably read this section as well, due to some of the issues like CSS/XHTML compliance.
In this section I'll explain a few more advanced moves that can be made with this skin, and how you can better adapt it to suit your needs.
This section will grow as I get more requests from people, so please keep the discussion going and we can continue to expand this section.
If you prefer you can jump directly to a topic in this section as follows:
Configuring and using the guestbook
How does single folder mode work?
Filters
Styles
Button sets
Folder by folder behaviour
A step-by-step study on adding a navigation header to your album
By selecting the "Include guestbook" option on the slides tab of the ExhibitPlus user interface your visitors will be able to leave comments on each slide page if they choose. Comments will be visible to all other visitors. You should be aware that there is no security or authentication for this feature - anonymous comments are possible. If you are not comfortable with anybody having the ability to leave comments, do not enable this feature.
The guestbook component was very kindly written by Dhinakaran Annamalai for inclusion into ExhibitPlus. Since it is a component that runs on your webserver, usually some additional work is required to get it going. These steps are very simple, and some brief instructions will be given here. Please understand that this is a stand-alone component, and getting it to work requires changes to your server. In short, guestbook functionality doesn't really have anything to do with ExhibitPlus. Please don't post messages asking for support if they involve how to change permissions on your web server - these questions would be better directed to your ISP, or other forums which focus on these topics.
If you look in your output directory you'll see a folder called guestbook. Inside this folder is a file called processXML.php. After you copy or upload your album to your webserver (or hosting provider) this file will be executed by the server itself each time somebody accesses the guestbook or writes a new entry. This file will then create .xml files in the guestbook directory, one for each slide.
Because this file will write files into the directory of the webserver it will first need permission in order to do this. There are usually two ways of going about this. Either the process/username which runs the web server itself needs to have write permission (or ownership) of the processXML.php file and the guestbook directory, or you can assign write permission to everyone for the guestbook directory. In the unix world this is referred to as setting the permissions to 777, usually using a utility called chmod. In some cases you may have to ask your ISP to change these permissions for you, but usually it is very easy for you to do yourself. If you have shell access (which you probably don't, and if you don't know what shell access is, then you definitely don't have it) you could simply execute the command "chmod 777 guestbook" from your root album folder. Alternatively it is also very easy to use most FTP clients. Connect via FTP to your server using your favourite FTP application, then right click on your guestbook folder and select an option like permissions or properties. You may see that it is currently set to something like 755, simply change it to 777. You may see the rights represented not by a number but by a series of checkboxes. In this case just ensure that the "write" permission for everyone (or all, or world) is selected.
What can be done if you've followed these instructions and talked to your ISP but you still can't get your guestbook to work? I'm sorry, but in this case the author of ExhibitPlus and other JAlbum users cannot help you. The guestbook works and has been tested exhaustively. Unfortunately the problem must lie with your server and/or configuration.
One final point, which goes without saying. Attempting to get your guestbook to work on your local PC will fail - it can only run on a web server (which must support php scripting) and visitors must have flash installed with their browser to be able to see it.
For those who are interested a thread regarding the guestbook was previously started on the JAlbum forum, before this text was written.
Even though JAlbum has the ability to process subfolders and create a top-level index for these, it seems that many users (for whatever unknown reasons) generate their albums one folder at a time, and then manually link these into their websites. This common use of ExhibitPlus was not intended or expected so special behaviour was built into version 1.4 to handle these cases. This behaviour is called "Single folder mode". A design decision was made that single folder mode was created for users who haven't really taken the time to properly explore the features of JAlbum, and therefore they would probably not read any documentation, and perhaps not even explore the options in the user interface. Therefore this behaviour would be completely automatic. For this reason you will not find any controls in the user interface for this feature.
Single folder mode simply supresses the display of certain information on the root index page. In fact, the name of the feature is a little misleading, because it applies to the root page of any album, even if there are sub folders in it. Functionality is as follows:
Filters are an excellent way to easily add various effects to your thumbnail or slide images. JAlbum has a fully open architecture which allows people with a little Java knowledge to build their own filters, and for even inexperienced users to quickly add them.
Some of you might have noticed the "FYVIE.NET" watermark on all the slide images in my own personal album. This was very easy to add. The easiest way to do this is simply to use the Watermark section of the ExhibitPlus tab in the JAlbum user interface. This will use the default system font. If you are not happy with the default system font then edit the file init.bsh in the ExhibitPlus skin directory. In this file you will find a line like this:
// f.setFace("Bank Gothic Medium BT");
Simply remove the // characters at the beginning of the line to effectively uncomment it, and change the font face as you like. To acheive more precise control about how this filter might be used ensure that the fields in the ExhibitPlus tab are empty and set a filter manually via the Advanced tab. Set a user variable called "filter1" with the following value:
class=WatermarkFilter text="Your text here" size=20 closeups valign=bottom align=right
strengthPercent=40 face="Bank Gothic Medium BT" style=plain
That's all there is to it. Just change the options as you would like, and generate your album.
If you are interested in other filter possibilities, be sure to check out the information on filters at the JAlbum website. Have you written a filter that would go well with ExhibitPlus? Let me know.
Styles are now easier than ever to alter. Since ExhibitPlus 1.2 the design of styles has been split into 2 separate components. All of the layout aspects of the style are contained in a file called res/basestyle.css in the skin directory, we will refer to this file as the layout style sheet. Under the style directory you will find various different alternate style files, e.g. light.css, blue.css, etc. We will refer to these files as the colour style sheets. These are the files which are selectable via the JAlbum user interface, and these files contain only colour specific information to change the appearance of the main style. This approach means that the colour style sheets themselves are quite small, easier to understand and utlimately make the process of designing your own style very fast!
Essentially there are 3 main aspects to consider if you wish to make your own style:
If you wish to use a background graphic (for example purplestripe.gif is used by dark.css) then include this graphic in the skin's /res folder and it will be copied over to the /res folder in your output directory. Just remember to name any background graphics with unique names for each different style.
When JAlbum runs it will copy files as follows:
Have you created a style which you think should be included with ExhibitPlus? Please get in touch. Or perhaps you've done something innovative or impressive with ExhibitPlus? Why not let us link to your album via the sample page?
Maybe changing the colour of styles is not enough for you? You'd like to go further and change layout aspects or the behaviour of the skin itself?
This is no problem, simply use a text editor to alter index.htt, slide.htt, onload.bsh, init.bsh or res/basestyle.css. A detailed discussion on all of the internal aspects of these files, or the design behind the skin is beyond the scope of this document. Therefore you should be prepared to spend some time reverse-engineering the skin and experimenting. It is important to bear in mind a couple of points before starting this:
Please note also that since version 1.4 the complexity of the routines has increased significantly, making reverse-engineering and your own modifications very difficult. In addition, many routines which were previously located in the .htt/.bsh files have now been moved into the plugins/Utils.java file. This file is compiled into plugins/Utils.class. Such modification and recompilation may be beyond the reach of many users. If you need further information about compilation procedures please refer to the JAlbum website and search through the forums.
Buttons are an important aspect of a style, and therefore it is very important that different button sets can used with different styles. Some buttons suit light backgrounds, some suit dark backgrounds, some suit all backgrounds. Ultimately it is up to you which buttons you will use with your Album, and ExhibitPlus includes several different button sets. Check the /button-sets folder in the skin directory to locate the available button sets.
To use a specific button set you change a line in your selected colour style sheet. For example dark.css contains a line which reads:
/* <% album.put("BUTTON_SET", "red-21px-darkbackground"); %> */
To use the larger gold buttons for a dark background you would simply ammend this line to:
/* <% album.put("BUTTON_SET", "gold-32px-darkbackground"); %> */
You can also look under the "Icon set" drop down box on the "General" section of the ExhibitPlus UI. This allows you to experiment with different button sets easily, without having to edit the colour style sheet.
You will also notice that if you look at some of the buttons in the button-set folders you will see that some of them are not used by the skin. These are included for other people who may write extensions to ExhibitPlus.
These are examples of the current button sets available for ExhibitPlus:
red-21px-darkbackground
silver-21px-darkbackground
silver-32px-darkbackground
gold-21px-darkbackground
gold-32px-darkbackground
silver-21px-lightbackground
silver-32px-lightbackground
gold-21px-lightbackground
gold-32px-lightbackground
metodi-beige-20px
metodi-silver-20px
metodi-blue-20px
metodi-blue-20px
Have you created your own button set for ExhibitPlus, or found another button set which you think works well with the style? Please let us know.
As you might have noticed in the reference section about user configurable files some of these files affect all the folders, and some of them affect only the folder they are placed in.
For example news.inc can be placed into any folder, so the contents of each folder can have a different news file. Header.inc and folder.inc go into the root folder of your source image directory, and their content affects all index pages generated with ExhibitPlus.
In order to demonstrate the power of this feature we will use the example of altering user variables on a folder by folder basis.
The first thing we need to understand is what the variables.inc file does. Normally it is placed into the root image folder (input) directory. It contains variables which you wish to have permanently associated with your album. By using this technique you don't have to enter user variables via the JAlbum user interface.
So for this example let's assume that we are only setting two variables via variables.inc - protectSlideImages and fixedFormatIndexPage.
Our album (a very simple one) consists of two folders:
Firstly we need to prepare two different variables.inc files and copy them to the respective folders as follows:
variables.inc for portfolio folder:
<% fixedFormatIndexPage = true; protectSlideImages = true; %>
Do we need to place a variables.inc in the holiday snaps folder? Since fixedFormatIndexPage and protectSlideImages both have a default value of false we don't actually need to specify these values again. Therefore we can safely omit a variables.inc for this folder.
To see a good example of how this method might be used refer to the sample albums on this site. You will notice that each folder within these albums has different set of variables defined, altering the look and feel of each individual folder. Browse to one of these folders now and look at the bottom of each of the index pages. A list of the variables changed via variables.inc is displayed. The display itself was made via news.inc.
Would you like to change news.inc so that it affected all folders, rather than just one folder? Or perhaps you'd like to be able to specify individual header.inc and footer.inc files for each folder?
To change the header.inc and footer.inc behaviour look for the lines in index.htt and slide.htt that read as follows:
<ja:include page="$rootPath/header.inc"></ja:include> <ja:include page="$rootPath/footer.inc"></ja:include>
Now change them as follows:
<ja:include page="header.inc"></ja:include> <ja:include page="footer.inc"></ja:include>
Likewise to change news.inc so that the news file from the first folder is used for all folders look for:
<ja:include page="news.inc"></ja:include>
and change to:
<ja:include page="$rootPath/news.inc"></ja:include>
Simple!
Perhaps you've noticed the fyvie.net banner and navigation bar at the top of each page? A navigation bar is also present in the personal album on this site. Would you like to achieve the same functionality with your own album?
You may be tempted to try to solve this problem using the quick and dirty method: frames. I would recommend against doing this for a number of reasons. Probably one of the biggest reasons is that your users will not be able to quickly copy and paste the URL in their browser. Well they could if they right click a link and then copy it this way, but as we know the average user doesn't have that kind of time. If you avoid using frames the link to the file or directory that the user is looking at is always available to them in plain sight. Also, what if they did copy and paste a direct link? Your frame set will disappear. It is not appropriate to go further into the evilness of frames, but if you need further convincing, just check this article
A much better way to approach this is to use standard HTML/XHTML and CSS markup. Before we begin you should already have made yourself familiar with the use of the following files: styles.inc and header.inc
Now that you know what these files are for we can begin. We'll start with the contents of the header.inc used in the fyvie.net personal photo album:
<%
// Copy index.html to every directory (redirector only for fyvie.net)
se.datadosen.util.IO.copyFile(new File(rootImageDirectory, "index.html"), outputDirectory);
se.datadosen.util.IO.copyFile(new File(rootImageDirectory, "_fyvienet_photobanner.gif"),
rootOutputDirectory);
pathToRoot = rootPath;
if (fileName != void) pathToRoot = pathToRoot + "/..";
%>
<!-- header content starts here -->
<div id="topcontent">
<a href="${pathToRoot}/../index.html"><img src="${pathToRoot}/_fyvienet_photobanner.gif"
style="float: left" alt="fyvie.net home" /></a>
<!-- Navbar is here -->
<div class="topNavBar">
<a href="${pathToRoot}/../index.html" title="Return back to the fyvie.net home page">
home</a> |
<a href="${pathToRoot}/../photos/index.html" title="A large collection of personal
photographs">photos</a> |
<a href="${pathToRoot}/../diving.html" title="Everything related to my experience with
SCUBA diving">diving</a> |
<a href="${pathToRoot}/../resources.html" title="A collection of useful links and
resources">resources</a> |
<a href="${pathToRoot}/../projects.html" title="Details of various small projects
- some finished, some in progress">projects</a> |
<a href="${pathToRoot}/../photos/index.php" title="Documentation for
the ExhibitPlus skin for JAlbum">E+</a> |
<a href="${pathToRoot}/../tools.html" title="Tools / software that I use or
recommend">tools</a> |
<a href="${pathToRoot}/../info.html" title="Contact information, maps and more about
fyvie.net">info</a> |
<a href="${pathToRoot}/../isearch/" title="Search fyvie.net">search</a>
</div>
<!-- End navbar -->
</div>
<!-- Start main section -->
<!-- header content ends here -->
Let's examine this a little closer. The first section of the file copies index.html from the root of the input directory to every folder in the output directory. This isn't actually needed, and in the case of fyvie.net this index.html is nothing more than a redirector that sends users to the file content.html if they arrive directly in a folder and don't specify a filename in their URL. In fact, if you already use the name "index" for your album pages (the default setting) then you needn't be concerned at all. However, for completeness, this is what the index.html referenced above looks like:
<head> <meta http-equiv="refresh" content="0; url=content.html"> </head>
The second copy operation in header.inc simply makes sure that the file _fyvienet_photobanner.gif (the graphic at the top of each page) is copied to the root of the output directory for the album, as it will be referenced by the HTML that follows it.
After the file copy a variable, pathToRoot, is calculated. This ensures that we can specify the correct relative URL reference to the root folder wherever our pages happen to be. This enables us to always reach important files like _fyvienet_photobanner.gif.
At the first <div> marker we see the actual HTML code which will be included in each generated page. This code sets up the navigation, and that's pretty much all there is to it.
But wait - we are referencing CSS styles that are unique to our header.inc file - they aren't contained in any of the style sheets used by our album. One way of doing it would be to include those styles into a file like basestyle.css, but then every time you upgraded or reinstalled the skin the changes would be lost. By specifying the styles via styles.inc the styles will be copied into every generated HTML file, and you can keep the styles.inc file together with your other customised files in the your source directory. If you had multiple albums you could also use multiple styles.inc files.
<style type="text/css">
#topcontent { }
.topNavBar { color: white; font-weight: bold; text-align: right;
margin-right: 45px; padding-top: 11px; position: absolute; right: 0px}
.topNavBar a { color: rgb(0,204,0); text-decoration: none; }
.topNavBar a:hover { color: rgb(0,204,204) }
.topNavBar a:visited { color: rgb(0,204,0) }
.topNavBar a:active { color: rgb(204,204,0) }
#centercontent { clear:left }
</style>
There's only one more thing to think about here. The file _fyvienet_photobanner.gif exists in our root image directory. Therefore JAlbum will process this image file as part of our album and we won't want that. It was named so that it began with an underscore because JAlbum used to ignore files named in this way. Later on, the behaviour of JAlbum changed, and this wasn't the case anymore. Therefore we have to visit the "Advanced" tab in the JAlbum user interface, then select the "Main" tab and alter the field called "ignore pattern". The default value is usually "\..*", but you can change it to "(\.|_).*" so that files starting with an underscore will also be ignored.
If you would like a copy of all the custom configuration files used in the above examples you can download them here.
If you would like to assist with the testing of ExhibitPlus, please see further information on this subject here.
This concludes the advanced guide. Do you think there is something else that should be added to this section? Please let me know. Perhaps you started here and might benefit from learning some of the topics discussed in the user guide, or would benefit from learning about the various variables and files described in the reference section?
