Extension:Semantic Page Series

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
Semantic Page Series

Release status: beta

Implementation Special page, Parser function
Description Generation of multiple pages from one Semantic Form
Author(s) Stephan Gambke (F.trotttalk)
Latest version 0.1 (2012-02-02)
MediaWiki 1.17+
PHP 5.2+
Database changes No
License GPL 2.0 or higher
Download Semantic Page Series 0.1

Development version
README
CHANGELOG

Parameters
  • $spsgPageGenerationLimits
Hooks used
ParserFirstCallInit

Translate the Semantic Page Series extension if it is available at translatewiki.net

Check usage and version matrix; code metrics

The Semantic Page Series 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[edit | edit source]

$IP stands for the Installation Path (or "directory") of your MediaWiki installation, the same directory that holds LocalSettings.php, index.php etc..

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
  2. Extract the files to the $IP/extensions directory
  3. If necessary rename the newly created directory to SemanticPageSeries
  4. Add to the end of LocalSettings.php below the inclusion of the Semantic MediaWiki and the Lingo extension:
    require_once("$IP/extensions/SemanticPageSeries/SemanticPageSeries.php");
  5. Do some customization if necessary (see below)
  6. 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[edit | edit source]

The following settings may be used:

  • $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.

Default setting:

    $spsgPageGenerationLimits = array(
      '*' => 0,
      'user' => 10,
      'sysop' => SPS_NOLIMIT
    );

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

Usage[edit | edit source]

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[edit | edit source]

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

<noinclude>
This is the "Event" template.
</noinclude><includeonly>
{| class="wikitable"
! Title
| [[Description::{{{Title|}}}]]
|-
! Date
| [[Date::{{{Date|}}}]]
|-
! Location
| [[Location::{{{Location|}}}]]
|}
[[Category:Event]]
</includeonly>

Create Form:Event[edit | edit source]

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.

<noinclude>
This is the "Event" form.

To create or edit a page with this form, enter the page name: {{#forminput:form=Event}}

</noinclude><includeonly>
{{{info|page name=<Event[Title]> <unique number>}}}

{{{for template|Event}}}
{| class="formtable"
! Title:
| {{{field|Title|mandatory|restricted=user}}}
|-
! Date:
| {{{field|Date}}}
|-
! Location:
| {{{field|Location}}}
|}
{{{end template}}}

'''Description:'''
{{{standard input|free text}}}

{{{standard input|save}}}
</includeonly>

Create Form:EventSeries[edit | edit source]

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.

<noinclude>
This is the "EventSeries" form.

</noinclude><includeonly>
{{{for template|Event}}}
{| class="formtable"
! Title:
| {{{field|Title|mandatory|restricted=user}}}
|-
! Start of the event series:
| {{{field|Start}}}
|-
! End of the event series:
| {{{field|End}}}
|-
! Repeat every:
| {{{field|Period}}}{{{field|Unit|input type=dropdown|values=day,week,month,year}}}
|-
! Location:
| {{{field|Location}}}
|}
{{{end template}}}

'''Description:'''
{{{standard input|free text}}}

{{{standard input|save}}}
</includeonly>

Include a link to the series form[edit | edit source]

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:

{{#serieslink:
form=EventSeries
|link text=Create event series
|link type=button

|iterator=date
|target form=Event
|target field=Event[Date]

|start=Event[Start]
|end=Event[End]
|unit=Event[Unit]
|period=Event[Period]
}}


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[edit | edit source]

  • 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 <unique number> 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[edit | edit source]

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[edit | edit source]

The date iterator will generate dates or datetimes.

Parameter Meaning/Remark Default Allowed values
start Mandatory. Specifies the first date or datetime of the series. None Any date or datetime
end Specifies the latest date or datetime an event of the series might occur. the start date Any date or date/time
period Specifies the period between generated dates. 1 Any number
unit Specifies the unit to be used with the period. Using dayofweekinmonth you can specify that all events of a series shall occur at the same day of the same week of a month, e.g. every 3rd Thursday. day day, week, month, year, dayofweekinmonth

count[edit | edit source]

The count iterator will generate a series of numbers.

Parameter Meaning/Remark Default Allowed values
from Specifies the first number of the series. 1 Any number
to Specifies the last number of the series. the from value Any number
step Specifies the step width between generated numbers. 1 Any number
digits Specifies how many digits the generated numbers shall at least have. If a number is too small, it will be padded with zeros. 1 Any number

page[edit | edit source]

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

Parameter Meaning/Remark Default Allowed values
pagenames Specifies the list of pages to be iterated upon. String

Contact[edit | edit source]

Comments, questions and suggestions should be sent or posted to:

Sponsorship[edit | edit source]

This extension was sponsored by Prescient Software

See also[edit | edit source]