EXT: calendar¶

Table of Contents¶

EXT: calendar 1

Introduction 2

What does it do? 2

Screenshots 3

Users manual 4

How to customize this extension 5

Speed issues 6

FAQ 7

Introduction¶

Installation and Setup¶

Install the extension with the extension manager.

You need to create one page for every view you would like to use. Create one page for every view you plan to use. Also create a SysFolder (or a SysFolder-tree) that shall hold the calendar events, categories, target groups, etc The resulting page tree could look like this:

Now on each page, add the plugin to the page. On each page, the plugin must be configured. The following settings must be adjusted for each page.

• Under the “General Settings” tab (see screenshot below), change the “ View mode ” to the desired view mode of that page. You'll need at least one page that holds the “Event” view and one of the other views that lists the actual events (such as the “Upcoming” view, the “Month” view etc). Specify the “Month page”, “Week page”, “Day page”, and “Event page” that contain the respective views. Also specify in “ Startingpoint ” one or more SysFolders that contain the events, target groups etc. Don't forget to set “Recursive” if needed.
• Under the “Template” tab, choose a template that corresponds to the “View mode” you have chosen in the first step. For starters, you may just use one of the included default templa tes (“Use default template for”). You can later modify the included default templates (included in the EXT:calendar/templates/ directory).

Once you have added the plugin to all the pages, and customized it for each page, the extension should work out of the box.

Adding events¶

I suggest you try out some of the features that this extension has. Due to time limits, there currently is no documentation.

The most important thing about events is: If you don't specify neither start-time nor end-time, this event is considered to be an “all- day”-event.

If you want to add exceptions to recurring events, you should select “Exception” and insert the date of the exception into the “Start Date” of the event. This will automagically overwrite the day's recurring event with the exception.

How to customize this extension¶

Thanks to its TypoScript backend, you can fully customize this extension to fit your needs.

For instance, you can modify the standard templates (included in the EXT:calendar/templates/ directory). You can also modify the default TypoScript code that inserts the contents into the templates' markers.

And even more, you can even create your own rendering functions, i.e., you can, for instance, write a PHP function that outputs your own customized month view.

I currently don't have the time to write the documentation on the API for this part of the extension, but you can contact me by email if you need hints on how to do this.

For starters, I suggest you look at the rendering process of the month view that works as follows:

• The month itself is a standard Typoscript TEMPLATE.
• One of the subparts in the template is called “WEEKS”, and is used to render the weeks within the month view.
• By recursion, the weeks are built from a number of DAYS, and for each day, there are a number of events that are to be rendered.

Within TypoScript, the TEMPLATE-cObj gets the relevant list of ``events'' that are to be rendered in this view as the standard “data” parameter. Within PHP, you can access them via $this->cObj->data['events']. This data includes standard “rows” of all the events of the rendered timespan in the following form:

$events[theYear][theMonth][theDay][rowUid] = array(...)

where theYear/theMonth/theDay are the date of the event, and every day is just an array of events, included by their unique id from the database (MySQL) table.

Now, you could for example easily write a PHP function that renders a month view without recursively calling a week-cObj again. Rather, this PHP function could just directly output the event in the way you want. (Hint: Within TypoScript, use “event < plugin.tx_calendar_pi1.event” if you want to use the extension's default TypoScript code for rendering events, and just use a standard PHP cObj to render this. Refer to the Typo3 documentation for more info. Using custom functions is expected to be much faster than the way it's currently done with nested TypoScript objects. However, this requires custom modifications and is only suitable for experienced Typo3 and TypoScript developers. Be welcome to contact me for questions on this topic.

Speed issues¶

The extension might render slow on small/old hardware such as small virtual servers. If you properly set up Typo3 to cache previously rendered pages, this only happens to the first visitor per day but is probably not desired. Hence:

• Be sure to use a PHP accelerator such as eaccelerator or PHP-APC
• Be sure to use Typo3's included caching framework

Here are some hints to speed up the rendering process even further:

You may write your own PHP function that renders the views. This requires some in-depth knowledge of Typo3 development (extensions and TypoScript), but is generally possible since the views are rendered byUSER Typoscript objects. See above for some more hints on this topic.

The second option can be done quickly and is suggested for any installation. In the month view, there are at least 5 weeks, and thus 35 days that are displayed. This results in 1 (month) + 5 (weeks) + 35 (days) + X (events) TypoScript Content Objects being created and processed. Every event includes 15 markers again, because events are basically rendered through a TEMPLATE cObj. The same holds for days objects, week objects etc. With three month-views on a page, this easily results in 100 TypoScript objects in total, which kills slow hardware.

If, however, in the month viewyou'd only use the EVENT_TIME and EVENT_TITLE markers on the month-view (as in the default templates), there are many markers that are obsolete and can be pruned. Just remove all the markers from the views that you don't need. In TypoScript, using the TypoScript Object browser, just clear the obsolete markers such asplugin.tx_calendar_pi1.month.subparts.WEEKS. week.subparts.DAYS.day.subparts.EVENTS.event.marks.EVENT_IMAGE etc. Proceed with all markers that are not needed.

FAQ¶

• Q: New events are not shown in the view A: That's probably due to caching. Click on “Clear all cache” and see if they appear.
• Q: The extension won't render, and my Webserver's log files mention memory_limit problems. A: In the default configuration a lot of markers are used, which takes a lot of memory. I needed to raise the php memory limit to 24M to make this extension run. If you remove all markers but the ones you need, you might be able to run it with 16M as well.
• Q: I need installation help or a new feature. Can I sponsor development? A: Yes, you can. Please contact me by email.
• Q: Can I help with development? A: You are very welcome!

EXT: calendar - 11