Well - at least it will be traditional in the sense that there will be four days spent in a classroom learning EE hands-on from an experienced professional, with the ability to ask questions and interact with others in the room.

That’s where any similarity to off-site training you’ve had in the past will (hopefully) end. 

The first difference is the location.  This class will be held in a vacation destination - a scenic resort town nestled close to Lake Michigan and renowned for it’s beautiful sunsets, clean beaches, bikepaths and an historic downtown with home-town coffee shops and microbreweries.

The second difference is the venue.  We’ve all suffered through training in an instantly forgettable generic space.  Learn ExpressionEngine in a brand-new, funky, hip and green hotel located within walking distance of restaurants and shopping.

The third difference is the after-hours activities.  Rather than leaving you to while away the evenings alone in your hotel room, we’re planning a number of events to get you out to experience the area and hang out with the others in the class.

For more information on the location, venue, course content, and schedule/cost please visit the new classroom section here on Train-ee.com.

If you have any questions not answered by that page please feel free to contact me directly via either Train-ee or Boyink.com

Sign up now - the conference room is only so big!

Preview the Results
Before getting your hands dirty with the code, take a look at the completed calendar index on the sample site.  I want you to make sure it’s what you’re after before proceeding.  You can see that EE generates the calendar view, and if you look at either July or August of 2008 there are entries that show up that display a linked title.  At the moment the link doesn’t go anywhere - that requires a detail template that I’ll cover in the next chapter.

If you mouse over a link, you should get the browser title pop-up that displays a bit more information about the event—the start time, the duration and the location.

That’s roughly half the calendar functionality I’ll be covering in this series.  The other half will be the detail template (that the title will link to) and implementing an events RSS feed.

If that works for you, keep reading…

Overall Implementation Steps

• Create events weblog
• Create events custom field group
• Add fields to the group
• Enter content
• Create events template group
• Update embeds/main_nav
• Update stylesheet/styles
• Add code to events/index
• Create embeds/event_rollover_title

Create an Events Weblog
Event calenders in ExpressionEngine are powered by a standard weblog - so I’ve created a new weblog and named it “Events”, with a short name of “events”. 

Create an Events Custom Field Group
Events have their own unique data structure, so a new field group is required. Create an “Events” custom field group.

Add the following fields to the group.  I’ve listed the field name, label, type, size and formatting options for the fields I’ve added:

• event_duration, Event Duration, Text Input, 3, None
• event_location, Event Locations, Drop-down List, manually populated, None
• event_cost, Event Cost, text input, 4, none
• event_contact_name, Event Contact Name, text input, 128, none
• event_contact_phone, Event Contact Phone, text input 128, none
• event_contact_email, Event Contact Email, text input, 128, none
• event_details, Event Details, text area, 6 rows, XHTML

And One More
While planning this section initially I was going to tie together events and ministries using categories.  I’m going to do a bit of a direction change and use relationships instead.  Using categories only nets me being able to show related events on Ministry category pages—so if you view the Ministries for Singles I’d be able to pull the upcoming events for singles - but I see a couple of issues with that approach.  The design of the Ministries index template doesn’t allow for another content type to display and I don’t want to go down the path of a category-specific template.  Using categories also doesn’t easily allow me to pull ministry-specific events to a ministry detail page—and I think that’s a more helpful connection than the category level tie-in.

Relationships will let me create a direct connection between an event and a ministry.  I’ll be able to use that connection to link from a ministry detail page to an event, and from an event detail page to the sponsoring ministry.

So I’ve added one more field to my Events field group - a relationship field:

Name:
event_sponsoring_ministry

Label:
Event Sponsoring Ministry

Field Type:
Relationship

Weblog to Create Relationship With:
Ministries

Display Criteria:
I choose “Sort by Title” in “Ascending” order

In this chapter all we’ll do is setup the field and assign a related Ministry while entering content.  In the next chapter I’ll show how to pull related Ministry information to the Events detail view.

Connect the Field Group to the Weblog
Make sure to assign the new field group to the Events weblog via the “Edit Groups” link in Weblog Management.

Enter Content
Go ahead and post some new entries in the Events weblog. There are a couple of new things to note here:

Make sure to click the Date tab and assign choose an Entry Date that’s in the future.  The time of the post will be used as the event starting time so round it off to a nice “top of the hour” number.  The other new thing is to now use the relationship field - so for every post choose a sponsoring ministry in the drop-down.  I found that putting a number of events on one date helped me with formatting the calendar visually.  Keep in mind that you can edit your entries to assign new entry dates to move events around the calendar for formatting purposes.

Create an Events Template Group
With the content structures in place I’ll now work on pulling the content to the site.  Create a new template group named “events”.  Since the content is full-width like the Beliefs page, it made a good starting point - so I copied that code into the new events/index template.

Coding the Template
The first order of business is to change all references of “beliefs” to “events” - so the page title, the body id, and the variable in the main navigation embed.  Then in the main content div you can remove all the code there entirely.

I used the calendar code from the EE documentation as a starting point for my code - the “big” version which is the second example on that page.  I also used the provided calendar css as a starting point.

After some tweaks - here is the guts of my events/index template - take a scan through it and then I’ll highlight the changes I had to make from the example code I used as a starting point:

Here are the changes I had to make from the sample code I copied from the EE docs:

• Changed the weblog it references - to “events” in my case
• Changed the next_path and previous_path values - and just referenced this index template
• Added “show_future_entries="yes” to the calendar tag - otherwise the calendar will only show events for today or ones that had passed

With those changes I had a working basic event calendar.

Getting Tricky with Embeds
I wanted to take it a step further though and see what it would require in order to be able to pull custom fields to the calendar view - so users could get more event information without having to click through to the detail page.

Remember that the weblog:calendar tag doesn’t support custom fields by default.  However - it does return entry_id.  Using that as a bridge I was able to pull custom field content to the index template by using an embedded template with an embedded variable.  I decided that directly displaying more content on the calendar would visually junk it up so decided to pull custom field content into the link title attribute .  The result? Mousing over an event link will pop up the little browser tooltip and display the event start time, duration and location.

So I created a new template in my embeds group called “event_rollover_title”.  It has the following code:

and then added a calling template in events/index:

Here’s how it works:
The parent weblog:calendar tag returns entry_id, which gets passed to this embedded template.  This embedded template takes the entry_id and uses it as a parameter on a weblog:entries tag, which as you know returns all custom fields.  The fields within the weblog:entries pull out the post time (used here as an event start time), duration, and location.  This text is assembled and returned to the calling template as the link title text.

One note I need to make about this approach is that it, due to it’s nested approach, it could be resource intensive if you have a lot of calendar entries.  For the couple of church sites I’ve been involved with, I wouldn’t be worried, as there are rarely more than a couple of entries a day.  I’ll also - in a future chapter - cover some caching approaches that will also help mitigate any performance concerns.

Don’t Forget
Don’t forget to update embeds/main_nav to make the link to events/index live.

Companion Files
The companion file zip archive for this chapter includes

• New events/index
• Updated stylesheets/style
• Updated embeds/main_nav
• New embeds/event_rollover_title

Here’s a link to download the companion files: 20-Events-Index.zip

Next up - the events detail template.

ExpressionEngine Calendar Overview
I know a number of you have been waiting for me to get to this part of the site build—and it has me a bit worried as I’m afraid the expectation is that I’ll show how to build this really great full-featured event calendar that slices and dices event information like something from Ronco.

The EE calendar just isn’t that complex, however, so I want to do a bit of work to manage your expectations before plowing into the code.  Let me lead off with an overview of the EE’s calendar function - a description I wrote in the comments on an earlier chapter in this series:

First - imagine a weblog. Now add an entry on the weblog.  It goes in with a publish date.  Many blogs have those little sidebar calendars that show you when posts were made - so if you posted an entry on the 6th of March that date would then become clickable.  Clicking on it would filter your current view down to just the entries posted on that date.

Got it?  Now - blow up that small calendar to be full-page, post some entries with future dates, and tell EE to show entries with future dates.  Throw the title of the post on the full-page calendar view. Link the title to another template that can show more details for one event.

That’s the essential EE calendar capability.  It’s basic weblog post information, plotted on a calendar view, with the ability to show entries with future dates, and link to another template that can show all the content for that one event.

Advantages
There are a number of advantages to using EE for an event calendar.  First - you can offer content administrators a consistent publish and edit process and interface.  Entering an event is the same as a new ministry. 

