Pages Module 2 - Installing, Using and Coding

In the first installment of this series we looked at an introduction to and history of the ExpressionEngine Pages Module.  This post will build on that foundation by going through the process of installing the module and looking at how content authors interact with it and how to code ExpressionEngine templates to display Pages Module content.

 

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:

/mikes/cool/jeep 

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

http:/www./yourdomainhere.com/index.php/mikes/cool/jeep 

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:

/mikes/cool/jeep
/mikes/cool/jeep/seats
/mikes/cool/jeep/rollcage
/mikes/cool/jeep/rollcage/seatbelts 

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:

{exp:channel:entries channel="static_pages"}
    
<h2>{title}</h2>
    
{content}
{
/exp:channel:entries} 

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:

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:

{if segment_2 == "mikes"}
<p>Now display this paragraph</p>
{/if} 

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.

 

Category Navigation

<< Previous Entry   

Next Entry >>

 

Previous Comments

Picture of JohnM

by JohnM

Date: Thursday, June 9th, 2011
Comment: #1

Be sure to include the excellent Booyant Better Pages in your 3rd Party write up.

I wish EllisLab would give the Pages module some love.

Picture of Tyler

by Tyler

Date: Friday, June 10th, 2011
Comment: #2

Pages and Categories need some love. Tend to not use either. Nice article. I was hoping for some interesting new tricks for the Pages Module but I guess that may come with the next installment in the series.

Add Your Comment

Commenting is not available in this channel entry.

Unless otherwise stated all content is © Michael Boyink of Train-ee.com & Boyink Interactive. Please don't steal - I've got kids to feed...

dy>