No one seems to get confused over setting up category groups, creating categories and assigning entries to them so I won’t cover that here (sales pitch - that process does get covered in step by step detail in my book).

The confusion seems to come from how to create a reusable template to display categorized results. The channel:entries tag has a category parameter that I think misleads people into thinking they somehow need to force-feed the entries tag with the ID of the category they wish to display, and if that’s the case then can you dynamically set that ID or do you have to create different templates with the ID hardcoded?

This isn’t the case - we’re actually looking at a situation where the dynamic property of ExpressionEngine is valuable.  If you haven’t yet, I would suggest a quick view of the dynamic=“off” explained screencast here on Train-ee.  While the parameter values have changed (EE1 was Off/On, EE2 is Yes/No) the functionality is the same. The screencast focuses on single-entry views but the channel:entries tag dynamically responds in a few different situations - reading single entry URLs, pagination URLs, archival URLs and - what we’re interested in today - category URLs.

How to Create a Reusable Category Template
Here’s a quick screencast that shows a simple EE template and how it responds when fed proper category URLs:

How to Create Category Links
Another short screencast shows how to dynamically create category links that feed the template the category URLs that it needs to be reusable:

Note: I didn’t code that second link correctly.  It should be:

How To Show Which Categories a Single Entry is Assigned To
This question comes up a bit - and the answer is the {categories}{/categories} variable pair for the channel:entries tag.  This is a “looping variable pair” meaning for every one entry in a channel, it will loop once for every category that entry is assigned to.  This is what allows a given entry to be assigned to multiple entries and have each of those category names get displayed for the entry.

In our little demo code it would be used this way:

