Create datastructures from Page Schemas

Why Page Schemas?

Creating an Semantic MediaWiki app (i.e., a collection of SMW pages to accomplish some task) typically requires creating a collection of SMW datastructures: categories, forms, properties, and templates. (Users of Cargo can omit the properties.) The original/default way provided to create these datastructures is MW GUI, i.e., clicking through webforms. This default manual procedure has several problems:

1. tedium. Even a very simple app, like the Books example from the Page Forms Quick Start Guide (PFQSG), involves a lot of clicking and typing.
2. irreproducibility. Suppose you want to port your app to a new wikihost, or recreate your old one after a failure? Good documentation (like the PFQSG) can help, but it's still all-too-easy to make mistakes when clicking through endless GUIs.
3. lack of version control. You can't VC clicks. You can automate those clicks with a webtest tool, and then VC the webtest code ... but that's Real Work. (The payoff for that additional work is test automation, which is itself valuable.)

Page Schemas allows one to capture a description (or schema) of one's datastructures in text (XML)

1. from which one can relatively easily and reproducibly generate the datastructures, with much less GUIing.
2. that is easily VCed.

Note there are other tools that deliver the same value-add for SMW apps (and in some cases additional benefits), like Mobo. But those other tools are typically external to a MW or SMW wiki, requiring separate installation on the wikihost (as does Mobo). By contrast, Page Schemas is an SMW extension; the admin/sysop of an SMW wikihost may find that advantageous.

Tutorial

The following procedure illustrates how to create SMW datastructures (and to generate MW data from them) on the sandbox.

1. Create sample Page-Schemas-compliant XML for a category. Since, for tutorial purposes, you want this to Just Work, consider using the following XML adapted from the Page Schemas sample (minus ellipses in original):

<PageSchema>
    <pageforms_Form name="City">
        <standardInputs/>
    </pageforms_Form>
    <Template name="City" format="standard">
        <Field name="Population">
            <Label>Pop.</Label>
            <semanticmediawiki_Property name="Has population">
                <Type>Number</Type>
            </semanticmediawiki_Property>
            <pageforms_FormInput>
                <InputType>text</InputType>
                <Parameter name="size">20</Parameter>
                <Parameter name="mandatory"/>
            </pageforms_FormInput>
        </Field>
    </Template>
    <Section name="History" level="2">
        <pageforms_PageSection>
            <Parameter name="rows">10</Parameter>
            <Parameter name="mandatory"/>
        </pageforms_PageSection>
    </Section>
</PageSchema>

This example XML defines a category containing a form/template with a name and 2 fields (History and Population) to be used to define datastructures (various types of pages) within that category.

2. Start a non-existent page for your category, e.g., https://sandbox.semantic-mediawiki.org/wiki/Category:Cities by attempting to browse to it. (If you do not get an edit page, choose another URI.)

3. In the resulting edit page: paste your sample XML into the edit area, and save it.

4. In the resulting category page (which will be https://sandbox.semantic-mediawiki.org/wiki/Cat%C3%A9gorie:Cities because the default site language is French), click the link=[Expand] to show your schema, which should resemble this:

Form: City
    standardInputs
Template: City
    format             standard
    Field: Population
        Label              Pop.
    Semantic property: Has population
        Type               Number
    Form input
        Input type         text
        size               20
        mandatory
Section: History
    Level              2
    Other parameter
    rows               10
    mandatory

5. Near top right of that page, you should see a dropdown named More. This should expand to include a list of links including Generate pages. Click the latter link.

6. In the resulting page (title=Generate pages), you should see 3 items: Attribut:Has population , Formulaire:City , Modèle:City. Ensure any redlinked items are selected (i.e., check the adjacent box). (Note that the property='Has population' has previously been created, so is not redlinked, and does not need recreated for our purposes.) Click button=Generate pages.

7. The response at the resulting page will be like

The selected pages will be generated.

because the page-generation process is asynchronous. Nevertheless, you will probably be able to test-browse to your form's page immediately ... except that you will need to guess its URI. To do that, ...

8. Go back to your category page, and copy its URI, e.g.,

https://sandbox.semantic-mediawiki.org/wiki/Cat%C3%A9gorie:Cities

To get the URI for your form's page (presuming you have followed the steps above using the schema XML above), change Cat%C3%A9gorie:Cities to Formulaire:City to get

https://sandbox.semantic-mediawiki.org/wiki/Formulaire:City

9. Browse to your form's page/URI. It should show you a text field (for entering the {city, page} name) and a button. Enter a city name (which could be anything you want--I used Foo), and click the button: this will allow you to create that page using the form you defined in your schema XML (above).

10. The resulting page should have fields matching your schema (2 fields for history and population), plus an additional field name ~= Texte libre (for text that will append to your page--feel free to leave that blank), plus the usual MediaWiki edit-page UI ... and not much else! Fill-in the fields as you see fit, and click the button to save the page.

11. The resulting page should contain the data you entered! and resemble my page.

Congratulations! You have now either

• successfully created SMW datastructures from a Page Schema, or,
• shown great diligence but failed. If you believe you should not have failed, and want help, try the following:
  1. Look for an issue matching yours at the SMW sandbox's issue tracker. If you find one, consider appending your experience to that issue (and opening it if it was previously closed).
  2. If you do not find an issue matching yours, create a new issue with label=s-mw.org - sandbox

Note that the functionality demonstrated in this tutorial is on this wiki tied to the "contributor" permission. You may ask for it on this talk page.