Adding a Recurring Schedule to a View

The following is a simplified procedure for integrating a recurring schedule into a view:

1. In one of your application’s tables, create a text field (minimum size=96 characters) to store the XML string representation of the recurrence pattern. The field can have any name you wish, for example recurrence_pattern .
2. In the view in which you will use the recurring schedule panel, add the field above to an existing or new datasource, and include the datasource in one of the view’s panels. Make sure the recurrence_pattern field is hidden, because the XML string cannot be edited directly.
3. Integrate UI into any region in your view (axvw file) by simply adding the line, replacing xxx with the name of the layout region that you’ve defined in the view to contain the recurring schedule user interface:
   <panel type="view" id="recurringPatternPanel" file="ab-common-recurring-pattern-edit.axvw" layoutRegion="xxx" showOnLoad="false" />
   
   To display an existing pattern in the UI’s controls, add the following code to the javascript file that corresponds to your view (axvw) file:
   var recurringPatternCtrl = View.controllers.get("abRecurringPatternCtrl");
var currentPattern = this.formPanel.getFieldValue("table.recurrence_pattern");
recurringPatternCtrl.setRecurringPattern(currentPattern);
   
   The table.recurrence_pattern field is from steps 1 and 2 above. Typically you would add the above code to your view’s afterRefresh listener. formPanel is the panel from step 2. It should be one of the main forms defined in your view, in which you’ll need to include table.recurrence_pattern as a hidden field so that you can get/set its value and so that the form will automatically save the XML string to your table.
   
   
4. When you need to retrieve and store an updated XML string that represents the recurring schedule the user has setup in the Recurring Schedule UI, use the following code:
   var currentPattern = recurringPatternCtrl.getRecurringPattern();
this.formPanel.setFieldValue("table.recurrence_pattern", currentPattern);
   
   The above code is typically placed in your form’s beforeSave listener, and is only necessary when using the recurrence panel as an embedded panel. When using the code in step 5 to display in a popup dialog, the callback function already takes care of saving the updated XML string in your table.
   
   
5. Alternatively, if you prefer to display the user interface in a popup window as a response to some user action (such as clicking a button), use the following in your javascript file instead of the above:
   
   var formPanel = View.panels.get('formPanelName');
var initialPattern = formPanel.getFieldValue("table.recurrence_pattern");
View.openDialog('ab-common-recurring-pattern-edit.axvw', null, false, {
width: 520, height: 225,
closeButton: false,
xmlPatternRecurrence: initialPattern,
callback: function(xmlPatternNew) {
formPanel.setFieldValue("table.recurrence_pattern", xmlPatternNew);
}
});
   
   The code above handles the display of the user interface, the initial setup of the interface to reflect an existing pattern, and updating the pattern in your form’s hidden XML string field. Therefore, this replaces all the code in steps 3 and 4 above. When displaying the recurrence UI in a pop-up window, you must not use any of the code in steps 3 and 4; use only the code above for this step.
   
   The xmlPatternRecurrence variable in the arguments to the openDialog function is required, you must include it. The recurrence panel uses the presence of that variable to enable the pop-up features (e.g. Save and Cancel buttons), and uses the value of that variable to set the initial pattern. You may set the value of xmlPatternRecurrence to null or the empty string in order to initially display a default recurrence pattern of None.
6. Due to user actions or custom logic in your application, you can reset, show/hide, or enable/disable the panel using the clearRecurringPattern , enableRecurringPattern , and showRecurringPatternPanel functions, respectively. This only applies when using the panel in embedded mode. When using it in a pop-up dialog, refer to the parameters for openDialog in the [ab-common-recurring-pattern-edit.js] reference section above.
7. When the user saves the form that the recurring schedule is integrated into, you may need to retrieve the recurrence type and/or total number of occurrences in a beforeSave listener, in order to validate them against any custom rules your application may have. The toolkit provides the getRecurringPatternType and getVal_EndAfterOccurrences functions for that purpose.
8. Whenever there is a need in your application logic to retrieve a list of dates that match a recurrence pattern, use the following code in your application’s java class:
   
   final RecurringScheduleService recurringService = new RecurringScheduleService();
final List<Date> dates = recurringService.getDatesList(dateStart, dateEnd, recurringRule);
   
   The parameters dateStart , dateEnd , and recurringRule are values that you have previously stored in your application’s tables in the database (from steps 1-7), and you would add java code preceding the above lines to retrieve those values from a datasource.
   
   

For weekly, monthly, and yearly patterns for which there are no selections on the right side of the user interface, the generated dates for that pattern will be based on the properties of the Start Date supplied to the WFR. For example:

• if the pattern is weekly and there are no checked check boxes for days of week, then the pattern will be every x weeks on the same day of the week (Sunday, Monday, etc.) as the Start Date.
• If the pattern is monthly and the right side is blank, then the pattern will be every x months on the same day of the month as the Start Date (e.g. 1st, 16th, 23rd, etc.).
• if the pattern is yearly and the right side is blank, then the pattern will be every x years on the same day of the year as the Start Date (e.g. June 30, November 11, etc.). This feature allows you to store a more ‘dynamic’ pattern. For example, if Start Date supplied to WFR is March 21, 2012, and the right side of the interface is blank as described:
  • For yearly, the schedule would be every x years on March 21.
  • For monthly, the schedule would be every x months on the 21st day.
  • For weekly, the schedule would be every x weeks on Wednesday, because 3/21/2012 is a Wednesday.

One use case is Personal Protective Equipment (PPE) in the Environmental Health & Safety (EH&S) application. The general recurrence pattern for required PPE renewal is stored with each PPE type, but the specific generated recurring dates are based on the date that an employee received the PPE. A PPE type may have a yearly recurrence for renewal, and the month and day of the yearly dates for each employee will be on the month and day that the employee received the PPE, which will be the Start Date supplied to the getDatesList WFR.