If you wanted those to be links use the same {path= linking variable I showed in the screencast - again, because you're using it in a category context, it will return category links.

How to Display Category Hierarchy
ExpressionEngine lets you create a hierarchy in your category group, nesting categories and subcategories as many layers deep as you wish. The important thing to note here is that the hierarchy you create is for display only, not for URLs. In other words, the channel:categories tag I used in the screencast will return a nested list showing your hierarchy; but EE will not create URLs that display in a parent_category/sub_category fashion. Using native code, EE works with one category at a time in the URL and they will all display in the same /category/category_url_title fashion.

How To Show Category and Entry URL Titles in the same URL
So I’ve clicked the “salsa” category, got my list of results, and then click on an entry in that list like “Harrison’s Hot Trotters”.  Now I want to see a detail page for that entry that has a URL like: /cat_demo/salsa/harrisons-hot-trotters.  How do I do that?

The short answer is, you don’t.  At least not with native code.  EE just isn’t designed to work with URLs in this way.  Categories were designed to be a simple filter used to whittle down a long list of entries to something more manageable.  Once you chose an entry from that list your URL is going to lose the category information.  One reason for this is that ability to assign an entry into multiple categories - if the category stayed in the URL you could end up with the same single entry showing at multiple URLs.

I don’t believe EE categories were ever designed to be used as a navigation-building tool.  EE has a blogging heritage and its category functionality grew out of that - giving users the ability to filter a large set of blog entries down to just entries in designated categories.

You Keep Mentioning Native Code…
As usual with ExpressionEngine any time the native abilities come up short the 3rd party market rushes to fill that void.  There are a number of category-related add-ons available and in future posts I’ll look at a couple of them that can ease some of your category pain.

Gulp….“Let me think about that one for a bit…”

Not an unreasonable request, right?  As a consumer I’ve often used such tools to quickly compare multiple products I was interested in purchasing.  Comparison tables can quickly help you find differences and similarities that would be tough to see bouncing around different product-specific pages.

But how to pull this off on an ExpressionEngine based site?

As is so often the case with EE, what looks difficult at first blush turns out to not be too difficult.  Let me show you the front end of what I came up with so you can better tell if it’s close to what you need:

Overview

• The drop-downs are dynamically populated from channel:entries tags so if our client adds or deletes products he won’t have to worry about replicating those edits for the drop-downs.
• While the drop-downs display entry titles, you are really choosing entry_ids.
• When you click “Compare” a bit of javascript grabs the entry_id’s from the 3 drop-downs, appends them onto the URL and reloads the template.
• Additional channel:entries loops then see those entry_id’s and use them to retrieve the content for the chosen entry.
• Each column is actually its own HTML table, floated using CSS to create the side-by-side view.

Main releases/compare Template
Let’s work through the main template (available as a download):

This is the javascript that assembles the expected page URL including the 3 entry_id’s from the selected products.  If you use this code make sure to change the site= parameter to the URL to your comparison template.

Just some basic CSS mainly to get the result tables to line up by floating.  I went this route because it made exception-handling much easier (what if user selects an option only from the first and third boxes, etc). 

These are the dynamically-generated drop-downs.  It may or may not make sense to chunk these out into a reusable embedded template or snippet, but since they are pretty simple I just left them this way. All we need are the default fields from the channel so our disable parameter can disable everything else for best performance.

This conditional displays the comparison table labels if the template has been loaded with entry_id’s showing in the URL.

These conditionals pull in the embedded template that displays a column.  Since the columns need to be identical and only need to look at a different segment for the right entry_id to pull content for, I created an embedded template and just pass the segment variable as an embed variable.  While the comparison column in this tutorial is simple, the odds are that on a production site it would be much more complex and you might as well only create that table once.

The embeds/comparsion_column Template

Pretty straightforward here, we just use the passed-in variable to determine what URL segment to grab the entry_id from. 

Wrapping Up
So there you have it - with a small bit of javascript together with native ExpressionEngine tools like segment variables, conditionals, embedded templates, and embed variables, you can pretty quickly pull entries from a channel and display them in a side-by-side comparison table for happy users.

The functionality I needed was exactly the same as the native Monthly Archive tagset, but for weeks rather than months.

If you’e used the Monthly Archive tagset, you know that it creates links that take advantage of the dynamic aspect of the exp:channel:entries tag in that the Monthly Archive tag generates URLs that have month and year as URL segments (example.com/blog/2011/06/) and that URL structure is how an exp:channel:entries tag running in dynamic mode knows which entries to pull.

Pretty cool, but for me it means that the means by which EE can pull monthly archives is pretty well-baked into the system and not easily tweaked for my purposes.  Searching the EE aftermarket reveals a Yearly Archives plugin by Low, but that’s making the bucket bigger rather than smaller.  Not finding any other add-ons I had actually written and sent an email to the client saying I couldn’t do the weekly drop-downs and had setup the page to use a monthly drop-down and the native Monthly Archives function and that would have to do until/unless I “had a bright idea”.

And - you guessed it - it wasn’t 1/2 hour after sending that email when I had that bright idea.  Or at least enough of a spark to get me doing the experimentation that led to a solution. Below is the solution I came up with - it’s working on our development system with some test content.  It’s not a perfect solution - let’s look at the code and then I’ll point out my concerns with it (note that this is a simplified version not involving a drop-down):

So, two loops.  Let’s look at the first one:

Date Heading
ExpressionEngine has a blogging heritage (although that’s less obvious as time goes on).  One of the parameters for the workhorse Channel Entries tag pair is the date_heading tag that allows you to group channel entries in certain time-buckets (daily, weekly, monthly, etc).  The functionality it’s bringing to the table here is letting me build a list of weeks that have entries. 

Week Date
I’m using the week_date variable here - I think for the first time ever in an EE project.  The week_date variable establishes the starting point for the week-bucket to group our entries into.  It defaults to starting weeks on Sundays, if you want to change that use the start_day parameter.

Link with Custom Segment
The final point of this first loop is to get the unique week number into the URL.  I’m doing that by taking advantage of EE’s segment variables.  To create the link I’m just appending on a custom segment to the normal link built by the path variable.

The first loop nets me a list of linked weeks that have entries in them.  Clicking one of the links refreshes the page but with a week number now appearing in the URL - now let’s look at goes on in the second loop.

This is pretty straightforward - we set dynamic to off so this tag ignores the URL.  Then it loops through all entries in the news channel and compares the week of the entry date to the week number appearing in the URL.  If it’s a match the title is shown.

Performance?
My only concern with this approach is performance.  In my case I don’t expect the news channel to have thousands of entries but rather dozens with maybe 8-10 entries per week. This particular project is also not a public one, but rather with a couple of dozen targeted and logged in users.  So for me I think the performance will be OK.  If your project requirements are different this approach may need some stress testing before using.

Not Quite Done
The above code works great after a week has been chosen, but I also needed the page to display the current week’s news by default.  Here’s my revised code:

The last loop is the same, just wrapped in the conditional that looks for a week having been selected.  The newly-added middle loop runs if no date has been selected and the key there is the display_by parameter that returns a single week’s worth of entries.  I may also have to use the show_current_week parameter but I’m not sure yet and am waiting for the system to be used more to see if the right results are returned.

So there’s my “bright idea” for weekly archives in ExpressionEngine.  Now if I’d just had it before telling the client it couldn’t be done…

Disclaimer
I haven’t worked with all of these add-ons and this post is not meant to be an in-depth review of what they do and how well they work.  I am currently using one of them on a client build so can comment more deeply about my experience with that one.  The list below is in a relatively simple to complex order starting first with Accessories and other little UI helpers and moving towards Add-ons like Taxonomy and Structure that can radically alter the way you work with ExpressionEngine.

• Pages Autocomplete - Free
  According to it’s developer “Pages Autocomplete is a simple accessory that turns the ‘Pages URI’ field on the publish page into an autocomplete text input.”
• Page Helper - $7
  One of the challenges with the Pages Module is that the Page URI field has no help - it’s entirely up to your users to enter a correct and valid path and title.  To ease this process Page Helper lets users select a parent page, then pulls the URL title from the entry.  These elements get put together to form the Page URI.
• ‘Plates - $10
  Along with a Page URI there is also the template choice to worry about clients getting wrong.  According to it’s developer “This fieldtype for ExpressionEngine 2 is a drop in replacement for the native Pages Module or Structure Module ‘Template’ field. No longer do you have to present your client with a confusing + long drop down list of templates to choose from. With ‘Plates you can give your templates meaningful names, thumbnail previews and publish notes.”
• MX Extended Content Menu - Free
  While the main purpose of this Add-on isn’t Pages Module related, a secondary function of it is building a Control Panel submenu for your Pages Entries—as a way of getting to them quickly for editing.
• Easy Page Links - Free
  Sometimes making a content-based link from one entry to another is a harder process than it should be in ExpressionEngine - mainly because content doesn’t normally get directly to an output URL. The Pages Module does that mapping however, so this accessory “extends the functionality of the default link HTML formatting button. The link button will now open a modal window which lists the current pages from the Pages module and also has a text input field for custom URLs”.
• CrumBum - Free
  Over the years I’ve seen many requests for an automated way to build breadcrumb trails in ExpressionEngine.  If you aren’t using the Pages Module that’s pretty tough to do - but if you are using Pages then this add-on could prove handy.  According to it’s developer “Crumbum is an ExpressionEngine 2 and 1 plugin that automatically generates breadcrumbs in your templates based on the URL structure of entries managed by the Expression Engine Pages Module”.
• Better Pages - $15
  Better Pages can limit Pages templates to only those that are actually useful for a specific custom field group.  You can add thumbnails for your templates to make selection even more intuitive, and it will narrow fields displayed on the publish/edit screen based on which template is selected.
• NavEE - $35
  NavEE lets you manage multiple navigation bars using drag & drop to sort them.  It can dynamically apply active classes applied to either standard nested lists or custom HTML, generate Breadcrumbs, and more.
• Taxonomy - $25
  According to it’s developer Taxonomy “is a navigation/breadcrumb building tool which uses nested sets to control hierarchy.”  Taxonomy lets you build links either using or not using the Pages URIs from the native Pages Module.  You can either build your Nav and then choose entries to assign to that navigation item, or use the included Fieldtype to assign an entry into the navigation right from the Publish page.  I’m currently using Taxonomy on a client site - see my comments after this laundry list.
• Blueprints - $35
  According to it’s developer “Blueprints lets you take control of your Publish Layouts and take Member Groups out of the equation. It is designed let you create Publish Layouts based on templates, not Member Groups. No longer will you have to tell your client “Ignore this custom field, it won’t display in Template A, but works in Template B” or, “Ignore all these templates in the drop down, just use Template B or Template C for this Channel”. Nor will you have to create different channels for different page layouts. You can create a single “Pages” channel, assign it custom fields, and use that one channel for all your page types.”
• Structure - $65
  No list of Pages Module related add-ons would be complete without the ever-controversial Structure Module. According to it’s developer “Structure is a powerful add-on that lets you create pages, generate navigation, manage content through a simple interface and build robust sites faster than ever. It forgoes the current template_group/template setup and creates “static” and “listing” pages that are all editable through a tree sitemap view. Now, traditional page style content and multiple entry pages can live within the same area.”  I’ve yet to have a project that felt right for Structure, but know that there are many in the EE community who wouldn’t build and EE site without it.

Taxonomy Use Case
I mentioned above that I’m using Taxonomy on a current client project so I wanted to fill in a bit of the reasons why and comment about how it’s gone so far. 

The project started with an EE 1x site that I didn’t build.  It was done a few years ago by an agency that has since closed it’s doors.  I’m not sure if this particular site was one of their first ExpressionEngine jobs, but there were some puzzling aspects to how it went together.  For example, the Template Library was filled with page-specific templates that were all exactly the same, save for the fact that they specified a different entry_id to pull for content.  I’m not sure the developer fully understood how ExpressionEngine works dynamically with URL’s.  Every time they needed a new page on the site, an existing template would be copied and the hardcoded entry_id changed in to pull the newly published content. 

In addition to the template mess the other aspect of the site was that one weblog was storing content for multiple sections of the site.  About Us content was stored in a catch-all “Pages” weblog along with more business-focused content (and the templates sorted it all by using the hardcoded entry ID’s).  Now throw in the main reason for my involvement - the client wanted to reshuffle the site’s information architecture to reflect an updated way of communicating their business structure.  And by the way, can we keep the amount of content editing & reshuffling to a minimum?

Enter Taxonomy.  With it I can keep the content stored the way it is and let the client assign existing entries into the revised navigation structure using the Control Panel tools the Taxonomy Module provides. After a bit of phone training they seem comfortable using the Taxonomy fieldtype to also assign newly published content into the navigation structure.  I’ve got them working with just one menu so we’ll see how things go when I add another - but during the training they were quite enthusiastic about being able to control their navigation using the drag & drop interface Taxonomy provides.

While working with Taxonomy I’ve run across the odd broken link in the documentation and did have to apply one change to the code itself (which was included in a subsequent release). Developer Iain Urquhart has - in spite of our vast time zone differences - been very responsive to my questions and ideas for improvements to the product. 

And So?
This is the end of the line for this series covering the Pages Module.  Have experience with these add-ons?  Know of something that I missed?  Feel free to comment and let me know the error of my ways…

Sometimes the best way to see if a particular feature is valuable or not is to look at what use others have found for it.  I’ll include my use of the Pages Module at the end of this entry but thought I would also post some responses from other EE developers here as well.

Note that many of the comments around using the Pages Module were interspersed with comments about using some of the related add-ons, which I want to cover in the next and final chapter on this series.  My editing may be a bit heavy handed but I wanted to focus on just the Pages related portions of the comments here.

I’m using Pages module now to simply give me URL’s without the template_group in the URL structure. I’m using a static/index template for my static pages and then with the Pages module I can specify “/about” to be the Pages URL and get an nice looking URL like domain.com/about rather than domain.com/static/about. Clients will still edit the entries in the Edit menu like usual. So, my use of the pages module is pretty basic.  via Deron Sizemore

I’m using the pages module on a complex site I’m building right now. Most of the content consists of 4 different channels in different sections, but they also have pages like, About Us, Terms of Service, Privacy Policy, Contact Us, etc. These pages fall outside the regular norm of continual publication. That’s where I find the pages module is useful. via Bransin Anderson

I use the Ellislab Pages module a lot now, but my use is probably not typical. I use it for just one purpose: as a way of allowing editors to have fine-grained control of their URLs. I describe the Pages tab as a way of overriding what the default url would otherwise be for that particular entry. This is useful not just for SEO purposes, but also allows the Marketing department to send out short, friendly URLs in mailings and offline media. I don’t typically give access to the back end of the Pages module (the bit with the hierarchical listing), because in this context it’s misleading and somewhat useless. I like this approach because it feels like progressive enhancement: I could switch the module off at any time and the site would still work fine - I have no reliance on it. via James Smith

As for me, I’ve only used the Pages module to any extent on two sites and in both cases the use was the same.  These clients wanted one-off pages that didn’t exist in the navigation on the site and wanted to be able to specify the URL that the page appeared at.  They were usually doing a specific marketing campaign where the URL was going to appear in print so it needed to be as short as possible.  The content on the page also needed to be flexible.  I ended up creating dedicated “pages” channels, with one custom field for “content”.  That field was set to “none” for formatting, which allowed the clients to drop in any HTML for any type of media - Flash pieces, videos, photos and text, or survey forms where another app generated the HTML. In both cases the clients were very HTML savvy and I wasn’t concerned that they were going to publish a broken page.

In both cases the client were happy with what the Pages Module did for them - which was essentially work outside of the carefully crafted content management rules we had put in place for the rest of the site.

How about you - have you found a use for the native Pages Module not listed here?

Installing the Pages Module
The Pages Module User Guide covers the process, but overall it’s easy because the Pages Module is first-party and included with the default EE2 installation.  Navigate to Add-ons > Modules, scan the list, find the Pages Module and click the “Install” link.  The install process should return you to the overall list of Modules, but now the Pages Module title should be an active link, and it should be listed as “installed”.

Configuring the Pages Module
The Pages Module is usable already, but you’ll want to review its configuration settings to make sure it’s implemented the best way for your site. If you aren’t already there, navigate to Add-ons > Modules > Pages > Module Configuration.

The User Guide does a good job of explaining the settings that are available, but I’d also like to point out a couple things that aren’t immediately obvious:

• Choosing a default Channel for Pages Entries doesn’t restrict other Channels.
  All channels are eligible to post entries into the Pages Module unless you configure EE otherwise.  With the Pages Module now installed, visit a Publish page for any of your channels.  You’ll see that the Pages Module has added a Pages tab to all of them—even the ones you’ve carefully made a Publish Page Layout for.  To prevent content authors from sending unexpected Channel entries into the Pages module you’ll need to first set the default, then go through and remove the Pages tab from the Publish page layout for all inappropriate Channels.
• You can only choose one default Channel
  If you have more than one Channel storing Pages Entries you’ll need to not set a default, because then EE will hide the list of channels when you click “Create Page” from the Pages interface.
• You can set a default template, but you can’t hide the rest
  You will be exposing your template library to content authors and most times there is one right “Pages” template choice and a whole lot of wrong ones.
• The Pages screen is buried
  The Pages Module does not change your top-level EE Control Panel navigation, so it’s best to use the My Account area customization abilities to add a top-level navigation option to the Pages screen.

Pages Module Use for Content Authors
There are two workflows to creating a “Pages Entry” - you either start from the normal Publish menu or from the new Pages Screen. There is little difference - either way you have to choose a channel to store the Pages Entry, enter the content, and then do two things that makes a Pages entry unique; chose an output template and assign a “Pages URI”.

Wait, what?
Output template and URI? 

This is where the Pages Module gets both potentially powerful and potentially confusing depending on your project and your content authors.  We’ll get to template coding in a moment, but one of the advantages of the Pages Module is that you can feed one template with content stored in different channels with different url_titles or entry_id’s all through one template, without having to re-code the template or put in a bunch of conditionals and segment variables, and without final url implications.

Remember where the Pages Module User Guie said one of the features was “Use virtually any URL to display the page”?  The “Page URI” field is where that feature comes to fruition. You simply enter the address you want this content to be found at (following some simple guidelines).  ExpressionEngine will append your value here to your site domain and index.php (if you haven’t removed it) and use that as the final URL for this content.  For example, if you specify a Page URI of:

Then your final URL (assuming you haven’t used .htaccess to remove index.php) would be:

Pages Hierarchy
The Pages Module will display a hierarchy in the EE Control Panel if you’ve configured it to and have Pages assigned URI’s that contain hierarchy.  To see how it works first visit the Pages Module configuration screen and set “Display of URIs on Module Homepage” to “Nested”.  Now create a couple of Pages entries with URL’s along the lines of:

Now in the Pages Module interface you get a hierarchical view (see screenshot).

Pretty cool - for some sites and content authors this may be a more helpful way of finding, editing, and viewing the content they want to edit.

Coding Templates to Display Pages Entries
Again, start with the EE User Guide around displaying Pages entries.  At its simplest this template can look like:

Parameters
The above example is admittedly a pretty simple channel:entries tag - let’s look a bit deeper at what code we can, can’t, and should do to display a Pages entry.  According to the User Guide:

On the template assigned to a Page entry, use a normal Channel Entries tag with any parameters and variables that you desire to display the entry

This statement paints with a pretty broad brush and I’d argue that it’s too broad.  There are many parameters for the channel:entries tag that you wouldn’t (or couldn’t) use when displaying a Pages entry:

• url_title
• entry_id
• offset
• orderby
• search

That’s just a quick and non-inclusive list.  The general guideline is that any parameter you would normally use to affect what entry or entries are returned would be inappropriate on a Pages template - because the URL already determines what entry will be returned. Also any parameter that would cause the channel:entries tag to return or act on multiple entries (ID ranges, date ranges etc) would be inappropriate as well.

Some other parameters of note:

disable= Parameter
I hate the term “best practices” - but if there are any in ExpressionEngine one of them is to use the disable parameter as a means to eliminate unnecessary queries generated by the channel:entries tag and as a result improve page load time.  It’s no different when displaying a Pages entry - adding “disable=“member_data|pagination|categories” reduced the queries on my test page by 3.

limit= Parameter
I often use a limit parameter on single-entry templates to ensure they only ever display one entry no matter if someone tries to manipulate the URL.  When I tried this on my sample template I ended up with an additional query, so it might be best to not use it here.

show_pages=“only”
This is a new parameter that the Pages Module brings to the table, and at first glance you might think of using it like the “limit=1” parameter to ensure that your Pages template only displays Pages entries.  If you add it to the template, however, what you’ll get is a listing of all your Pages entries.  This parameter is intended to be used to build navigation to all of your pages entries - so used in a sidebar where it would be added to a second channel:entries tag pair. Note that it essentially does two things - sets dynamic=“no” and returns only Pages entries.

The kicker with the show_pages parameter is that it only returns a flat list of Pages entries. No hierarchy. No sense of parents or children.  It’s especially frustrating because you can see that hierarchy in the Control Panel but can’t get it to display on your site. The Pages Module is almost the evil identical twin of EE’s categories which will render a hierarchical list to the site but keeps all URLs flat.  Pages will create hierarchical URLs but you can’t get EE to render a hierarchical list on the site.

What About Variables?
That covers parameters, what about the other arrow in our EE-quiver - variables?  ExpressionEngine has a Number of Variable Types, all of which will work within a channel:entries tag pair returning content from the Pages Module.

And that, my friends, is something I learned while writing this article.  For some reason, somewhere, I got it stuck in my head that a template used to display Pages content at a Pages URL could not use segment variables in conditionals because the URL was essentially “masked”.  I’ve said as much in numerous EE discussion forum threads.  In coding a template to verify things I’m saying in this article, I quick threw some conditionals in like:

And now I can’t get them to not work.  I even had to go back to an EE 1 site and sure enough, works there too. I’m not sure where I got that idea from.  Or why no one ever caught it in the forums..;) If I’ve misled you in this respect I apologize!

