Extension:RecordAdmin

MediaWiki extensions manual - list

RecordAdmin Release status: stable
Implementation	Data extraction
Description	A special page for finding and editing record articles using forms
Author(s)	nadtalk
Latest version	1.2.2 (2011-06-08)
License	GPL
Download	SVN [?]: checkout-url tree code changes Template:WikimediaDownload/svn
Translate the RecordAdmin extension if possible
Check usage and version matrix; code metrics

RecordAdmin lets you link HTML forms to wiki templates to give the ability to keep records in a MediaWiki.

Installation

Install using subversion on a unix system

To install from subversion under a unix system, change to the directory of your wiki extensions folder and check out the extension code.

cd /var/www/mywiki/extensions
svn co http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/RecordAdmin/

You will need the svn client installed to use this method. Under debian/ubuntu or other apt based system use:

apt-get install subversion

Under Redhat/Centos or other RPM based unix use:

yum install subversion

Configuring LocalSettings.php

Add this line to LocalSettings.php

require_once("extensions/RecordAdmin/RecordAdmin.php");

Global configuration options

• $wgRecordAdminCategory - Categorise a template with this category to tell RecordAdmin that the template represents a data type. Default value is Records so add [[Category:Records]] to your template. It is essential that you do this otherwise you will have no record types to work with.
• $wgRecordAdminUseNamespaces - Specifies whether records should use a namespace for each record type, default value is false.
• $wgRecordAdminEditWithForm - Specifies whether to add an "edit with form" action link for articles which are records. Default value is true.
• $wgRecordAdminAddTitleInfo - Specifies whether to add information about the record type below the article title is it's a record. Default is off.

CSS Styles

Here's some default CSS styles which you can adjust to your own needs, they should go into your MediaWiki:Common.css article (this is an article in your wiki not a file).

/* Styles for Record Admin */
/* http://www.mediawiki.org/wiki/Extension:RecordAdmin */
 
