Extension:Semantic Page Series

MediaWiki extensions manual

Semantic Page Series Release status: unmaintained
Implementation	Special page , Parser function
Description	Generation of multiple pages from one Semantic Form
Author(s)	Stephan Gambke (F.trotttalk)
Latest version	0.4.0 (2017-08-01)
Compatibility policy	Master maintains backward compatibility.
MediaWiki	1.23+
PHP	5.3+
Database changes	No
License	GNU General Public License 2.0 or later
Download	Download extension Git [?]: Download Git master browse repository (GitHub) commit history repository contributors (GitHub) code review Development version README CHANGELOG
Parameters $spsgPageGenerationLimits
Hooks used ParserFirstCallInit
Hooks provided sfEditFormPreloadText sfHTMLBeforeForm
Translate the Semantic Page Series extension if it is available at translatewiki.net

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

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

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

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.

<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

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

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

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

• 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

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.

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

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

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

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

See also

• Semantic Forms
• Semantic MediaWiki