What Do You Give Up?
My misunderstanding of segment variables aside, there are still some possible drawbacks you need to know about if setting out to use the Pages Module.  There is a sneaky sentence in the Pages Module User Guide that says the following:

the page will automatically be treated as a single entry page for that page entry, so other tags on the template will need to use the dynamic=“no” parameter (if available) to display other content.

Pages templates are all about displaying the Pages entry at the URL you made up.  The casualty in this feature is you’ve lost the ability for all other tags to work in the dynamic mode that you’re used to everywhere else because that dynamic mode relies on a formulaic URL structure.  Given the number of ways just the channel:entries tag works dynamically, this can be quite a drawback.  Category pages, paginated content, and date archives all rely upon ExpressionEngine’s URL structure to know what content to return so would be unusable at a rendered Pages URL. 

What’s Next?
We’ve covered the history and purpose of the Pages Module.  We’ve looked at how to install it, what it means for content authors, and how to return Pages entries from a template.  We’ve looked how the Pages Module works with some parameters and variables, and what you give up to get the features of the Pages Module.

In the next (and I suspect, last) installment of this series we’ll look at how people are using the Pages Module, and what the 3rd Party Add-on market brings to the table to extend the native abilities of the Module.

I set about to write a comprehensive article about the module - what it is, where it came from, why it was developed, what it does, what it doesn’t do, what it prevents you from doing, how people are using it, and how 3rd party developers are extending it.  As I started putting the article together it started getting pretty long, so I’ve decided to break it up into either a 2 or 3 part series.  This first installment covers the basics of what the Pages Module is (and isn’t) and takes a look at the history of the module with interviews from a couple of the key developers in its history.

What this article won’t do is talk in great detail about 3rd party addons like Structure and Taxonomy. While they are part of the Pages Module lineage I haven’t yet used either one of those tools and would rather not cover them without direct experience. But hey - that’s what comments are for, right?

“What’s this stuff? Some Cereal.  Supposed to be good for ya.”
So what is the Pages Module?  Your first encounter with the Pages Module may be in the Addon-Ons > Modules area of ExpressionEngine where it says:

Uses Channel Entries to make Static pages

Oh, cool, so this module creates static .HTML files from my channel entries, which should load faster.  This is a performance-related module then?

Let’s read on, now from the description from the Pages Module documentation where it says the module: 

allows you to easily create and maintain page content that is more akin to static content than dynamic information.

How much more akin? Is the content stored differently somehow?  Is the whole page managed this way, or just parts of it? Is the process for creating new “pages” different than an “entry”? Is there a difference between “content” and “information”? 

Reading on:

Additionally, these special “page” entries can be displayed with virtually any URL desired.

Now there’s some meat. ExpressionEngine by default has a relatively prescribed URL structure.  How you name and organize your templates and template groups has a direct effect on your generated URLs. Most times that’s fine, other times it’s a barrier to another goal. Being able to work outside that structure when desired is handy.

The documentation lists some additional features:

• Allows content authors to add and maintain pages without needing access to Templates
• Enjoy the full flexibility of channel entries in how your “page” information is entered
• Use virtually any URL to display the “page”

#1 is reassuring.  I certainly don’t want content authors to need access to templates.  But wait - does that mean if I don’t use the Pages Module they’d need access to templates? #2 just tells me I haven’t lost any flexibility - so that’s good.  #3 re-iterates the point made above.

So the Pages Module is…anyone?  Anyone?
So some of the confusion around the Pages Module comes from the EE documentation because it doesn’t fully explain what the module is and is not.  Here’s my take on it - the Pages Module is primarily a way to:

• allow content authors to define a URL to the content.
• allow content authors to define content heirarchy by creating URLs that establish it.
• provide content authors navigation to edit existing Page entries that reflects heirarchical URLs.
• allow developers a way to offer content authors different “output templates” for their Pages content, without affecting URL structures.

The Pages Module is not:

• a way to have ExpressionEngine generate true static .html files from rendered content & templates.
• the only way to prevent content authors from needing access to templates.
• a significantly different way for content authors create or maintain page-based content.
• usually the basis for an entire website built in ExpressionEngine.

“Just sit right back and you’ll hear a tale / A tale of a fateful trip”
Later in this series we’ll look deeper at the ins and outs of the Pages Module, but first I wanted to to look at where it came from and why it was developed. 

Mark Huot’s Tome
As with many of the significant ExpressionEngine Add-ons, the Pages Module started with Mark Huot, Technology and Development Director for Happy Cog.  Mark wrote a module initially called “Pages”, later renamed to “Tome” after ExpressionEngine came out with its first party Pages Module.

Tome’s approach was to use one weblog as the Tome weblog. You’d create a category group for this weblog and use ExpressionEngine’s category management tools to establish a hierarchical structure (think one category per page).  Once the hierarchy was established you would use the Tome interface to get to a node to edit the content there.  Or, you could feed other weblog content in at a specific node by changing the module configuration, routing its output to a different template.

Mark graciously agreed to answer some questions about Tome as background for this article:

What was your reason for developing Tome?  Was it for a specific client project or something you wanted to provide for the community?

