Contextual Group Calendar Using Calendar module, Views and Panels 2

From a UI perspective, this is what we're after: View Site

Work/Project Summary

I wanted full control over the evolution and design of calendaring in my site, but as importantly, I wanted to maintain group home-page context as users schedule and review events.

As you may know, using Event module takes control of calendaring AND disrupts the context it moves the user from the groups area of the site with the calendar displayed into the event module breadcrumb. This is confusing for users, and I wanted to eliminate that confusion.

In order to do this I had to eliminate the Event and og_calendar modules, but I also had to have a way for the group node id (not the group id) to be read and maintained by Drupal. Once I understood what argument handling code to pass through (not just arguments), all as pretty straightforward.

The step that complicated this is that I am using mini panels to place a calendar block on the page. This is not hard, but the panel must recognize the argument handling code in order to "know" where it is in order to maintain group context. By simply passing arguments through the mini panel to the view the whole set of 1) how to display events and 2) how to maintain context was all synched up, and I could move on to clarifying the breadcrumb.

The reason breadcrumbing was so important is that this is the only way to present navigational options with "Groups/"the-group-you-are-in"/calendar context at the top of each content area following the trail from the group home page block-view to calendar-view to event listing to node. To manage the breadcrumbs a template page snippet had to be developed.

All this likely convoluted to the average user. It was to me prior to diving into it. I hope my break-down of the steps helps others avoid the convolution and get right to clean, contextual group calendaring.

Many of the steps implemented here can be applied to other scenarios, and I hope too that the presentation of the steps helps people understand how Views, CCK and Panels 2 "talk" to each other through field types, argument types and argument handling code. It's really not that hard.

I worked with Ted Sirbinsky of Lullabot and MothersClick fame on solving this problem.

Views-based Calendar Configuration Procedure

The challenge of building a Views-based, tabbed mini-panel calendar has several parts:

Check here for the concise, Drupal.org generic walkthrough of this process. (Starts with section VI)

I - turning off the event and og_calendar modules, if they are installed,

II - installing calendar module and making sure date module are installed and enabled,

III - creating a simple event content type with a date-stamp

IV - adding a group calendar view

V - installing panels 2 and tabs panel-style modules:

note: panels 2 is in beta and my current configuration does not work with panels 2 beta 2. It works well with panels 2 alpha 13. I don't know why, and I don't have time to figure it out right now.

Make sure you run update.php when you install Panels 2. There are some database additions that are critical for proper Panels 2 functionality.

VI - creating a block view calendar with the right arguments and argument handling code, (walk through starts here)

VII - creating the calendar mini panel and passing argument handling code through to the view in the mini-panel,

VIII - creating the "group_tab" mini panel and styling the mini panel as "tabbed style"

and placing the tabbed mini panel into Group home panel page

IX - clarifying breadcrumbs through template page code.

I & II Easy part. I just removed event and og_calendar from my configuration. I did not have event nodes already on my site, so I didn't have to worry about management of those dates. Download the calendar and date modules, install and enable them.

III Creating an Event Content Type

Karen S. wrote a very good, step by step for using Calendar and Date with views can be found here. There is also a step by step on creating the event content type. The one difference between the content type Karen S. creates and mine is that I use a Datestamp

field instead of a Date field. (The view Karen S. provides had to be modified for my application.

VI Creating a Calendar Block View

Installing and activating Calendar module makes available a calendar view. Once the view is added the basic template for a calendar is available -- it's just a matter of configuring it well.

This "simple" thing is where so many people spend too much time. The steps here are important to follow, and it's easy to miss a couple of them:

1) Editing the Calendar View:

Once you have added the Calendar View, choose "edit":

Give the View a good name. Mine's "group_calendar". You may add calendars in the future; a clear name will make them all easy to keep track of all calendars. This group name is machine readable and is used by the your database.

Note: It is NOT the View "Title". The View Title will be discussed below.

2) Page View & Block View:

You will need both a Page view and a Block view for the group_calendar.

The reason is clear when you think about it. In terms of workflow or user experience, I wanted to have the block calendar available on the individual group home pagethat would link users to events in a compact space and would give them an overview of their specific group's events. They can click on an event in that calendar block and go to the page view calendar. [Creating a Groups home page is another whole step -- some of the process can be found here.]

Make sure "Provide Page View" is selected.

It is important that the URL entered is clear and simple.

Because the Calendar View was added, the "View Type" will be automatically selected as Calendar.