.recordadmin-menubar {
    margin: 0 0 10px 0;    
}
#bodyContent .recordadmin-menubar a {
    color: #6C6E9D;
    font-weight: bold;
    background: #f6f6f9;
    border: 1px solid #aaa;
    padding: 2px 10px;
    margin: 0 10px 0 0;
}
.recordadmin-typeinfo {
    font-size: 14pt;
    color: #ddd;
    font-weight: bold;
    line-height: 1px;
    padding: 0 0 25px 0;
}
form.recordadmin, .recordadmin-template {
    background-color: #f6f6f9;
    border: 1px solid #aaa;
    padding: 10px;
    display: table;
}
form.recordadmin h2 {
    font-size: 11pt;
    padding: 0 30px 10px 0;
    margin: 0;
}
tr.stripe { background: #f6f6f9; }
table.sortable tr.odd {
    background-color: white;
}
table.recordadmin td, table.recordadmin th {
    padding: 0 4px;
    margin: 0;
}
table.sortable th {
    text-align: center;
}
table.sortable td {
    overflow: hidden;
    white-space: nowrap;
    font-size: 8pt;
}
table.recordadmin { width: 100% }
table.recordadmin p { padding: 0; margin: 0; }

Handling records in a wiki

In a wiki the natural way of representing a record is by using template syntax in an article as in the following example:

{{Member
 | Title     = Mr
 | FirstName = Fingers
 | Surname   = McDave
 | No        = 33
 | Street    = Foo St
 | Suburb    = Barville
 | City      = Santabaza
}}

The template (in this case Template:Member) defines how such a record should look to the public, and the corresponding article in the Form namespace (e.g. Form:Member) is used internally by administrators to manage and adjust the records. the template may not contain all the possible parameters because some of them are for internal use only, but the form needs to contain them all.

 Note: In the current version of RecordAdmin, the templates must take the format shown above where each parameter starts on a new line.

Forms

This extension was developed primarily for wikis used in business which don't allow public editing and can therefore have Raw HTML enabled, so the forms can be created using standard HTML as in the following example form. This means that normal Javascript validation techniques can be added.

<html>
    <form>
 
        Title:
            <select name="Title">
                <option>Mr</option>
                <option>Mrs</option>
                <option>Miss</option>
                <option>Ms</option>
            </select>
 
        First names:
            <input name="FirstName" />
 
        Surname:
            <input name="Surname" />
    </form>
</html>

• The class attribute is only included so that CSS rules can be applied to the form if necessary.
• Note that there is no need for any action parameter or submit inputs, all these aspects are handled by the RecordAdmin extension.
• This may be adjusted in future to allow other extensions like SimpleForms to make the forms so that Raw HTML isn't necessary.

Setting up a template for use with RecordAdmin

Make a new template and this content into the page. Replace Visitor with whatever you call your record type.

<noinclude>[[Category:Records]]</noinclude>
<includeonly>[[Category:Visitor]]</includeonly>

Next make a normal template definition to display the information you want.

*Name: {{{name}}}
*Address: {{{address}}}

Using the special page

If no type of record is specified in the special page URL parameter, then a selection of the available records is presented. The records available are obtained from finding all the template articles which are in Category:Records (the category used is set in the '$wgRecordAdminCategory global variable). After a record type has been selected, the form for that kind of record is shown and can then be used to create new records, or define parameters used to find matching records.

Searching for records

The search form works like a filter, so leaving it completely empty and then clicking search will list all members. Filling in some characters such as 123 into the phone field, then clicking search will list all members having 123 in their phone number somewhere. The results will be listed below the form in a sortable table such as in the following example image.

The fields in the search form are regular expressions, so more advanced searches can be done, for example putting ^445 into the phone field will search for all members who's phone number starts with "445".

Editing and viewing records

In the search results list, click edit to change any properties of the member, or click on a results title to go to that member's article to delete it or see its history etc.

Creating new records

If the Create button is clicked instead of Search, then the values in the form will be used to create a new record. If no value is supplied in the Record ID field when a record is created, then a unique ID will be used of the format yyyymmdd-xxxxx where y, m and d represent numbers for the year, month and day, and x are random unique digits and letters.

• GUIDs are useful for the kinds of records such as invoices or log entries which need no specific name.
• You can use CSS to hide the ID input for record types that should be GUIDs

The #recordtable Parser Function

The #recordtable parser function allows sets of records of a specified type exhibiting specified parameters to be rendered in a page using the template corresponding to the record type. This is useful for example for having an article contain certain kinds of products that are currently in stock, or to list members who conform to criteria such as interests or expertise.

Here's an example of the parser function syntax:

{{#recordtable:Inquiry
 | cols     =  select, title, actions, created, modified, Name, Age, Address, Email, Phone, Description, Status
 | sortable =  yes
 | count    =  20
 | orderby  =  Name

 | Phone    =  ^555
 | Age      >  21
 | Status   != Open
}}

The "cols" parameter is used to specify which columns you'd like to be displayed and in what order. The column names are case sensitive. The first five columns shown in the example above are special ones which represent respectively:

• a checkbox for selecting the row
• a link to the record article
• the "edit" and "view" links
• creation date/time
• last modified date/time

The sortable parameter specifies that the results be rendered in a sortable table so that it can be re-ordered by clicking on column headers, and the orderby parameter specifies which column the table should be sorted by initially.

The count parameter limits the number of results to the specified amount, in this case twenty.

The next two parameters are conditions in the form of regular expressions which are applied to the corresponding field name. In this case the table will contain records of type Inquiry and will be filtered to only those with phone numbers starting with "555" and having an "Open" status.

The 'template' parameter

The template parameter used in the #recordtable parser function allows tables to be rendered in a customised fashion by passing the field values to a template to handle the rendering of each row. In the following example records of type "Person" are rendered, but the results are passed to a template called Template:PersonRow.

{{#recordtable:Person
 | cols     = Full name, Email
 | sortable = yes
 | template = PersonRow
}}

The content of the template is defined as follows, and in this example it is used to populate the "Full name" column (which is not one of the defined fields) from a concatenation of the Surname and Firstname fields in the format of "Surname, Firstname".

Content of Template:PersonRow:

<td>{{{Surname}}}, {{{Firstname}}}</td>
<td>{{{Email}}}</td>

Using #recordtable as a form input

Each row in a recordadmin search result is selectable by a checkbox. By default the checkbox is in the first column called "select" which is one of the special inbuilt columns (the others being title, actions, created, modified). This allows #recordtable parser-functions to act as a record selection component in a form.

When a form containing a record table is submitted, the record ID's of the selected rows are posted in an array as with a normal multiple select input element. By default the name of the array is wpSelect but this can be changed by supplying a name parameter in the #recordtable parser function call.

To use the parser-function in a form requires the native MediaWiki #tag parser-function because we need to expand braces inside tags as shown. In the following example all computer records having their CPU field set to "Athlon" will be rendered in a table within a form. Each row will exhibit all columns, the first being the checkbox. When the submit button is clicked, the wpSelect array is posted containing the ID's (titles) of all the rows having their checkboxes checked.

{{#tag:html|<form method=post>
  {{#recordtable:Computer|CPU=Athlon}}
  <input type=submit />
</form>}}

The #recorddata Parser Function

The #recorddata parser function is used to find a specific record title or a field value from within a record depending on the parameters passed. The type parameter is always required no matter what information is needed. Following are a couple of examples.

This example obtain the value of a field from a given record, in this case a contact's phone number from their record title:

{{#recorddata:type=Person|record=Joe Bloggs|field=Phone}}

This example is the other way round, only the record type is known, but not its title. This parser function is designed for finding a specific record or value, so if the result yields more than one record only the first will be returned, and no ordering mechanism is supplied for this currently.

{{#recorddata:type=Person|[email protected]}}

Here is a combination used to find a contact's email address given their phone number:

{{#recorddata:type=Person|record={{#recorddata:type=Person|Phone=555-12345}}|field=Email}}

Record creation links

The RecordAdmin special page allows values for fields to be passed in the query-string so that links can be made for creating new records, which can have some of the values pre-filled according to the context. For example a person's user page may contain the following wikitext which creates a sortable table of "Issue" records assigned to them and includes a link for creating a new issue with the "AssignedTo" field already filled out.

{{#tag:html|<a href="{{localurl:Special:RecordAdmin/Issue|ra_AssignedTo={{PAGENAME}}}}" class="new">Create Issue...</a>}}

{{#recordtable:Issue
| cols = created, title, AssignedTo
| sortable = yes
| AssignedTo = {{PAGENAME}}
}}

• In this example we've set the "AssignedTo" parameter to {{PAGENAME}} since it's in a user page
• The #tag built-in parser function is used so that we can add class="new" to the link to make it red
• Notice that the "AssignedTo" parameter name is preceded by ra_

Public forms

Often it's useful to have public forms that create records but make only a sub-set of the fields available and fill others in internally. For example, you may run a number of sites which all post their enquiry forms to your wiki where they are made into "Inquiry" records. These enquiry forms would be cut-down versions of Form:Inquiry which use hidden values for some fields like "Website" and "User" so the user doesn't have to set them. Also some records may have "staff only" section which shouldn't be present when filled in by end-users. Such forms may also exhibit friendly widgets, validation and styles which are inappropriate for the private administration side. Here's an example of such a "public form".

<html>
        <form action="/Thanks" method="POST">

                First Name:
                <input id="FirstName" name="FirstName" />

                Last Name:
                <input id="LastName" name="LastName" />

                Comments:       
                <textarea name="Comments"></textarea>

                <input type="hidden" name="wpType" value="Registration" />

                <input type="submit" name="wpCreate" value="Register!" />
        </form>
</html>

• The form's action can be set to a different article which can contain a "thank you" message or some other post-submission information
• The resulting page (in this case the "Thanks" article) the tag <recordid /> can be inserted to refer to the unique ID of the created record
• The wpType hidden input is used to specify the type of record that should be created

Form validation

Validation can be done with client side javascript; currently the extension does not support server side authentication. Here's an example of some simple validation that extends the form in the previous example to ensure the two name fields are filled in.

<html>
        <form action="/Thanks" method="POST" onsubmit="return validateRegistration(this)">

                First Name:
                <input id="FirstName" name="FirstName" /> <span class="error">*</span>

                Last Name:
                <input id="LastName" name="LastName" /> <span class="error">*</span>

                Comments:
                <textarea name="Comments"></textarea>

                <input type="hidden" name="wpType" value="Registration" />

                <input type="submit" name="wpCreate" value="Register!" />

                <script type="text/javascript">

                        manditory = [ 'FirstName', 'LastName' ];

                        function validateRegistration(form) {
                                var done = true;
                                for (i in manditory) if (document.getElementById(manditory[i]).value == '') done = false;
                                if (!done) alert('Please ensure that all the fields marked with red asterisks are filled in!');
                                return done;
                        }
                </script>
        </form>
</html>

• A simple JavaScript validation function has been added to the form and is called from the form's onsubmit attribute
• The fields that are manditory are added in the script to the manditory array
• We've added asterisks after the manditory fields, which are made red with MediaWiki's "error" CSS class

Useful RecordAdmin templates

still in development

Sites using RecordAdmin

• OrganicDesign:Issue - this article shows how we use RecordAdmin on our private wiki to organise and account for our development work
• University of Auckland - used by the Faculty of Science to organise contacts, incidents, labs and other things

External links

• Examples of some well designed web forms

See also

• Extension:SemanticForms
• CcTeamspace - MediaWiki based organisational system used by Creative Commons
• TemplateForms - Another project for editing templates using forms being discussed on the Wikitech list