It was developed for the community. I was enjoying EE development so much I started comparing EE to other platforms. I noticed WordPress had a great “pages” feature that allowed you to create one-off static pages. EE was sorely lacking in this area. I had noticed many tutorials on how to use weblogs and nested templates to re-create this kind of functionality, but they all felt like hacks.

It only took a few hours to get the initial proof of concept up and running. EE’s extension hooks (at the time) were far too generous and allowed me to hook in to the very underlying functionality of the system. I was able to rewrite important aspects of the URL routing engine and generate a static page.

What advantages did you feel Tome offered over what EE did natively?

At the time EE didn’t offer anything like this. Its advantage was that it allowed me to break entries free from their channel and allow them to live on their own as stand alone pages.

Did you feel Tome had downsides to being used (did it play well with segment variables, pagination, categories, embedded templates etc)?

Yes, it had many downsides. The biggest of which being 1. my ability to support it and 2. its hacked implementation on top of EE. While I was able to get it to play nicely with most segment variables and categories, pagination was always a bear.

How similar or different to Tome is the native Pages module?

All in all, it was awfully darn similar. The biggest difference was the UI of the CP. I had a release just about ready to go out at the time that Pages was released which enhanced the CP UI to add expand collapse support, drag and drop support and a slew of smaller UI tweaks. Those features never saw the light of day, and unfortunately never made it into the native Pages module either.

With the current state of EE and the addon aftermarket, how would you meet the project requirements today that caused you to create Tome at the time?

The short answer is that I use Structure for most of my development now. It’s robust and offers a much cleaner UI for content editors to get content into EE.

As an aside, Train-ee traces its roots to Tome, as some of the first tutorials I wrote were how to use native weblogs and templates to create “static” content with dynamic navigation.

“Rumors of my assimilation are greatly exaggerated.”
Or not in this case.  ExpressionEngine version 1.6 - released in June of 2007 - included a new “Pages Module” that assimilated some of Tome’s features.  The primary ExpressionEngine Developers at the time were Paul Burdick and current EllisLab President/CTO Derek Jones.  Paul Burdick handled the ExpressionEngine Pages Module and also agreed to answer some questions about it via email:

What were the reasons for developing the Pages Module?

Mark Huot had written a very popular module called Pages that allowed one to organize content into a hierarchy while also dynamically generating navigation for those pages.  It was extremely popular as it allowed people to create a slightly more custom site structure.  Do not remember how it worked exactly.  However, there were a couple bugs that were causing EllisLab to take notice of it, specifically it killing sites with load and install/uninstall/update issues.  Mark was working on a new version but with his client work and other responsibilities it was delayed.  Since it was popular and seemed to fill a need, EllisLab decided to build their own version with a tighter integration in ExpressionEngine, which allowed the load to be greatly reduced.

What advantages did you feel the Pages Module offered over how EE worked before it existed?

The original intention was to allow users to use entries and templates to create a site structure more fitted to their needs and outside the standard template_group/template URL structure.  Essentially, a single entry displayed by any template at any URL they dreamed up.  Any hierarchy would be on whatever URL structure they created.  Extremely basic functionality, honestly, but something that required modifying the core.system.php file to override the use of the Template class.  Also, it allowed designers to create content on the site that was only displayed on a single page (ex: an about page) that was editable in the Publish area by their content editors without needing to touch templates or global variables.

Did you expect that people would use it as the basis for an entire site or just portions?

Definitely portions.  An entire site being created with Pages was not even on the radar.  It was a rather lightweight addition to EE 1.6.

Is there a reason the module never went further with more dedicated tag pairs for building navigation and breadcrumb trails?

If people remember, the real effort for building ExpressionEngine 2.x started in 2007 at EllisLab.  On some level, EllisLab and specifically the development team was spread a little bit thin the latter half of that year with ExpressionEngine 1.x, CodeIgniter, and ExpressionEngine 2.x work.  Derek Jones and I were the only full time developers working on ExpressionEngine for most of that year too.  So, expanding Pages was not a priority.  Further, looking back at the EE 2.0 To Do list now, one of the highest priorities for ExpressionEngine 2.0 was a rewrite of the Template parser.  And one of my goals with that was to allow more flexibility in how the site structure could be set up via templates.  Obviously, with my departure in early 2008 and the delays with ExpressionEngine 2.0 being released, those two goals were never realized.

Were/are you happy with how the module currently functions?

Looking at it now, no, I am not pleased with how it functions.  However, I understand why it was written so simply at the time and that we were *planning* on making much more powerful functionality possible in the future.

Do you feel there are downsides to using the Module and if so, what are they?

Honestly, it is way too simple and not easy enough to create Pages and build a hierarchy (especially seeing the current hierarchy and adding to it).  Once again, so much of this seems like something destined for the “Design” area in the CP, as it is a amalgamate of Publishing and Site Structure.

What are your thoughts on how the addon market has extended the use and overall direction of the Pages Module?

Except for Structure, I am not familiar with how the Add-On market is affecting or has been affected by Pages.  I tried using Structure during the first EECI Conference in Leiden, but it never tickled my fancy.  My personal needs in ExpressionEngine have always run towards the amazingly bland and simple or so extremely specific/complex that I have had to custom build my own Add-Ons or hack ExpressionEngine itself.  Professionally, I have not had to work with either Pages or Structure while working with Solspace.

What’s Next
In the next installment of this series we’ll cover how to install & configure the Pages Module, how to code a template to display Pages Module content, and what using the Pages Module means for content authors.

Thanks to Mark and Paul for taking the time to respond to my questions, and thanks to Eric Barstad of Shadow Box Creative Media for supplying the Tome screen captures.

Project
The project at hand was school website.  The site is fairly large with 8 main areas of content to cover it’s preschool through middle school offerings.  I was contracted to take a new site design and power it using ExpressionEngine.