Second - you can take advantage of categories or relationships to group event content together with other content.  I plan on doing that here, using relationships to tie an event to a ministry so that I can show specific upcoming events on a ministry page.

Third - you if go down the path of memberships on your site you can allow any registered member to submit a calendar event using a Stand-Alone Entry Form.  Those entries can then take advantage of Custom Entry Status so that the new submission goes to “pending” status and doesn’t appear on the site.  You can then implement an Entry Notification such that a calendar administrator would get an email when a new event is submitted.  The calendar administrator would then review the event and if approved set the status to “Open” which would cause it to display on the site.

Disadvantages
The native EE calendar doesn’t do recurring or multi-day events - but there is a third-party plugin that adds that capability - so you post an entry, some details about how it repeats, and then your event shows on the full-page calendar view multiple times.

The native weblog:calendar tag doesn’t support custom fields, which means that on the full-page calendar view you are limited to what can display for each event.  Options are title, author, and entry_id. There are ways around this restriction that aren’t too hard, so I’ll cover one here.

EE’s calendar also doesn’t, inherently, work with categories. In other words, you can’t assign categories to the weblog driving your event calendar and then use native EE tags to link to a categorized view of the overall calendar.  You can get to this functionality with a bit of php trickery, but for this series I’ve decided to stay within the bounds of native EE functionality only.

There is no native iCal support - although there seems to be some movement in the forums around it.

Options
If native EE doesn’t meet your calendaring requirements the next option I’d suggest looking at is using a Google Calendar.  There is a relatively new Google Calendar Plugin for pulling information from a public calendar to EE.  However it doesn’t have much activity around it and I haven’t tested it—so don’t consider this link an endorsement.

Having Said All That
My plan here is to show the implementation of a simple event calendar using native EE tags.  I’ll push the bounds a bit, showing how to use entry_id as a bridge to pull custom fields to the full-page calendar view.  Other than that, this will be a very straightforward implementation.

In the Real World
My church uses the EE calendar but I have extended EE’s native functionality with the repEEt plugin linked to above.  I also implemented a Stand Alone Entry Form with workflow to allow calendar submissions by any registered member.  In all honesty if 10% of the events on the calendar were submitted that way it’d be great - in reality my wife and I “own” the web calendar and keep it updated based on what we hear going on while at church.

But - we’re a very small church with a small building.  We don’t have a ton of staff, committees, or different facilities to manage.  For us the combination of ExpressionEngine and repEET work well.

I won’t duplicate the help found at 5Pieces, or in the Monoslideshow documentation.  All that’s really different is the code needed to pull the image and thumbnail specifications in the XML file used by Monoslideshow.

You’ll also need the “Extract URL Plus” plugin offered in this EE forum thread.

Note that in my case I have two fields in the photoblog: thumbnail and full_size_image.  I don’t use captions so just plug the title in as the image title and description.  I have MSS configured to not show this data anyway as I prefer to just let the images speak for themselves.

In order to get the XML to output correctly for Monoslideshow to parse it, I had to wrap a weblog:entries tag inside of a category:archive tag.  There’s probably a more efficient way to do this with a custom query, but so far the performance seems acceptable.

Here’s the EE code required - keep in mind that there is more to the XML file that Monoslideshow requires.  This code goes in the file after the “preferences” portion of the file closes.
monoslideshow_xml.txt

Oh - this approach also assumes that all photoblog images are in the same directory.

I think the site_url and homepage variables are a couple of my favorites in ExpressionEngine. I’ve found that you can actually use these in the EE Control Panel - wherever paths need to be specified.  This includes:

• Weblog Path Settings
• File Upload Preferences
• Category Image URLs

Why would you want to use variables in these spots?

What happens to me quite often is - no matter how hard to I try to remember - I forget to change these paths after a site goes live.  Then when, for example, someone uses the Search, the path of the link returned still has the “temporary” domain name in it.  The link will still work, but it messes up your server logs and just doesn’t look as nice as getting the live URL in there.  Or - I decide to rename “index.php” to something more semantic and then have to go find all the places where “index.php” is stored.

So - what I discovered I could do is use the variables in those settings - and then they will inherit the change to the homepage and root URL setting automatically.

So, for example, rather than having a Search Results URL setting of :

I can specify:

Now when I change the “URL to the root directory of your site” and the “Name of your site’s index page” under Admin > System Preferences > General Configuration all those individual weblog paths will change as well.

With some paths -like category images - you won’t want the “index.php” in there since you are referring to an image and not a template.  In that case you can use site_url instead:

Variables in Control Panel path settings == one less thing to worry about when launching a site == well worth it.

Situation:
My church - Manna - wanted to have an “online directory” of member photos on the website.

One way to do this is to just use the Photo Gallery module and create a “members” category, upload some pics and title them with the member name.  While this would give you a nice online directory, what it doesn’t do is integrate with the existing profiles which get linked to blog posts and comments, etc.

However, the built in profiles don’t let you browse pictures - you can only navigate via the memberlist and click each name to view the full profile.  The profile may or may not include a photo.

For the situation where you met someone but can’t remember their name this isn’t a great arrangement.

What you really want is the best of both options - photos stored in the profiles where members can upload and maintain them on their own, where they get linked to blog posts and comments, but also have a “gallery” page where you can browse photos to find a name.

That’s where this little howto comes in.  Using the Query Module we can pull this data together in pretty short order.  Here’s the code I used (note that I’ve removed all formatting and specific paths, so you’ll need to edit those to work on your site):

This code:

• Only loads those members who have images
• Sorts the results by screen name
• Loads 4 images to a page
• Adds pagination links if there are more than 4
• Loads the member name and bio
• Links to the standard EE profile for each member

Voila!

Here’s the “straight-talk” around what happened with my church and this page. This approach was my response to being asked to put together an online directory on the site - with the expectation that I would bring my camera, take pictures of people, and post them to the site.  I’ve consistently avoided putting myself in such roles as I don’t want to be the “website update boy” for the church.  I’d much rather spend my time putting together ways to enable self-service for church members at large - so rather than taking on the creation and maintenance of a member photo gallery this approach put the responsibility for uploading photos in the hands of each member.

However in the end this member photo directory was one of those times when the technology was the easy part, but getting people to take action was the harder part.  Not enough people uploaded their own picture to make this page worthwhile - so it only lasted a few months on the site.

What this tells me is that that a photo directory just wasn’t that important to enough people - otherwise they would have taken the 10 minutes to upload a photo. 

For the purposes of demonstration, let’s assume I have an existing section of simple static content with navigation to each page showing in the sidebar.  I now want to add a “Contact Us” page in this section, and the page needs to have a fill in the blank form.  I want the navigation to this new contact page to show up in the same list as the other pages in this section, but would rather use a different template to create the page.

Here’s what I would do:

• Create a new post in the weblog holding my static content.  In this case I’d title it “Contact Us” which would get me a URL title of “contact_us”. Make sure to note the URL title.
• Enter some dummy content - it won’t appear on the website so it doesn’t matter what you put in.  I usually put a note of “Don’t delete this entry as it’s used to create navigation”.
• Save the new entry.
• Just for kicks, go to your site and refresh things to ensure the new entry is showing up in the navigation.
• Now return to the template group that contains the templates used to create your static content.  Create a new template.
• This is the important part - make sure to name the new template such that it matches the URL title as your placeholder entry - so in my case the new template is called “contact_us”.
• Add the necessary code to the new template and save it.
• Go back to your site, navigate away from the placeholder page and click the “Contact Us” in the navigation again.  EE should load your new template rather than the placeholder entry from the static content weblog.

What we’re taking advantage of here is how EE processes URLs and the order it looks for things.  It looks for templates before content entries, so the new template will get loaded rather than the static content placeholder entry.

Overall this is just a neat little trick that lets us use weblog entries from one weblog to build navigation to a number of different templates - templates that may or may not draw content from the same weblog as the navigation comes from.

Note that you could keep all this functionality in one EE template, and use segments and conditionals to analyze the URL and either show static content or the contact form.  How you approach the build is up to you - for me it seems each site has more or less a fixed amount of complexity, and I can either build fewer but more complex templates or more templates that are individually less complex.  In other words - I can squish that complexity into either a tall and narrow shape, or a short and fat shape - but the shape has the same surface area...if that makes sense.  Often I’ll make a decision based on what’s going to be the quickest to figure out a year from now when I’ve forgotten how the site went together and have to look at the code to remember...which for me tends to be the more-but-simpler-templates approach.

This method builds nicely on the “Approach-A” I’ve outlined previously.  Here’s what you need to add:

• Another custom field, named “parent_page”.  Make this a relationship field and specify the same weblog as this fieldset is already used in.  Stick with the default for title, and save the new field
• Now go through your content entries, and edit the second-level pages, assigning them to the parent-level pages.  In my working example I have seven entries.  I left the index entry alone, and edited pages two, three, five and six to assign them to either page one or four - which I’m arbitrarily making my second-level pages.

The Code
The nav-building code is a bit more complex in this case, so lets take a look at the text version of the template and go through the code.

• The main weblog:entries tag that builds the left nav is unchanged from Approach A
• The first conditional looks at the value of the new parent_page field. If this is 0, that means there is no relationship setup, so this must be a parent page.
• Each parent page gets an opening li, then the code uses reverse related entries to pull in all the pages that list this page as parent.  Reverse related entries is necessary because we estabished the relationship from the perspective of the child
• The code uses two EE variables, count and total_count, to determine when to insert the nested opening and closing ul tags.
• Once the reverse_related_entries code is done, the closing li tag for the parent item is added.
• The weblog entries tag closes and then the overall parent ul tag is closed.

The Results
The results of this approach can be seen in the working example, which renders with an index entry that’s omitted from the left-nav (the top-level of content), and a navigation bar that has two levels of pages.  The second level links are pages with no relationships established thereby making them “parents”, and under each parent is a nested UL with it’s children (the entries where we specified a parent page). 

Advantages

• Simplicity in terms of EE setup - using only one weblog and one template
• Better usability for clients—the parent_page field appears on the Control Panel Publish form along with other fields, vs. the categories which depend on users remembering to click to another tab to assign.
• Consistent interface for content maintenance—all using the weblog Publish page, vs. using categories where category pages have to be edited in the category interface where there is no file upload function, etc.

Disadvantages

• Subpage URL structure is the same as Parent Pages—so the nav structure is not reflected in the URL structure.
• The Parent Page drop-down won’t reflect any structure, so this approach is probably best for smaller less complex sections of content.

Overall I think this is still my favorite approach for static three-level content in EE - especially when the structure can be filled in by the site developer before the client is unleashed on the site.

In this post I’ll show an alternate method of presenting three-level content in EE.  The navigation model in this approach is less like traditional navigation and more like a weblog in that the category (2nd) level pages uses the main content area for blurbs with “Read More >>“ links to the detail (3rd) level content. I use this approach sometimes because I like how it gives the user more detail as you move through the site.  It’s also a nice way to get around needing category-index level content that often times says nothing more than “below this page are three more pages”. 

Implementation Note
I’ve been thinking all along that this is a “3-template” approach, but I’ve realized that if I created a new template group for this example it could remain a two-template approach.  If you watch the urls used in the working examples you’ll note this example is now in it’s own “static-c” template group.

I’ve posted both a working example along with text versions of the index template and the category page template.

As before, this tutorial assumes you’ve created the ExpressionEngine weblog, category group, and field group used in the previous tutorials and will cover the incremental differences only.  To build off Approach B to Approach C we need to:

• Add a field to the Static Weblog
• Change how the left-navigation is built on both templates
• Modify the category template to bring in the blurbs for each detail page

Adding a New Field
The category pages in this approach will feature “blurb” or “page summary” type content for each detail page.  To hold that new content we need to add a field to the Static Weblog:

• In the EE Control Panel, navigate to Admin > Weblog Administration > Field Groups
• Choose your “StaticPage” field group, and click the “Add/Edit Custom Fields” link next to it’s name.
• Click the “Create a New Custom Field” button at the upper left of your screen.
• Fill in the details for the new field.  I’ve called mine “page_summary” and made it a textarea with 6 rows, with the formatting set to “None”.
• Save your new field

Changing the Left Nav
For this approach, since we’re moving the links to 3rd level pages into the content area of the second-level pages, we need to change the EE tag used to build the left navigation. We’ll now use the exp:weblog:categories tag - download the text version of new Index template to get the EE code.  Copy/paste this into your EE index template, and make sure to change things where appropriate for different weblog, template, or field names.