The "Title" of the calendar view in my site is "Calendar."

Note: Be clear here. In order for you to place this block into a panel in the next section, Panels 2 will need the title of this view. The "View Title" helps YOU keep track of and use the view. "Name" helps the database keep track of and use the view.

Make sure "Provide Block" is checked.

Calendar View Type will automatically be selected.

If for some reason you have changed it, make sure it is "Calendar."

I have titled the block "Test Calendar" title it what will make the most sense.

Display 999 nodes per block -- These are events, and chances are you may need a lot of linked references to nodes/events created by users. It helps to just max this field out.

3) Fields:

The fields for this Calendar view are simple:

Create a Node Title field as a link

Create a Datestamp (name of content type) field. The name of this datestamp must be the same as the CCK event_date content type. Don't group multiple values.

4) Arguments:

Once the fields are created you must create the proper arguments for each of ways your events are presented. This is the heart of OG context control.

Calendar module creates a view template and Calendar:Year, Month, Day should be already present in your view.

You will have to add the Og: Group nid(s) argument type in order to use the argument handling code.

These argument Titles will present the user with clear breadcrumbs which clarify where the user is at any time,

The Og: Group nid(s) arg type will establish a Node Id context which ties each of the args together with a og_get_group_context() argument code.

It is important that these arguments be set up just this way. This is the heart of OG context control.

Argument Handling Code snippet (just copy this code):

if (!args[0]) {
$og=og_get_group_context();
$args[0]=$og->nid;
}
return $args;

5) Filters:

make sure to set your filter to Published Equals Yes -- otherwise you won't get any published events.

Congratulations.

You now will have a Views Calendar Page view. You will also have a calendar block to place into your panel. Calendar module comes with a css-styled calendar-mini that will reference all event dates as links that will connect you with a day-view of the node, and to the node itself.

But much more on this next.

VII Placing Views Block in Panels 2 mini-panel

1) Mini Panel Content panel (not the tabbed panel, but its content.)

In section V you downloaded and enabled the Panels 2 and Tabs Panel-style modules.

In this segment of section IV, you will create one content mini panel that will contain your Block View Calendar. We start with three mini panels already created.

Note: I have created a "calendar" mini panel, an "events" mini panel and a "groups_tabs" mini panel. The last, "groups_tabs" mini panel will contain the other two mini panels and will display them with tabs. The first two don't need tabs.

First click Add to create a new mini-panel

Once you have clicked Add, provide a clear title -- "calendar" works well. Then click Layout.

For this mini panel we want a Single column layout. Then click Layout Settings, or Next.

Layout settings provides a form to set the Panel style. Because this mini panel will go inside another, tabbed mini panel, set this to the default/no tabs style. Save.

Content: Once you have set the layout, it's time to add your calendar block view.

Click the icon to add content.

Add Content to mini panel. Here is the reason you were clear when naming your calendar view. In Panels 2 beta you can restrict the clutter of views available to panels, so you don't have to pick through a bunch of blocks and views. Here we have found our Calendar View.

Configure Calendar is an important form. It displays as a pop-up. I want to override the title of the block, so no title appears. We want the calendar to appear in the tabbed mini panel as a block, so select View type to be Block.

Arguments: Don't miss this step! This is where our argument handling code will be passed through to the view from the panel. You must click Send arguments and enter %1 in the Arguments field. Otherwise our code will go unnoticed.

Content placed in configured mini panel: If you have not missed a step, you will see your working block inside your single column mini panel.

Save your mini panel configuration.

VIII Tabbed Mini Panel implementation

This step by step will be quick and largely visual.

Again, I have created three panels in advance. Here, we will focus on the "groups_tabs" mini panel. We will use Tabs panel style module by Wim Leers to style "groups_tabs" and to display the "calendar" mini panel we just created.

Title your tabbed mini panel clearly so it can be selected easily when placing it in your Panels page layout (see below.)

Again, select a Single column layout. This is a "box" to contain your other panels, and it will be placed into two-column stacked panel later on.

