Stuff to click on

Thursday, December 17

Embed - Know It, Love It, Live It

If you don't use ExpressionEngine, this post will probably be mostly Greek to you. If you do use ExpressionEngine... cool! Hope you find this information useful. :-)


I've started working with ExpressionEngine CMS for some smaller web properties. If you've never checked them out, they are a great company located right here in Bend, OR. I needed something flexible and easy to use, without costing an arm and a leg... and this package is a good fit. The online documentation is outstanding with a very comprehensive documentation package. The forums are quite active, and it's pretty easy to find knowledgeable folks on Twitter who are more than willing to help out with questions (I found folks by searching the #EE hashtag).

One of the items that we wanted to incorporate was an event calendar. While all of the scheduled events needed to appear on the calendar, the link behavior for each event varied on a case by case basis. Some items needed to link to a detail page on the site, others needed to link to the event coordinator's site, and some didn't need any link at all.

The calendar tag that is built into ExpressionEngine is great, but it's limited to a certain set of fields. For example - you can't access any custom fields that you've added to a weblog (EE's term for a "section"). I was initially frustrated by this... why on earth would they limit the functionality. Then after some Googling and Twittering I realized I could accomplish the same thing - and more elegantly - by using the embed feature. I already knew how to embed templates - that's how the site header, navigation, and footer were configured. What's also great is you can add parameters so that when you call the embed you can send static information or variables along as well. SWEET!

Even luckier for me? had already done the same thing with the calendar, so I started out more than halfway to the finish line.

Rather than rehash a bunch of code that is widely available elsewhere, I'm going to link directly to the source pages and add my comments. Here's what I did.

1. Created the event calendar weblog (section) created a custom weblog field group.

2. Entered several of the events into the calendar for testing, and to give the end user who would be managing this information a place to start.

3. Added a page for the calendar, and added the ExpressionEngine calendar tag to the body of the page.

4. Modified the example code
  • In the weblog tag, changed the weblog parameter to "events".
  • In the weblog tag, added the options show_future_entries="yes" and show_expired="yes".
  • Changed the calendar month link paths to match the site's template paths.
  • Changed the date format of the calendar headings for the month name and the days of the week.
  • Added a horizontal rule to the top of each date cell.
5. Added the sample CSS to the site style sheet and modified it to match the site color scheme and appearance.

At this point, I got stuck trying to figure out how to add the logic needed to control the link behavior for each event. The rest of this post parallels the instructions I found on Train-ee, starting at the section called "Getting Tricky with Embeds".

6. Created a blank template in the template group associated with the event calendar. Added the word "foo" just to make sure it was working, then on the calendar template page I replaced the code with the event link and title with the code to invoke the embed. (Basically, the stuff between the {entry}{/entry} tag pair.) Then I previewed the calendar page just to show that the embed truly was firing off. (The word "foo" appeared for entry in the calendar, so it was a success!)

7. Added the parameter event_id="{entry_id}" to the embed tag in the calendar template.

8. Removed "foo" and added the opening and closing weblog entry tags to the embed template:
{exp:weblog:entries weblog="events" entry_id="{embed:event_id}" show_future_entries="yes" dynamic="off" show_expired="yes"}
{/exp:weblog:entries}

9. Added the {title} tag in between the opening and closing weblog entry tags and previewed the calendar page... just to make sure I hadn't screwed up yet. (The title of each entry appeared on the correct dates, so things were still going well!)

10. Started playing with if statements. Built the logic that determined the link type (a custom field) and displayed the title with the appropriate link (using the path variable or the custom field for the external site link) - or no link at all.

11. Sent a link to the shiny new event calendar for everyone to praise and drool over! ;-)

Here's the final code, for reference:

Calendar Template:
{exp:weblog:calendar switch="calendarToday|calendarCell" weblog="events" show_future_entries="yes" show_expired="yes"}
<table class="calendarBG" cellpadding="6" cellspacing="1" width="100%" summary="Events Calendar">
  <tr class="calendarHeader">
    <th><div class="calendarMonthLinks"><a href="{previous_path='events_tickets/index'}"><<</a></div></th>
    <th colspan="5"><h3>{date format="%F %Y"}</h3></th>
    <th><div class="calendarMonthLinks"><a class="calendarMonthLinks" href="{next_path='events_tickets/index'}">>></a></div></th>
  </tr>
  <tr>
    {calendar_heading}
    <td class="calendarDayHeading" align="center"><strong>{lang:weekday_short}</strong></td>
    {/calendar_heading}
  </tr>
  {calendar_rows}
  {row_start}<tr>{/row_start}
    {if entries}
    <td class='{switch}' align='center' width='14%'><hr noshade width='95%'>
      {day_number}
      {entries}
      <p>{embed="events_tickets/calendar_embed" event_id="{entry_id}"}</p>
      {/entries}
    </td>
    {/if}
    {if not_entries}
    <td class='{switch}' align='center' width='14%'><hr noshade width='95%'>{day_number}<br /> <br /></td>
    {/if}
    {if blank}
    <td class='{switch}' align='center' width='14%'><hr noshade width='95%'><em>{day_number}</em><br /> <br /></td>
    {/if}
  {row_end}</tr>{/row_end}
  {/calendar_rows}
</table>
{/exp:weblog:calendar}

Calendar Embed:
{exp:weblog:entries weblog="events" entry_id="{embed:event_id}" show_future_entries="yes" dynamic="off" show_expired="yes"}
  {if event_link_type == "Do not link this Event"}{title}{/if}
  {if event_link_type == "Link this Event to a web page with data that I will enter"}<a href="{path=events_tickets}details/{url_title}>{title}</a>{/if}
  {if event_link_type == "Link this Event to an outside web address (ie. www.foo.com)"}<a href="{event_link}" target="_blank">{title}</a>{/if}
{/exp:weblog:entries}


ExpressionEngine References:

ExpressionEngine User Guide
Train-EE
Net-Tuts "Become an ExpressionEngine Superstar" Series
Devot:ee
Tweeps: @angieherrera, @boyink, @bkmorse, @webunder, @woop

No comments: