Personal Calendars

It is possible for users of your web site to keep a list of events you have published that they are interested in. This works similarly to a shopping cart in that they can add or remove events to their own personal list of events. This is available to both logged-in users and anonymous users.

Note

The difference between the "event cart" and a real shopping cart is that you can't buy events, and the event cart doesn't have the concept of quantities.

For this to work you need to give your user the option to add an event to their cart. You can do this when outputting a list of events (with the Calendar: Event Index container rule) or when displaying a single event's details (with the Calendar: Event Details container rule).

You can then add the Calendar: Event Cart container rule so a user can view and manage their events.

Event Clashes

In the event a user adds events that clashes with each other, you can give the user the option to choose their preference for clashing events. This is covered below.

Event Management Actions

You can add or remove events using either normal forms or Ajax requests. If you use Ajax, JSON data is returned that you can use as required. This is covered shortly.

Adding Events: cartadd

To add an event, submit your form to $forms.cartadd.action with a form method of $forms.cartadd.method. This form requires a parameter called event which contains the URL value (such as $event.url) of the event.

If not using Ajax, you can specify the return parameter which contains the URL of the page to load after the event has been added. If this omitted the user is returned to page they were on when they added the event.

Here is a sample template:

<form method="{$forms.cartadd.method}" action="{$forms.cartbulk.action}">
    <div>
        <input type="hidden" name="event" value="{$content.url|escape}" />
        <input type="submit" value="Add" />
    </div>
</form>

Additionally, the event data contains a parameter called in_cart which is true if the event is already in the user's cart, and false if not. You can use this determine whether to show add button or a remove button (removing is covered shortly).

{if $content.in_cart}
    {* show remove form or no form *}
{else}
    {* show add form *}
{/if}

Removing Events: cartremove

Similar to adding events, you can also remove them. The only difference is that you use the $forms.cartremove.action and $forms.cartremove.method values instead.

You can use the in_cart variable once again to determine if the event is already in the cart, although if you're using the event cart rule you can assume that all events are already in the cart.

A sample template is as follows:

<form method="{$forms.cartremove.method}" action="{$forms.cartremove.action}">
    <div>
        <input type="hidden" name="event" value="{$content.url|escape}" />
        <input type="submit" value="Remove" />
    </div>
</form>

Empting Event Cart: cartempty

To remove all events in a user's cart, submit to the $forms.cartempty.action URL.

<form method="{$forms.cartempty.method}" action="{$forms.cartempty.action}">
    <div>
        <input type="submit" value="Remove All" />
    </div>
</form>

Resolving Clashes: cartclash

When using the event cart and displaying a list of all events for a user, you can also determine any clashes using the clashes array. Each element in this array has a key and value: The key is the ID field of the event it clashes with, while the value is the URL field of the preferred event.

To resolve a clash you must submit to $forms.cartclash.action. There are three required parameters: event1, event2 and preferred. The first two parameters (event1 and event2) correspond to the ID field of the two events the clash is being resolved for, while the preferred field should contain 0 for no preference, the value of event1 if the first event is preferred, or the value of event2 if the second event is preferred.

A sample template is provided with Recite for outputting clash data and resolve form.

Bulk Managing Events: cartbulk

You can bulk add or remove events using the $forms.cartbulk.action URL. This action can accept an array called add[] which contains the URL field of events to add, an array called remove[] which contains the URL field of events to remove, and a parameter called empty, which if present will empty the cart.

Events are removed prior to being added, so if the same URL is present in the remove and the add arrays then ultimately the event will be added.

There is a sample template provided with Recite which demonstrates this functionality.

Form Response Data

When you submit any of the described actions, you can access a summary of what has occurred in the event cart container rule. This is available with the $status array, which contains the following keys:

  • added – List of events that were added

  • updated – List of events that were updated (specifically, events that has clashes resolved)

  • removed – List of events that were removed

  • emptied – True if the event cart was just emptied

There is a sample of this in the cart-summary.tpl template in Recite.

Ajax Response Data

If you submit any of the cart actions using Ajax, the following data is returned as a JSON array. Note that any of these may be omitted.

  • added – An array of events that were added. Each element is an object with an id and title property corresponding to the event that was added.

  • removed – An array of events that were removed. Each element is an object with an id and title property corresponding to the event that was removed.

  • emptied – This is a boolean set to to true if the cart was emptied.

  • error – This is a boolean set to true if an error occurred.

  • errormsg – If an error occurred then this contains a description of the error that occurred.