Because your mini panel will have more than one block of content, you can select Tabs in the Layout settings section of mini panel configuration. (You must have the Tabs Style module loaded and enabled to see this selection option. If you don't have it installed you will not see this.

I have no style settings set for my mini panel, but here is the edit pop-up, so you know it's options.

Add your "calendar" mini panel by clicking the icon.

There is a special section in the Add content pop-up. In Panels 2 there is a Panels node selection option that allows you to filter the types of nodes that will show up in this window. If you have created multiple mini panels (I have "events" too) select those as well.

I have not overridden the title here. Click "Add pane".

Once you have added the mini panel(s), they will be shown in your groups_tabs Content area. You can click the arrow/bullet next to the Mini panel title to preview its contents.

VIII (Part Two) Placing Tabbed Mini Panel into your page layout

This section will not be outlined in detail. It is more of a bonus section to see how the panels page handles nested mini panels and to return us to the first UI image now with a little more understanding.

Go to your Panels admin, and select panels pages

You must first create a panel. I have many and Edit the _groups panel page.

In the layout area of the Settings section, you can see here I have already placed the "groups_tabs" mini panels in the right side of a Two column stacked layout.

This is where you would Add the tabbed mini panel "groups_tabs" as you have done in earlier steps.

If you select Preview (in Panels 2 beta, it is "View" in my alpha release) you can now see your tabbed mini panel display, and can toggle between calendar and events. (I have not added any additional arguments.)

Once again, the themed "final result."

IX Clarifying and making uniform the Breadcrumb Context

All the above "functionality" development enables the user to create context sensitive group calendars. But Drupal's existing breadcrumbing system doesn't talk to the group context very well. So we created a template.php theme function override that tells the breadcrumbs to behave.

I worked with Ted Sirbinsky of Lullabot and MothersClick fame on solving this problem too. The issue was that the Groups home page recognizes the URL passed through the view. But calendar module and Drupal's default theme_breadcrumb() breadcrumb variable aren't set to interact. The Theme function override helps hook the breadcrumb into the group's view, node id and specific arguments.

I wrote this note to Ted when we were working this out:

I like this structure.

Home :: Groups :: The Vineyard Voice

This structure allows for:

1) "Groups": group directory selection

2) "The Vineyard Voice": would take you back to the group you are in -- (When it is also a calendar name it is confusing. I'd like to eliminate that confusion.)

This structure also serves as a real breadcrumb.

I would like to use this basic breadcrumb unit as the prefix for all deeper group calendar breadcrumbs.

For example, this current breadcrumb:

Home :: Test Calendar :: The Vineyard Voice :: 2008 :: January 2008

would be replaced with this structure:

Home :: Groups :: The Vineyard Voice :: Test Calendar :: January :: 2008

To accomplish this,

Ted wrote a theme_breadcrumb() override and called it vv_fix_breadcrumb().

The code is well commented and should be self-explanatory, even to non-phpers.

I will simply add the theme override code and bold the comments so you can understand what is happening:

/**

* Fix breadcrumbs to work the way we want them to, overriding Drupal.

*

* @breadcrumb - Currently breadcrumb variable from Drupal.

*/

function vv_fix_breadcrumb($breadcrumb = array()) {

// if a user is looking at a calendar

// arg(2) is the group id

if (arg(1) == 'calendar' && is_numeric(arg(2))) {

$breadcrumb = array(); // reset to empty so we can rebuild them

$group = node_load(arg(2));

$view = views_load_view(88); // the views ID of the calendar view

$breadcrumb[] = l('Home', '');

$breadcrumb[] = l('Groups', 'og');

$breadcrumb[] = l($group->title, 'node/'. $group->nid);

$breadcrumb[] = l($view->page_title, $view->url .'/'. arg(2));

// if the view is showing a specific year

if (is_numeric(arg(3))) {

$breadcrumb[] = l(arg(3), $view->url .'/'. arg(2) .'/'. arg(3));

}

// if the view is showing a specific month

if (is_numeric(arg(4))) {

$date = mktime(0, 0, 0, arg(4), 1, arg(3));

$month = date('F', $date);

$breadcrumb[] = l($month, $view->url .'/'. arg(2) .'/'. arg(3) .'/'. arg(4));

}

drupal_set_breadcrumb($breadcrumb);

}

// This section of the breadcrumb override is not for the Group pages, but for the main content types section of the Vineyard Voice

if (arg(0) == 'publish') {

$breadcrumb = array(); // reset to empty so we can rebuild them

$breadcrumb[] = l('Home', '');

if (arg(1) == 'audio' || arg(1) == 'blog' || arg(1) == 'video' || arg(1) == 'writing' || arg(1) == 'image') {

$breadcrumb[] = l(ucfirst(arg(1)), 'publish/'. arg(1));

}

drupal_set_breadcrumb($breadcrumb);

}

return $breadcrumb;

}