Extension:Page Forms/POM

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

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

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

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.

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).

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

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;

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.

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; ...