Extension:Page Forms/POM

Page Object Model or POM is a proposal for extraction of page/template handling functionality from Semantic Forms to separate API that will allow 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

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::TemplateCollection 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 represents a single template instance on a page.
 * parameter('parameter_name') is a reference to the POM::TemplateParameter object with this name
 * append($parameter) adds another parameter to this template


 * POM::TemplateParameter represents a single parameter in a template. (This class might not be necessary.)


 * POM::PageDefinition represents a page definition similar or the same as form definition you have right now that defines the sequence of templates and fields, and their properties (and maybe more things in the future), but not the form appearance


 * POM::TemplateDefinition represents a template definition within a page definition


 * POM::FieldDefinition represents a field definition (letting the user input a parameter), 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 $new_favorite = POM::Template; my $fav_url = POM::TemplateParameter('url', 'http://www.google.com'); my $fav_title = POM::TemplateParameter('title', 'Google'); $new_favorite->append($fav_url); $new_favorite->append($fav_title); $favorites->append($new_favorite);

$favorites[5]->delete;

Setting template parameter value
$favorites->setParameter('firstname', 'Alex'); same as: $favorites[0]->setParameter('firstname', 'Alex');