Extension:Semantic Page Series

The Semantic Page Series extension allows a wiki user the generation of a series of pages from one Semantic Form.

An example use case is to create pages for recurring events. Where without this extension this was solved by having one page for the whole series and using the #set_recurring_event parser function of Semantic MediaWiki, it is now possible to create a dedicated page for each event occurrence.

Installation
''Note: Having MediaWiki (version 1.17 or higher), Semantic MediaWiki (version 1.5.3 or higher) and Semantic Forms (version 2.4 or higher) installed is a precondition for the Semantic Page Series extension; the code will not work without them. Lower versions might work but are not tested.''


 * 1) Download a released version or the current development version
 * Alternatively you can clone Semantic Page Series using git
 * 1) Extract the files to the   directory
 * 2) If necessary rename the newly created directory to SemanticPageSeries
 * 3) Add to the end of LocalSettings.php below the inclusion of the Semantic MediaWiki and the Lingo extension:
 * 4) Do some customization if necessary (see below)
 * 5) Go to the Special:Version page of your wiki and verify that an entry for Semantic Page Series exists

There is a version history available.

Customization
The following settings may be used:

Default setting:
 * $spsgPageGenerationLimits to specify the maximum number of pages that may be generated per request by a member of a user group. If a user is in more than one group, the highest number is used.

If you want to change the default settings, just include the new values in LocalSettings.php after the inclusion of the extension.

Usage
The usage of the extension will be explained using the above mentioned example of a series of event pages. It is assumed that MediaWiki with the Semantic MediaWiki and the Semantic Forms extensions is installed and working (see dependencies above).

The general setup steps are:
 * Create a template for one event
 * Create a form definition for one event
 * Create a form definition for the event series
 * Include a link to your event series form somewhere

Create Template:Event
Nothing special going on here. It's just a simple template as you would normally use with Semantic Forms.

This is the "Event" template.

Create Form:Event
Again nothing special going on here. Well, with a small caveat: To be able to create the event pages automatically, e.g. without the user having to specify the name of every event page, you have to make sure that the form supports the one-step process. This is done by adding a "page name" parameter within the form definition's "info" tag.

This is the "Event" form.

To create or edit a page with this form, enter the page name:

Description:

Create Form:EventSeries
This form looks nearly identical do the Event form above. The only difference being, that the Date input field is removed and replaced by input fields to specify how the page series is to be created: Start, End, Period and Unit. You can also remove the page name parameter of the info tag or - as there are no parameters left in this case - the whole info tag. All the other form fields have to remain. During the creation of the pages of the series the values from these fields are copied into the respective fields of the Event form.

This is the "EventSeries" form.

Description:

Include a link to the series form
To tie it all together and include a link on a wikipage, the #serieslink parser function is used. It takes all the parameters, that #formlink takes, except of course the target parameter. Additionally you have to specify what iterator is to be used - date in this case, the target form to be used to create the pages of the series and the target field that should be populated by the iterator. Finally you have to specify the form fields where the parameters for the iterator come from. It is quite a lot, but have a look at the example:

That's it. Now, when the users click the button they are taken to a Semantic Form (defined in Form:EventSeries). On the form they can specify the recurring date parameters among all the other information, e.g. location. When they hit "Save" the necessary jobs to create the pages of the series are created in the job queue using Form:Event.

Pitfalls

 * With this extension it is possible to - intentionally or unintentionally - generate a large number of pages with very little effort. Configure your wiki carefully!
 * Semantic Page Series does not check if a page already exists. Should one page of the series have a name for which a page already exists, the existing page will be overwritten. To reliably prevent this, use a &lt;unique number&gt; in the page name definition.
 * This might of course be useful to change a whole series of pages at once. However, Semantic Page Series will not delete any pages which were in the series previously and due to changed data would not be in anymore.
 * Due to the fact that pages are created using jobs, it is not possible to directly output error messages. If there are any problems you will have to check the log files. You might have to turn logging on first. The debug log group of Semantic Page Series is sps.
 * Diff and preview action are not supported.

Iterators
''This paragraph describes the iterators available in the upcoming version 0.2 (and in the development version available from SVN). The current version 0.1 only provides the date iterator with all parameters mandatory.''

date
The date iterator will generate dates or datetimes.

count
The count iterator will generate a series of numbers.

page
The page iterator will generate a series of pages using each value within a comma-delimited list of page names.

Contact
Comments, questions and suggestions should be sent or posted to:
 * the Semantic Mediawiki User mailing list (preferred)
 * the Semantic Page Series discussion page
 * the author

Sponsorship
This extension was sponsored by Prescient Software