Extension:Semantic Forms/POM

From MediaWiki.org

Jump to: navigation, search

Page Object Model or POM is a proposal for extraction of page/template handling functionality from Semantic Forms to a separate API that will allow an abstract interface for templated pages manipulation. The name shows the similarity of concepts between POM and DOM

Contents

[edit] Rationale

[edit] Semantic Forms development

As Semantic Forms extension grows and more and more functionality is required, it becomes apparent that abstracting page processing is necessary.

Some tasks that will benefit from such abstraction (feel free to add to this list):

  • multiple forms to edit the same page where smaller forms to edit parts of the page can inherit some definitions from parent form
  • currently, the form-handling code, mostly contained in SF_FormPrinter.inc, does up to six tasks concurrently: parsing the form definition, parsing the existing page, parsing relevant semantic attribute/relation/property pages, creating an HTML form, handling a submitted form (which includes field validation), and creating a new page based on the submitted form. These tasks can be separated into separate classes, to make the code clearer and more maintainable

[edit] Third party extensions

Other extensions and maintenance scripts can benefit from having page and template parsing abstracted for them.

Examples include:

  • command line tools that want to manipulate just some template parameters without parsing whole page
  • MediaWiki API extensions to allow AJAX tools to edit some parts of the page without caring about parsing the content of the pages
  • tools to allow for automated addition or editing of information, also using the MW API
  • outside applications that can use a semantic wiki as a database, such an online spreadsheet or a PDA application, also using the MW API

[edit] Lower level of abstraction

First (lowest) level of abstraction is separated into Extension:Page Object Model that is going to implement features only depending on standard MediaWiki syntax. It might be a good idea to build functionality described on this page as higher layer extension relying on Extension:Page Object Model to do all underlying work.

We might want to rename this page into Page Object Model Schema (POMS) or PageSchema or something like this.

[edit] Possible class structure

Here is a possible class structure for POM:

  • POM::Page - represents a page.
    • templates() gets either all templates or all "template collections" for the page
    • templates('template_name') is a reference to the POM::TemplateCollection object for 'template name' template
  • POM::Element - represents any data element within a page.
  • POM::TemplateCollection - subclass of POM::Element - represents all templates on a page that are of a certain type.
    • count() gets the number of such templates
    • [i] references the i-th instance of this set
    • append($template) adds another template to this set
  • POM::Template - subclass of POM::Element - represents a single template instance on a page.
    • parameter('parameter_name') is a reference to the POM::TemplateParameter object with this name
    • setParameter($name, value) sets the value of a parameter in this template
  • POM::TemplateParameter - subclass of POM::Element - represents a single parameter in a template. (This class might not be necessary.)
  • POM::Field - subclass of POM::Element - represents a standalone field on a page (in Semantic Forms there are two - "free text" and "page title")
  • POM::PageDefinition - represents a page definition similar to or the same as the current form definitions that define the sequence of templates and fields, and their properties (and maybe more things in the future), but not the form appearance
    • templateDefinition('template_name') gets the POM::TemplateDefinition for the 'template_name' template
  • POM::TemplateDefinition - represents a template definition within a page definition
    • createInstance() creates an instance of POM::Template matching this definition
  • POM::FieldDefinition - represents a field definition within a template definition (unless it's the "free text" field, which is outside of any templates).

[edit] Code use cases

[edit] Creating POM object

my $page_definition = new POM::PageDefinition('Form:User');
my $userpage = new POM::Page('User:Sergey Chernyshev', $page_definition);

[edit] Handling multiple instance templates

my $favorites = $userpage->templates('Favorite'); // instance of POM::TemplateCollection class
my $favorites_definition = $page_definition->templateDefinition('Favorite') // instance of POM::TemplateDefinition class
my $new_favorite = $favorites_definition->createInstance(); // instance of POM::Template class
$new_favorite->setParameter('url', 'http://google.com');
$new_favorite->setParameter('title', 'Google');
$favorites->append($new_favorite);

$favorites[4]->setParameter('url', 'http://www.google.com');
$favorites[5]->delete();

[edit] Use cases

[edit] Command line image localization tool

Some fictional tool that will download files referenced in template by "fileURL" parameter and add local version using "mediaTitle" parameter to change external links to images/PDF documents to locally hosted.

Real life scenario is to have local copies for TechPresentations.org presentation files backed up locally.

[edit] Original wiki article example

<pre>
{{Presentation
...
|fileURL=http://ajaxexperience.techtarget.com/images/Presentations/Crockford_Douglas_JavaScript.ppt.pdf
}}

[edit] Pseudocode

Get the url of the file to download

$article = POM::Parse('JavaScript The Good Parts');
$url = $article->getElementsByName('Presentation')[0]->getTemplateParameter('fileURL');

Download the file and save it as local Wiki media title (out of scope of POM)

$filename = download($url);
$mediaTitle = addLocalFile(makeLocalTitle($url), $filename);

Set new parameter that references this new local media title

$article->getElementsByName('Presentation')[0]->setTemplateParameter('mediaTitle') = $mediaTitle;
$resultwikitext = $article->toWikiText();
...

[edit] Resulting wiki article

{{Presentation
...
|fileURL=http://ajaxexperience.techtarget.com/images/Presentations/Crockford_Douglas_JavaScript.ppt.pdf
|mediaTitle=Media:Crockford_Douglas_JavaScript.ppt.pdf
}}
Retrieved from "http://www.mediawiki.org/wiki/Extension:Semantic_Forms/POM"