Extension:Semantic Page Series
This extension is currently not actively maintained! Although it may still work, any bug reports or feature requests will more than likely be ignored. If you are interested in taking on the task of developing and maintaining this extension, you can request repository ownership. As a courtesy, you may want to contact the author. You should also remove this template and list yourself as maintaining the extension in the page's {{Extension }} infobox. |
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 |
Development version README CHANGELOG |
|
|
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
[edit]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.
- Download a released version or the current development version
- Alternatively you can clone Semantic Page Series using git
- Extract the files to the
$IP/extensions
directory - If necessary rename the newly created directory to SemanticPageSeries
- 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";
- Do some customization if necessary (see below)
- 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]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]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]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]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]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]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]- 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]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]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]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]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]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
[edit]This extension was sponsored by Prescient Software