Editing and creating page templates
From pixyWiki
After you've used Preferences->Themes page to customize your website theme, you can edit and create page templates through the Preferences->Templates page. We'll show you how to do that, but first you need to understand how the required pages, found in every theme, work together to display a website.
Every theme is different, but all themes must have two required pages -- pages that you cannot rename or delete. These are the Weblog template, which defines the main page of your blog, and the _day template, which defines how each day's worth of blog entries is displayed on your main page. Some themes also have a required page named _css which defines the CSS style code used by the website. First, let's look at a simple Weblog template.
Contents |
The Blog template
Below is a simple Blog page that displays all of the data that the website typically contains including recent entries with paging to past entries, feed links, a calendar and feed auto-discovery. Check the annotations for more detail.
Listing 1: a typical Blog template
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>$model.weblog.name : $model.weblogPage.name</title>
#showAutodiscoveryLinks($model.weblog)
<style type="text/css">#includeTemplate($model.weblog "_css")</style>
</head>
<body>
<table border="0" align="center" width="95%">
<tr>
<td class="entries" width="80%" valign="top">
<h1>$model.weblog.name</h1>
<p class="descrip">$model.weblog.description</p>
#set($pager = $model.getWeblogEntriesPager())
#showWeblogEntriesPager($pager)
<div class="next-previous">
#if ($model.results)
#showWeblogSearchAgainForm($model.weblog)
#showNextPrevSearchControl($pager)
#else
#showNextPrevEntriesControl($pager)
#end
</div>
</td>
<td width="20%" valign="top">
<h2>Calendar</h2>
#showWeblogEntryCalendar($model.weblog "nil")
<h2>Feeds</h2>
#showAtomFeedsList($model.weblog)
<h2>Search</h2>
#showWeblogSearchForm($model.weblog false)
<h2>Links</h2>
#set($rootFolder = $model.weblog.getBookmarkFolder("/"))
#showBookmarkLinksList($rootFolder false false)
<h2>Navigation</h2>
#showPageMenu($model.weblog)
#showAuthorMenu(true)
<h2>Referrers</h2>
#set($refs = $model.weblog.getTodaysReferrers())
#showReferrersList($refs 30 20)
</td>
</tr>
</table>
</body>
</html>
The above template includes a good mix of Velocity expressions and statements. There's a lot going on, so let's explain it in detail. Here's the point-by-point breakdown.
<title>$model.weblog.name : $model.weblogPage.name</title>
HTML title; For the HTML title we use the websites name, a colon and the name of the page template that is currently being displayed.
#showAutodiscoveryLinks($model.weblog)
Auto-discovery links; The #showAutodiscoveryLinks() macro adds the HTML <link> elements required for RSS and Atom feed auto-discovery as well as RSD for weblog clients.
<style type="text/css">#includeTemplate($model.weblog "_css")</style>
Include CSS styles; Here we use the include the theme's _css template directly in the page, right inside a pair of <style> tags.
<h1>$model.weblog.name</h1> <p class="descrip">$model.weblog.description</p>
Display a page title & description; Here we use the websites name again in an <h1> title and also the description for the website.
#set($pager = $model.getWeblogEntriesPager())
Get entries pager; Get the entries pager object so we can display entries and a paging control.
#showWeblogEntriesPager($pager)
Show entries; Show current page's worth of entries (or search results). Calls on _day template to do the display of each day's worth of entries, the number of entries to display is set in Preferences > Settings.
#if ($model.results) #showWeblogSearchAgainForm($model.weblog) #showNextPrevSearchControl($pager) #else #showNextPrevEntriesControl($pager) #end
Show search results control? Show search results pager control if search in progress... otherwise... Show normal entries pager control.
#showWeblogEntryCalendar($model.weblog "nil")
Show the calendar; Show the standard website calendar.
#showAtomFeedsList($model.weblog)
Show feed links; Show links to all available Atom entry feeds, one per gallery.
#showWeblogSearchForm($model.weblog false)
Search form; Show the website search form, false indicates no gallery chooser.
#set($rootFolder = $model.weblog.getBookmarkFolder("/"))
#showBookmarkLinksList($rootFolder false false)
Display blogroll; Display contents of the root bookmark folder.
#showPageMenu($model.weblog)
Show page menu; Display navigation bar of pages available in website.
#showAuthorMenu(true)
Show author menu; Display author's menu, only visible to authorized users.
#set($refs = $model.weblog.getTodaysReferrers()) #showReferrersList($refs 30 20)
Display today's referrers; Display today's referrer URL with hit counts.
Note: The display of the website entries is controlled by another template, the _day template. So next let's take a look at that _day template.
The _day template
A theme's _day template is responsible for displaying one day's worth of website entries. Here's a typical _day template, one that corresponds to the above Weblog template.
Listing 2: a typical _day template
<div class="entry">
#foreach( $entry in $entries )
<div class="entryimage">
<a name="$utils.encode($entry.anchor)" id="$utils.encode($entry.anchor)"></a>
#foreach( $image in $entry.images )
#set($preview = $image.preview)
#if($utils.isEmpty($preview))
$set($preview = $image)
#end
<a href="#showNextEntryLink($pager)">
<img src="$url.site$preview.url" width="$preview.width" height="$preview.height" alt="$image.fileName">
</a>
#end
<div class="entrybar">
$entry.title
| $utils.formatDate($entry.pubTime, "EEEE MMM dd, yyyy")
| #showPopupCommentsLink($entry)
</div>
</div>
#end
</div>
And here's a point-by-point description of the template language expressions and statements found in the above _day template:
#foreach( $entry in $entries ) ... #end
Loop through day's entries. Here we use a $foreach loop to iterate through the $entries collection
<a name="$utils.encode($entry.anchor)" id="$utils.encode($entry.anchor)"></a>
Entry anchor. Create an invisible HTML anchor for this entry.
#foreach( $image in $entry.images ) ... #end
Loop through the entry's images. Her we use a $foreach loop to iterate through the $entry.images collection. It may be that the entry has only one image, but it is possible for an entry to have more than one image.
#set($preview = $image.preview) #if($utils.isEmpty($preview)) $set($preview = $image) #end
Get the image preview. To show a uniformed size of image for each entry, here we get the image preview; a resized version of the uploaded image (in this case the 800 pixel preview). In the case that the preview does not exist (due to the uploaded image being smaller than the preview) we default back to the uploaded image.
<a href="#showNextEntryLink($pager)"> <img src="$url.site$preview.url" width="$preview.width" height="$preview.height" alt="$image.fileName"> </a>
Display the image. Show the image and make clicking the image link to the next entry.
<div class="entrybar"> $entry.title | $utils.formatDate($entry.pubTime, "EEEE MMM dd, yyyy") | #showPopupCommentsLink($entry) </div>
Display entry title, date and comments link. Display the entry title and formatted date in a <div> so that it can be easily styled. If comments are available or are still allowed, display link to the popup entry comments page.
The Archives template
As well as the Blog page you may want to display an archive of your entries to browse through, or maybe another page showing all the thumbnails of your entries. We can do this in a similar way to the above Blog and _day; here's an example using a page we create named Archives:
Listing 3: an example Archives template
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>$model.weblog.name : $model.weblogPage.name</title>
#showAutodiscoveryLinks($model.weblog)
<style type="text/css">#includeTemplate($model.weblog "_css")</style>
</head>
<body>
<table border="0" align="center" width="95%">
<tr>
<td class="entries" width="80%" valign="top">
<h1>$model.weblogPage.name</h1>
#set($pager = $model.getWeblogEntriesPager("nil" ,5))
#showEntriesPager($pager "_archives")
<div class="bottom-next-prev">#showNextPrevEntriesControl($pager)</div>
</td>
<td width="20%" valign="top">
<h2>Calendar</h2>
#showWeblogEntryCalendar($model.weblog "nil")
<h2>Feeds</h2>
#showAtomFeedsList($model.weblog)
<h2>Search</h2>
#showWeblogSearchForm($model.weblog false)
<h2>Links</h2>
#set($rootFolder = $model.weblog.getBookmarkFolder("/"))
#showBookmarkLinksList($rootFolder false false)
<h2>Navigation</h2>
#showPageMenu($model.weblog)
#showAuthorMenu(true)
<h2>Referrers</h2>
#set($refs = $model.weblog.getTodaysReferrers())
#showReferrersList($refs 30 20)
</td>
</tr>
</table>
</body>
</html>
Let's look at the difference between this template and the Blog template.
<h1>$model.weblogPage.name</h1>
Display template name; Here we are showing the template name as a heading.
#set($pager = $model.getWeblogEntriesPager("nil" ,5))
Get entries pager and display the entries; Get the entries pager object so we can display entries and a paging control, set the gallery to nothing ("nil") and the number of entries to display to 5.
#showEntriesPager($pager "_archive")
Show current page's worth of entries. Calls on the specified _archive template to do the displaying of each entry.
The _archive template
Listing 4: an example _archive template
#foreach( $entry in $entries )
<div class="archiveEntry">
#foreach( $image in $entry.images )
#set($thumb = $image.thumbLarge)
<div class="archiveimage">
<a href="$url.entry($entry.anchor)" title="$utils.escapeHTML($entry.title)">
<img src="$url.site$thumb.url" width="$thumb.width" height="$thumb.height" alt="$utils.escapeHTML($entry.title)">
</a>
</div>
#end
<div class="archiveTitle">
<a href="$url.entry($entry.anchor)">$entry.title</a>
| #showPopupCommentsLink($entry)
</div>
<div class="archiveText">
<p>$utils.formatDate($entry.pubTime, "EEEE MMM dd, yyyy")</p>
<p>$utils.truncate($utils.removeHTML($entry.displayContent), 0, 400, "...")</p>
</div>
</div>
#end
Let's look at the difference between this template and the _day template.
#set($thumb = $image.thumbLarge)
Get the thumbnail. Gets the large thumbnail preview for the image (200 pixels).
<p>$utils.formatDate($entry.pubTime, "EEEE MMM dd, yyyy")</p>
Show formatted date. Displays the entry date formatted to Wednesday Jan 24, 2007 format. For more information read Date Formatting.
<p>$utils.truncate($utils.removeHTML($entry.displayContent), 0, 400, "...")</p>
Show entry content text. Display the entry content text without any HTML formatting (e.g. <strong> or <a href="">) and truncate the text if it is over 400 characters long. This can help preserve the formatting of the page when long descriptions accompany an entry.
Customizing your theme
When you start a pixyBlog website and you pick a theme, your website uses a shared copy of that theme. The page templates that define your theme are shared by all of the other users who have also picked that theme. Using a shared theme is nice because, when pixyBlog makes fixes and improvements to that shared theme, then you'll get those automatically. But you can't customize a shared theme. Before you can customize your theme, you've got to get your own copy of the theme's page templates like so:
- Go to the Preferences->Theme page: Login to pixyBlog and go to your websites Preferences->Themes page. Shown below;
Choosing a theme
- Pick and save the theme you'd like to customize: If you want to customize your websites current theme, then you can skip this step. If you haven't decided which theme to customize, then use the preview combo-box to pick the theme that you'd like to use as your starting point. Once you've picked your theme, click the Save button to save it as your current theme.
- Click the Customize button: Click the Customize button to customize your theme. When you do this the templates which make-up your theme will be copied to your website so that you can edit them.
- Customize your theme by editing and creating page templates: Go to the Preferences->Templates, edit your page templates and add new ones as needed â as described in the next section.
And if you get tired of your customized theme, just use the Preferences->Theme page to switch back to a shared theme â or pick another one to customize.
Editing and creating page templates
Once you've got the page templates copied into your website, you can do just about anything you want to your theme. You can use the Preferences->Templates page, shown below, to create a new page, delete a page or choose a page to edit.
Now might be a good time to describe the page template properties since you can see them in the table above. The properties are name, description, link, navbar and hidden. Let's explain each:
- Name: Each template has a name, which you can display in your templates. You can also use the #includeTemplate() macro to include the contents of one page in another, by referring to the template by name.
- Description: You can enter an option description for each page for display or just as a reminder to yourself as to the purpose of the page.
- Link: Each page template has a link property, which is used to form the URL for the page. For example, if the page's name is "simple" then the page will be available at the URL "/page/simple" within the website.
- Navbar: This is a flag that indicates whether the page is to be shown in the website navigation bar that is produced by the #showPageMenu() macro.
- Hidden: This is a flag that indicates that a page is hidden and not possible to access via URL. For new templates that you add, you'll be able to edit all of those properties using the Preferences->Template->Edit Template page (shown below).
But the rules for required pages are different. The website pages named Weblog, _day and _css are considered to be required pages. You can change the template code for those pages but you cannot edit the name, link or any other properties. Now that you know how to edit and create page templates, let's discuss how to use the models, objects and macros that pixyBlog makes available to template authors.