1. Requirements
2. How it works
3. Usage
4. DB storage
5. Customizing
6. Resources and included libraries/extensions

This extension provides tools to add the 'recurring events' feature to your application.

The widget displays a form together with your eventmodel, witch generates one or more recurrence rule (see iCalendar spec It uses the library 'WHEN' from T. Planer to calculate the datetimes from rules and to show a preview the datetimes as list or in a calendar. More included third party tools see Resources below.

This extension is very easy to use and supports languages and jquery ui themes.

Requirements ¶

• Developed with Yii 1.1.10
• needs PHP 5.3 >

How it works ¶

• Adds a 'rulescontainer' to your model edit/create form It contains multiple recurring rules/except rules as hidden inputs and a userfriendly description of the rule

• Adds a form where the user can generate the rule (Every first sunday, monday in feb ...)

• Adds buttons/icons to preview the resulting datetimes as list or in a calendar

• Adds a button to add the rule to the rulescontainer

Usage ¶

1. Register the RRuleFormAction component in the controller that runs the RRuleForm widget (see the view code below). In the demo this is the SiteController.

class EventController extends Controller {   

      /**
	 * Declares class-based actions.
	 */
	public function actions()
	{
		return array(
			....
                        'rruleform'=>array(
                         'class'=>'ext.recur.components.RRuleFormAction',
                        ),
		);
	}

1. Create the rrules model instance in your event models insert/create controller action

Yii::import('ext.recur.models.*');
...
public function actionCreate() 
{
   $model = new Event(); //your Event, Exhibition, whatever-model
   ...
   //handle your model 
   ...
   $rrules = RRules::createFromPOST();

   $this->render('create',array('model'=>$model,'rrules'=>$rrules);
   
}

See demo app: views/site/eventform.php

1. Add the RRuleForm widget in the views of the eventmodel (edit/create) It have to be created inside your eventmodel edit/create form-tags, where the rulescontainer should be visible.

<div class="form">
<?php
// show the errors of the rrules model too
echo CHtml::errorSummary(array_merge(array($model),$rrules));

echo CHtml::beginForm();
?>
<div class="row">
<?php
 ..... 
 // show your event input fields here
 ....

//Create the widget inside the events form
//This will create the rulescontainer
$recurWidget = $this->widget('ext.recur.components.RRuleForm',
    array(
        //'theme' => 'cupertino',
        'rrules' => $rrules,
    )
);

//display the preview buttons
$recurWidget->renderRulesListPreviewButton(); 
$recurWidget->renderRulesCalPreviewButton();

echo CHtml::submitButton('Submit'); //the event form

echo CHtml::endForm(); //end of the event form

//render the rrule-form outside the event-form
$recurWidget->renderForm();

See the demo and code for more details or options.

DB storage ¶

This extension doesn't provide AR models for the db, but it should be easy to implement this. You can save the rule-strings directly to the db or generate a 'EventRRules'- AR-model. Use RRules::getRules(); to get the array of string rules for save to db.

See the 'pseudo-code' in SiteController::actionIndex from the demo app.

TIP: If you want to display the datetime of a lot of events it may be useful to save the generated datetimes of the rules too. This will save memory and will increase performance if not for every event/rule the datetimes have to be calculated. You can use RRules->getDateTimes() for that purpose.

And: Take a look at the code...

Customizing ¶

Use the 'rruleform.php' view or 'rrule_summary.php' as template to generate your own rruleform/summary views. You can register the customized views with the widget attributes formView / ruleSummaryView.

Resources and included libraries/extensions ¶

• iCalendar: Recurrence rule
• PHP Date recursion library
• jQuery FullCalendar
• Yii extension echmultiselect
• Yii extension jtimepicker
• Yii extension slidetoggle

Many thanks to the authors.