SMW & Forms Guidelines

From DocWiki

Jump to: navigation, search

This DocWiki uses a combination of a fixed, baseline category structure with a judicious use of Semantic Mediawiki (SMW) and some of its extensions to create its structural organization and functionality. This page describes the SMW and extension portions and their use.

Contents

SMW and Extensions

These are the Semantic Mediawiki and extensions currently used on DocWiki:

  • Semantic Bundle - this is the inclusive distribution package for the other semantic components based around the Semantic MediaWiki extension, including:

In addition, though not strictly related to SMW, these extensions also provide useful organizational functionality:

  • CategoryTree - dynamically navigate the category structure
  • Multi-Category Search - represents a special page, that allows to find pages, included in several specified categories at once.

How Used

At present, SMW is limited to use for task entry and selected listings. Here are examples of the:

General Syntax and Use Guidance

The best examples of SMW syntax and conventions come from its help pages on:

Also, the [user manual] is quite helpful, including its quick "cheat sheets".

For Semantic Forms, its main page provides much useful guidance. Also, there is a useful example of a book author) that is worth following for your first exposure.

Proper Sequence of Use on this DocWiki

The same guidance as is provided for Semantic Forms is used on this DocWiki. Namely, the proper sequence of adding and modifying structure to the site, with links where appropriate to internal resources, is:

  1. Figure out your data structure - what types of pages will the site have? What data will be contained on each one? You can change all of this around later, but it's good to have a starting plan.
  2. Create properties - the basic building blocks of any semantic site are the connections between data, which in Semantic MediaWiki are known as properties. A property is used to specify a single piece of information about the topic of this page; the value of a property can either be a standalone value, or the name of a page on the wiki. Every property should be defined on your wiki, with a page in the "Property:" namespace. The easiest way to do that is using the 'CreateProperty' special page (see above).
  3. Create templates - a template sets the display of the data on a page, holds the markup to turn the data into actual semantic information, and (often) defines the page as being of a certain category, and thus of a certain page type. There will generally be one template per page type, although sometimes a single page type will contain more than one template. A template can also be used for aggregation, by displaying a list of all other pages that have a certain relationship to this page (see the inline queries documentation for much more information on this). The easiest way to create templates is using the 'CreateTemplate' special page (see above).
  4. Create forms - now you can create forms to allow users to easily add and edit pages of various types. There should be one form per page type; a form should populate the template or templates that this page type contains. As before, there's a special page to create new forms: 'CreateForm' (see above). See below for documentation on the special markup language used to define forms. One common request is for these three special pages ('CreateProperty', 'CreateTemplate' and 'CreateForm') to be able to edit existing property/template/form pages, and not just create new ones. However, this is programatically much harder to implement than creating new pages, because it requires parsing. For the foreseeable future, modifying existing properties, templates and forms will have to be done by hand. In other words, go to the properties, templates or forms pages (which are listed in special pages) and select what you want to modify. Clicking on the edit tab will allow you to do what you want by editing the source code.
  5. Create categories - one template in each form should define each article that the form creates as being part of a certain category. In the case of DocWiki, these are the Activity page for tasks. You should create a page for each such category, and specify a default form for it so that every article is automatically editable with the same form that created it. The easiest way to do that is using the 'CreateCategory' special page (see above).
  6. Enable links to forms - besides creating categories that have a default form, there are other steps you should take to enable users to access the forms that you have created. These include adding links to add data in the sidebar and elsewhere, and setting default forms and alternate forms on properties, to have red-links to nonexistent pages point to a form for creating them. These actions are all explained further below.
  7. Add data - lastly, you should also add data to the site, using your new forms, to make sure that forms, templates and categories are working the way you want them to.

Other Useful Tips

There are also some other special pages on this site that can help you use or learn more about these capabilities. You may want to check out:

Retrieved from "http://docwiki.citizen-dan.org/index.php/SMW_%26_Forms_Guidelines"
Personal tools