How to Make a ZenPhoto Theme
Contents
1. Getting Started
a. What is a theme?
b. What should I know before making a theme?
c. How does a theme work?
2. Theme Basics
a. Where are the files located?
b. Downloading and Installing the Wiki Theme
c. Theme Structure
3. Making a Theme
a. Quick & Easy
b. Diving In
i. theme.txt
ii. theme.png
iii. index.php
iv. album.php
v. image.php
4. Closing
In technical terms, it's a set of files that use a markup language (such as HTML or xHTML + CSS) and embedded PHP code to dynamically create the layout and style of your gallery. In other words, a theme is just a way to give your gallery a different look.
b. What should I know before making a theme?Before going through this article, you should already have a decent understanding of how to create a basic web page using HTML or xHTML+CSS. You should also have a very basic understaning what PHP is and how PHP code is put into a webpage. Don't worry, I'm not asking you to know how to create your on web app in PHP, I just need you to understand the basics on how PHP communicates with the server and returns information back to the client.
c. How does a theme work?(taken from Tristan's explanation)
Themes are done in a pretty straightforward way. They're just PHP files that use a set of theme functions (in template-functions.php) to display the albums or images in any way. The current theme is set in the admin panel, and that just makes a text file theme.txt with the theme's name in the cache folder (we'll add a field for the database soon, but for now, that works). The root index.php file then looks at the URL arguments (album, image, etc. or lack thereof) and decides whether to load the theme's index file, album page, or image page. Pretty simple.
With that said, let's get started!
2. Theme Basics a. Where are the theme files located?
By default, when you first install ZenPhoto, you should have a file structure that looks similar to the image on the left. You have the "root" or main folder of ZenPhoto, then in it you have four other folders named albums, cache, themes, and zen. Inside the themes folder is where the default themes exist, where you should install new themes that you've downloaded, and where you will make all your new themes. By default ZenPhoto comes with three themes: default, stopdesign and testing.
During the process of this article, we will be looking at a simple theme that I've created for the wiki. I will not go into every single detail of the code because as I stated before, you should already have an understanding of HTML or xHTML+CSS as well as PHP. If you don't know PHP too well, don't worry, just so long as you know what a function is and how to use it, you'll be okay. Any PHP that is not a funtion and that I've used, I'll explain. Okay? Okay!
b. Downloading and Installing the Wiki Theme. | This theme is made to look its best when using the default values for thumbnail sizes in the configuration file. You also need change the number of albums per page from 5 to 6. |
First off, download the theme here: 
wiki_zen_theme
To install this theme, just extract the contents of the .zip file to your themes directory as shown in the picture above. This will create a new folder called wiki inside your themes folder. If you haven't installed any other themes, you should now have three folders inside your themes directory: default, testing, and wiki (look at the picture to the right).
Inside the wiki folder you should see eight different files: index.php, index.css, album.php, album.css, image.php, image.css, theme.png, and theme.txt. I separated the CSS for all the .php files into separate files so that it would be easier for me to keep my CSS managable.
c. Theme StructureYou only need five basic files to create a theme: index.php, album.php, image.php, theme.png, and theme.txt. These files should be placed in a directory (usually the name of your theme) underneath the themes directory.
Here's a brief description of the basic files:
- index.php - This is the default php file. It's read and displayed when someone visits your main gallery page.
- album.php - This page is displayed when someone clicks on an album link from your gallery page (index.php). It then displays all the pictures in the selected album.
- image.php - This page is displayed when someone clicks on a specific picture from your album page (album.php). It then displays the selected picture, all it's comments, and the "add comment" form.
- theme.png - This is the theme thumbnail used in the Options page of ZenPhoto.
- theme.txt - This is the description file which gives ZenPhoto information about your theme. This information is displayed in the Options page of ZenPhoto.
 | This section is for those of you who are already comfortable with PHP. If you are not comfortable working with PHP, skip to the next section. |
If you are already skilled at designing webpages and/or websites, it's very simple to create a Theme for ZenPhoto. All you have to do is create your site like you normally would, but where you need the dynamic information, just use the available set of theme functions found in theme-functions.php. The quickest way to get your theme going is to create a copy of one of the folders of another theme and edit the files from there. Make sure that you include a loop inside each of your php scripts to loop through the albums, images and comments. You can do so like this:
<?php while (next_album()): ?>
<!-- HTML GOES HERE -->
<?php endwhile; ?>
Just make sure that for index.php, album.php, and image.php you use the next_album(), next_image(), and next_comment() functions respectively.
b. Diving InIf you're reading this, then I will assume two things: 1) that you've downloaded & installed the wiki theme which I've created and 2) that you have a basic understanding of what PHP is. What I will be doing here is to go through the process of how I created the theme and I'll explain what the PHP code does as well (although, I will not explain any of the xHTML or CSS code). You can then take this knowledge and use it to create your own theme.
Let's start off with organization. I first created a folder inside my themes folder called wiki. Then, I copied the files from default theme into my wiki folder and used those files as a starting point for my own theme. Start up your favorite text editor and open up the files. The first two files we look at will be the smallest & quickest files to create (theme.txt and theme.png). Then we'll delve into the PHP files.
i. theme.txt# Zenphoto theme definition file name::Wiki Tutorial Theme author::Darrell Dudics (a.k.a GameDudeX) version::1.0 date::5/24/2006 desc::A basic theme written for the ZenPhoto wiki.
First of all, the first line is REQUIRED. This line will tell ZenPhoto that this file is about to describe a theme. ZenPhoto will then look at the rest of the information and process it. The information is set up as key-value relationships using the format key::value. This means that whatever the name of the key, the value is shown after the double colons ( :: ). So now let's take a look at the list of keys and what they're for.
- name - This is the name of the theme.
- author - This is the theme author's name.
- version - This should be the version number of the theme.
- date - This should be the last known date of modification of the theme.
- description - This shoudl be a short description of the theme.
So just change the values of the keys to match your theme.
ii. theme.png/theme.gif/theme.jpgThis will most likely be the very last file that you create for your theme; it's an image used to represent your theme. This image can either be a .png, .gif, or .jpg and the dimensions of the file should be 150px by 150px. This will most likely be a screenshot of your finished theme, but if you want to get creative, you can design a cool icon that matches the style of your theme.
iii. index.phpNow if you look at the code in there, it's all just a standard xHTML-based webpage, but I'll try and explain some of the PHP code that's in there.
<?php if (!defined('WEBPATH')) die(); ?>
This bit of code makes sure that the configuration for ZenPhoto is setup correctly, if not it will stop everything right here. (There's no point in processing the rest of the webpage if the configuration is incorrect, right?)
<?php printGalleryTitle(); ?>
As you can read from the function name, this function will replace this bit of code with the actual name of the Gallery Title. So for example, if the title of your gallery were John's Flower Garden then the code would go from looking like this:
<title><?php printGalleryTitle(); ?></title>
to
<title>John's Flower Garden</title>
 | The function printGalleryTitle() is one of many theme functions. It's basically a PHP function that theme developers can use to get information from ZenPhoto about the gallery to put into a theme. All the theme functions can be viewed here. |
The next bit of PHP code:
<?php echo $_zp_themeroot ?>
Tells ZenPhoto to show the current path to the current theme's root directory. This is why it's used in the following context:
<link rel="stylesheet" href="<?php echo $_zp_themeroot ?>/index.css" type="text/css" />
This will give the correct path to the .css file.
<?php zenJavascript(); ?>
This will include some JavaScript that allows the logged in administrator to dynamically edit the description and title of your images and albums using AJAX.
<?php printPageListWithNav('<', '>'); ?>
This code will create an unordered list of links that link to the number of pages of albums in the gallery. So, for example, if you have three pages of albums, it will create the follwing code:
<ul class="pagelist"> <li class="prev"><span class="disabledlink"><</span></li> <li class="current"><a href="http://www.zenphoto.org:8080/zp" title="Page 1 (Current Page)">1</a></li> <li><a href="http://www.zenphoto.org:8080/zp/page/2/" title="Page 2">2</a></li> <li><a href="http://www.zenphoto.org:8080/zp/page/3/" title="Page 3">3</a></li> <li class="next"><a href="http://www.zenphoto.org:8080/zp/page/2/" title="Next Page">></a></li> </ul>
The following code is the main chunk of code for this file. It's what lists all the albums in the gallery.
<?php while (next_album()): ?>
<div class="album">
<div class="albumthumb"><a href="<?php echo getAlbumLinkURL();?>"
title="<?php echo getAlbumTitle();?>"><?php printAlbumThumbImage(getAlbumTitle()); ?></a></div>
<div class="albumtitle"><a href="<?php echo getAlbumLinkURL();?>"
title="<?php echo getAlbumTitle();?>"></a><?php printAlbumTitle(true); ?></div>
</div>
<?php endwhile; ?>
Let's take this line by line. First you're starting a while loop in PHP and tell ZenPhoto that 'as long as there's a another album that's next in the list of albums, do the following code'. The 'code' that you want ZenPhoto to process for every album is placed in between the the lines '<?php while (next_album()): ?>' and '<?php endwhile; ?>'
That is why when you look at the xHTML source from your browser you see a div with an album class more than once, because it will put every album into a div tag with the album class.
Now inside that while loop you will see more PHP code. The functions getAlbumLinkURL(), getAlbumTitle(), printAlbumThumbImage(), and printAlbumTitle() are all theme functions of which I won't explain because there are just too many to create a list here and you can also look them up in the theme function reference. However it's pretty obvious what they do just by looking at the function names. Keep in mind that all these functions provide information about the album and this information will be repeated for each album in the list of albums while going through the while loop.
<p>Currently displaying <?php echo zp_conf('albums_per_page'); ?> of <?php echo getNumAlbums(); ?> albums.</p>
This bit of code will just display how many albums are being shown out of how many total. zp_conf is a function that's been set up to allow easy access to read the setting values of the configuration file. The text "albums_per_page" tells zp_conf which setting you'd like to know the value of.
<?php
echo 'ZenPhoto ';
printVersion();
if (zp_loggedin()) {
printAdminLink('Admin', ' / ', ' / ');
printSortableGalleryLink('Sort Gallery', 'Manually Sort the Gallery');
echo ' / <a href="?logout" title="Logout of ZenPhoto">Logout</a>';
} else {
echo ' / ';
printLink(WEBPATH.'/zen/admin.php', 'Login');
}
?>
The function printVersion() will obviously print the version number of ZenPhoto. The reason why I couldn't do something like this:
echo 'ZenPhoto ' . printVersion();
is because the function will actually use the echo statement to print out the version. It does not return the value so that it could be used in the line above.
What the big if block does is check to see if the admin is logged in or not.
If you are logged in, all the code inside the if block will be processed. The printAdminLink() function will create a link to the admin control panel of ZenPhoto with the text "Admin" and place a "/" both before and after the text, like so:
/ Admin /
Next the printSortableGalleryLink() will create a link to the sorting page in the admin control panel with the text "Sort Gallery". When the user mouse-over's the link, they will see the text, "Manually Sort the Gallery".
After this, it will then print a "/" and then a link to logout of ZenPhoto.
Now, if you're not logged in, everything in the else block of code will be processed. First a "/" will be printed, then a link to the admin control panel with the text "Login" is created using the printLink() function. This function is not required in making this link, you can easily just use
<a href="http://www.zenphoto.org:8080/zen/admin.php">Login</a>
I just thought it would look nicer if I used one of the provided functions.
| printAdminLink() can only print a link to the admin control panel if you are logged in. If you are not logged in, it will show nothing. Some people are confused by this and think that if you're not logged in, it will just print a link to the login page, this is incorrect. |
So all together, this block of code will output the following if you're logged in:
ZenPhoto 1.0.2 / Admin / Sort Gallery / Logout
And output the following if you're not logged in:
ZenPhoto 1.0.2 / Loginiv. album.php
This page is almost exactly identical to index.php (in fact, I just copied the index.php and changed the name of the functions) so I won't explain everything again. The only difference between the two are that in index.php I used functions that would give me information about the albums. Here, you'll use functions that will give you information about the images themselves.
For example, instead of using getAlbumLinkURL(), getAlbumTitle(), and printAlbumThumbImage() like you did in index.php, you would use getImageLinkURL(), getImageTitle(), printImageThumb() respectively.
v. image.phpSince you should be used to the theme functions by now, I won't go into what everyone does, but I'll try and explain the more difficult bits of code.
Right at the top of this file (right before you define where the AJAX code goes) you'll notice a new bit of JavaScript. I left this code in just incase someone else wanted to modify the theme and put it in there.
function toggleComments() {
var commentDiv = document.getElementById("comments");
if (commentDiv.style.display == "block") {
commentDiv.style.display = "none";
} else {
commentDiv.style.display = "block";
}
}
</script>
This code will basically allow you to toggle whether or not you want the comments to show or not. Just use it in a link and use the OnClick method of a link to run the toggleComments() function.
<div class="navigation">
<?php if (hasPrevImage()) { ?> <a href="<?php echo getPrevImageURL();?>" title="Previous Image"><</a><?php } ?>
<?php if (hasNextImage()) { ?><a href="<?php echo getNextImageURL();?>" title="Next Image">></a><?php } ?>
</div>
If there is an image (in the list of images) previous than the one being viewed, create a link to that previous image with the text "<". Then, if there is an image (in the list of images) following the one being viewed, create a link to the following image with the text ">".
When you get to the form, I just copied and pasted code from an existing theme. However, from what I gather, it seems that because of
<input type="hidden" name="remember" value="1" />
the user is able to save his/her information by way of cookie. This way if he/she comes back to the site, ZenPhoto will retrieve their name, email address, and website from the cookie using <?php echo $stored[0];?>, <?php echo $stored[1];?>, and <?php echo $stored[2];?> respectively.
<?php $num = getCommentCount(); echo ($num == 0) ? "No comments" : (($num == 1) ? "<strong>One</strong> comment" : "<strong>$num</strong> comments"); ?> on this image:
This code will get the number of comments about the current image and display it. If there are no comments, it will say "No comments". If there is one comment, it will say "One comment".
<?php while (next_comment()): ?>
<div class="comment">
<div class="meta">
<span class="date">On <?php echo getCommentDate();?> at <?php echo getCommentTime();?> PST</span>
<span class="author"><?php pr