Whoa - Old Skool?
The project started some time back when the released version of EE2 was relatively new, so after some discussion with the client we decided to stick with EE1 for its stability and more well-rounded market of addons. Don’t let that keep you from reading, as this approach to solving a similar design & implementation challenge would be easy to port into EE2 by just changing the {weblog} related code to {channel}. 

Challenge
As I looked through the provided design comps I noticed that the sidebars had a number of different content elements in them.  There were little blocks just a quote. There were photos with a blurb of text and a link.  There were lists.  There were Bible quotes. There were Google maps.  Immediately some questions starting coming to mind:

• How many of these things are there?
• Are they the same throughout the site, or are they different in each section of the site, or are they different at the page level?
• Do they need to randomize?
• Is the ordering of them always the same?
• How much control does the end client need over these items?

As expected, the client wanted very precise control (do clients ever want anything less than complete control?). They wanted to choose sidebar items and set the sort order per page. Sidebar items needed to be reusable (one element being used on a variable number of pages across the site).

Native?
Could this be done with native ExpressionEngine tools?  I quickly ran through the available tools - relationships, categories, custom fields for setting sort order, etc. It was immediately apparent that for this requirement the native EE abilities weren’t going to cut it. 

Look to the Aftermarket
I knew that Playa offered ability to multi-select select from multiple weblogs/channels and had a drag / drop interface for for ordering selected items.  That was the Control Panel interface my client needed, no question.

Implementation

• Content-Specific Weblogs/Channels
  I setup per-content-type weblogs/channels for each type of sidebar content (picture, quote, graphic, video, etc). Some of these content types are left or right column specific and some can be used on either side (as determined by the design).  I named them accordingly (Sidebar Either Text Box, Sidebar Left Graphic etc).
• Playa Fields
  I created two Playa fields in the field group storing page content - one for the left sidebar, and one for the right.
• Template Code
  Each type of content has unique markup, so the template code uses conditionals within the Playa tag pair.  After determining what weblog/channel the result is from, the correct markup is applied to the returned content (code snippet available as a Companion File to this article)

Content Management Workflow
The client first publishes content to the proper sidebar weblog/channels.  Once the content item has been published it’s now available to the ExpressionEngine entry that holds the main page content. Now when they create or edit a page they use the two Playa fields to find the sidebar element they want, select it, then drag & drop to sort it correctly.

Results
The feedback I got with the approach was fantastic - I got word that the end client was “having fun” setting up his pages.

Fun?  Whodathunk!

Playa is a great add-on (actually a bit of a no-brainer to write this article about). I don’t use it on every site, but when the need presents itself - like on this project - it can definitely solve a requirement puzzle and help you look the hero to your clients.

Static pages.  Dynamic content.  Clean URLs.  Databases.  Templates.  Flat Files.  Publishing systems.

We’ve created a puzzling environment for putting content on the web, and the way different technology vendors use the same words with different meanings attached can make learning a new system a nightmare for anyone, much less someone new to the whole deal.

In a recent forum post a newcomer to ExpressionEngine posted:

I’ve been confused about “static” pages and “dynamic” pages so the post above this makes no sense to me. I like to use wordpress for any blogs that I do and I’ve always been told to make whatever page I want to show up better in the search engines a “static” page. Is a “static” page in wordpress the same as a “dynamic” page?

I responded in that thread, but also wanted to post the response here on Train-ee because understanding ExpressionEngine’s approach to “static content” is fundamental to understanding how the system works, or can work.

I Do Not Think That Word Means What You Think It Means

Static content is confusing because there are three mindsets driving the terminology: content management,database/backend/implementation, and search engines.

From a Content Management Perspective:
This perspective looks at the nature of the content rather than the implementation. 

Static pages can be defined as those that are not likely to change very often.  About pages. Contact Pages. Terms of Use. Write them once and they probably aren’t going to change - hence they are “static.”

However there is content that changes often.  Blog index pages change whenever you post something new.  Product content changes with new releases. Staff profile pages change when someone leaves or someone new hires on.  Because the content changes more often it’s “dynamic”.

From a Database / Backend / Implementation Perspective:
This perspective looks at the nature of how the content is stored on the server rather than the nature of the content itself - ie is the content stored in a database or in a text file?

Static pages are those where when you navigate to http://mydomain.com/about/the_company.htm there is a /about/ directory on the server with a text file named the_company.htm that contains HTML, CSS, and content.  It’s “static” because the file gets created and sits on the server.

With EE everything past /index.php/ in the URL doesn’t necessarily exist on the server at the file level.  When that URL is requested EE goes to its template library and creates the web page on the fly using instructions found there.  The result only exists in the users browser - so it’s “dynamically-generated” page.  Things get a little fuzzy here because EE allows developers to store their templates either as flat-files on the server or in the EE database - but either way those templates are not visible to end users, only the pages created by the templates.

From a Search Engine Perspective:
This perspective (at least as it relates to the topic at hand) is mainly concerned with URL formations. Dynamic content has historically had ugly URLs - like something from Amazon:

Search engines had a harder time indexing this content, and even when it was indexed it wasn’t ranked as highly due to the ugliness of the URL (and because some of those numbers were user ids or session ids that didn’t apply to everyone navigating to that page). 

What the search engine wanted instead was something like:

Not only is the URL more “readable” by humans, the search engine can more safely assume this is a good indexable page, not likely to change, not containing use or session-specific content, and of good general interest to their users.

Soooo…What’s “Static” Mean in ExpressionEngine?
From a content management perspective content can either be static or dynamic. EE handles any sort of content well, from never-changing About pages to constantly-changing Blogs. From a database/backend/implementation perspective pages are (usually) all dynamic.  From a search engine perspective it’s the best of both worlds - dynamically generated with with clean URL structures.

As an EE developer it’s up to you how you want to handle the implementation of content that’s less likely to ever change:

• You could hard-code all static content into flat-file templates and save EE from having to constantly perform database queries to retreive the same unchanged content every time it’s requested.  While this would be more efficient from a system perspective, it means if that content ever does change the person changing it needs access to that template. I’ve never been willing to do that for most clients, and don’t want to be on the hook for changing content on their behalf (the entire reason I got into EE to begin with). If you store your EE templates in the database then your content is stored there as well and technically not truly “static”.
• You could put your “static” content in channels and create dedicated templates & template groups to present it the same way as other dynamic content. Yes, this means the system does more work with having to query the database for content that rarely changes, but now that content is always available for clients to edit through EE’s edit interface. You can use some of EE’s caching abilities to mitigate the database work required here. There are a number of tutorials here on Train-ee showing this approach.
• You could use ExpressionEngine’s Pages Module.  Don’t be mislead - this Module is not required to create “static pages” in ExpressionEngine, but can offer some benefits for the right project.  Essentially once the module is installed and configured you can work outside of EE’s normal URL structures and assign your own URL to a page.  You can also create a common template to route all of these pages through.  Downsides to using this module are loss of the use of segment variables (since you are essentially masking a custom URL over EE’s normal URL) and having to reveal your templates to your content editors (concerning to me because there is usually one right choice and many wrong choices).
• You could look to third-party options like Structure or Taxonomy to work with static content in a more advanced way.

So don’t let the terminology fool you - with ExpressionEngine you have several tools available (both native and 3rd party) to handle any sort of content in a way that’s highly efficient & effective for the end client, you as the developer, and for search engines.

Just a bit of cliff-climbing required to figure it all out…

What are Snippets?
The short answer is they are the EE 1x Fresh Variables renamed, brought into the application by default, and given a more prominent place in the Control Panel.

The longer answer from the documentation page linked to above:

Snippets are small bits of reusable template or tag parts. You could create a Snippet for any number of purposes, anywhere that you need to reuse a small portion of a template, including partial or complete tags, other variables, etc. Snippets add flexibility and reusability, while making it simple to make site-wide changes by editing the Snippet’s source instead of having to modify many templates.

Well, yea, nothing new here, right?  We’ve always had the ability to save a chunk of code as an embedded template and use it over and over.  But go back and read that again.  Snippets can contain partial tags.  This is new - with embedded templates you always need to code complete tag pairs in the template to be embedded in - you can’t for example, have the calling template contain the opening exp:channel:entries tag and then store the closing /exp:channel:entries tag in the embedded template.

The key to this added flexibility is the parse order, or the order in which ExpressionEngine reads and executes the code you create in templates:

Snippets are expanded at a very early stage on each template, making it possible for them to hold dynamic content, ExpressionEngine tags, other variables, PHP, etc. They shine when you need to reuse dynamic information, but don’t need the extra overhead of access control or separate preferences of an embedded template.

In addition to the sample ideas in the docs, I wanted to explore Snippets in a different way.

A Different Coding Approach?
Ever since getting familiar with Snippets I’ve been wondering if there are ways to use Snippets in place of Embedded Templates with Embed Variables, and what advantages & disadvantages there might to doing so.

One way I commonly use Embed Templates with Embed Variables is building sidebar content.  Sites often have lists of things in the sidebar - most recent entries, most recent comments, etc.  Many times these lists are very similar, only differing in what channel the items are being pulled from. In these cases I’ll create one embedded template and pass in the channel name as an embed variable - so I can centralize the logic and markup of the list but still dictate which results I get in the parent template.  This seemed like a good test case for a Snippet-based approach instead.  Below are the two coding approaches presented and then an analysis of rendering time, memory and queries used.

The Embedded Template Approach
Here is the code for my parent template:

And then here is the code for the embedded template:

What I like about this template is the parent template is very clean.  The embedded template is called in twice but passed different values in the embed variables to get different lists as results.  The programmer in me thinks of this almost like a traditional function call.  The embedded template is a function, I pass it some different values, and it returns different results based on those values.  The results, in this case, being a marked up unordered list of titles with a header.  If I want to get a different number of results or link those results to different templates I can just create additional embed variables to use in the embedded template.

The Snippet Approach
Here’s the same idea re-coded using a Snippets-based approach.  With the Snippet I identified what was common about the two lists and placed that code off in a Snippet.  The parent template then houses the first part of the of the channel:entries tag so that I can specify a different channel parameter.

Here is the code that’s then centralized into the snp_list_guts Snippet:

The amount of code in the Snippets parent template is almost exactly the same as sample Embedded Template parent template.  However - call it force of habit - not seeing the complete channel:entries tag pair in one template bothers me.  Changes to the parameters of the tag would be easy enough to handle (like if I wanted a different limit on one vs the other), but things like building a different link in the middle of the template would be harder to do - I’d have to split the one Snippet in two.

What About Performance?
Regardless of the appeal of the code itself I wanted to see what performance differences there would be between the two approaches. I turned on ExpressionEngine’s Output Profiler and found the following (all running on my local machine on a relatively small EE test site):

Snippets:
Average Total Execution Time (10 page loads): .5414
Memory: 7,549,656 bytes
Queries: 23

Embeds
Average Total Execution Time (10 page loads) .5628
Memory: 7,562,520 bytes
Queries: 25

Compare:
Snippets ran ~ 4% faster.
Snippets used ~1% less memory
Snippets used ~ 8% fewer queries

So?
The Snippet-based approach has obvious performance gains, even on my small & local site.  Those results might be more impressive on a larger site, bigger database, and more complex content.  However I’m still somewhat ambivalent about switching to them.  You still can’t organize Snippets into groups.  You can’t save them as files (at least with native EE functionality, there is now a third party addon that lets you). And I’m still bothered by seeing EE tag pairs split between templates. 

However as a means to improve performance on a site that needs it Snippets would be well-worth investigating.

What about you - have you found a way to use Snippets that you think is pretty cool and want to share?