Changing the Category template
Now we need to modify the Category template - we’ll leave the exp:weblog:category_heading tag in place to bring in the Category Name and Description, but you can also get rid of this if it doesn’t suit your purpose.  Download the text version of the revised Category template, and paste it into as your category template in EE.  You’ll see where there is now a exp:weblog:entries tag that brings in the Page Summary and a “Read More” link for each page in this category.  A few notes about what’s going on here:

• You don’t need to add a category parameter to the weblog:entries tag - EE will do this automatically since we are on a category page.
• Our Index entry should never show on a category page because it’s not assigned to a category.
• The “Read More” links are pointing back to the Index template - which will load the Page Content for whatever entry you click on.

With the new field and revised EE templates in place, you should have a working static section with categories for subnav, and links to the detail pages on the Category templates.

Advantages

• Left navigation stays simpler
• Category pages are more detailed
• Visitors get more info about a detail page than what just a navigation link can provide
• Works well for presenting content that breaks up into a categorized “summary/detail” structure
• Could be extended if necessary to use a 3rd template for the lowest-level detail
• Still simple in that only two templates are required

Disadvantages

• Left navigation isn’t all-inclusive—you can’t jump directly from a 3rd-level page in one category to a 3rd-level page in another category
• Category pages have a different content structure than detail pages—may not work for all content types

Extending This Approach
I’ve purposefully kept things simple here just for the sake of the tutorial, but I’m can already see where this approach could be improved upon - and that’s adding “sideways” navigation to other pages in the same category when you’re on a detail page.  That would be easily do-able using another exp:weblog:entries tag on the Index template, configured to use the Related Categories Mode.  Since the Index content doesn’t have a category assigned this tag would not return anything, but while viewing an entry that’s been assigned to a category it would return links to the other pages in that category.  You can see an example of this approach in action on this Client site - the second-level navigation are all EE categories, and the links on the bottom of the page are to other pages in the current category.

I’ve posted both a working example and text versions of both the index and category EE templates.

Once again I’m going to assume you have created the EE elements covered in the first two tutorials, and only cover the incremental differences to now move to this level of static content.  To use this approach after building Approach A we need to:

• Enter category-level content.
• Edit the category archive tag in the Index template to add links to the new Category template.
• Create a Category template to display category content.

Enter the Category Content
For the category content we’ll use the additional Category field of Description.  You can also use the image field, but I’m not for this tutorial.  To add or edit the category descriptions:

• Navigate to the Admin > Weblog Administration > Category Groups area of the EE Control Panel.
• Click the “Add/Edit Categories” link next to your static category group.
• Click the “Edit” link next to a category.
• Enter content in the category description - this will essentially be the same as content in the “page_content” area of a weblog entry.
• Save your changes.
• Repeat for each category.

Edit the Index Template
All we need to do in the index template is edit the weblog:category_archive archive tag to add links inside the categories loop.  Download the text version of the revised Index template to get the new code.  You’ll note the links are to a template called “snow” - since my categories are different types of snow I named the category template to suit.  You can change the link to point to a more aptly-named template for your needs.

Create a Category Template
Now that we have links pointing to a category template, we need to create that template.  Download the text version of my category template and paste it into EE as a new template.  Note that if you changed the links from “snow” to something else in the previous step, you’ll need to name the template to match in this step.

The main difference in this category template is the EE tag used in the content div.  Rather than pulling a weblog entry, we’re using the category_heading tag to pull the category name, description and image fields.  There is a simple conditional there that only pulls the category description if there is content in that field. 

Note that the code that creates the left navigation is the same code as in the index template.  I’ve left this so that these tutorial templates would be more self-contained, but in practice I’d pull that code, stick it in it’s own template, and embed it back into this template. 

At this point you should have a working 3-tier static content setup in ExpressionEngine.

Advantages

• True three-level navigation and content
• Still pretty simple overall with two templates required

• Two different content editing workflows, depending on the content level in navigation
• The category description field doesn’t offer the same formatting options as a weblog field, so either the content has to be simpler or clients need to enter some markup
• The category image field (not used in this tutorial) doesn’t offer a file upload or browse button, so image paths need to be entered manually - which isn’t client friendly.