AutoTemplatePlugin

Automatically sets VIEW_TEMPLATE, EDIT_TEMPLATE and PRINT_TEMPLATE

Description

This plugin sets the VIEW_TEMPLATE, EDIT_TEMPLATE and PRINT_TEMPLATE variables according to a corresponding form or rule. For example, when you attach a new form to a topic, this plugin will enable the corresponding view/edit template automatically. This comes in very handy for applications where users create new topics without the help of a topic creator wizard, e.g. creating a new topic for a yet non-existing WikiWord. Together with the appropriate application settings, this plugin will then assure that the data the user enters is handled appropriately during view and edit.

Another use case is to apply a VIEW_TEMPLATE to a set of topics whose name matches a given pattern rule.

There are three base strategies on how the name of the template is derived:

1. exist
2. section
3. rules
4. type

These can be combined in a priorized list defaulting to rules, exist, type. This will try each strategy in the given order until a matching view template is found.

Note: this is a fork of the Foswiki:Extensions.AutoViewTemplatePlugin by Oliver Krüger. The difference between both is that AutoTemplatePlugin adds a rule-based strategy to derive VIEW_ and EDIT_TEMPLATEs as well as replacing the fixed selection which strategy to use with a priority of modes (see below).

If you decide to install AutoTemplatePlugin then please disable the AutoViewTemplatePlugin. Do not use both in parallel.

Mode "exist"

A topic that has a MyForm DataForm attached to it, will be displayed using the view template MyView and editted using the MyEdit if they exist. The template name is derived by stripping off the suffix ...Form from the form name and appending ...View. The Wiki engine will then use the template name MyView to search for the correct template along the template search path, for example using a topic MyView.

Examples:

You have a form called PurchaseRequestForm. The plugin will now search for PurchaseRequestViewTemplate, and PurchaseRequestEditTemplate.

Mode "type"

This is in effect an extended version of the "exist" rule with the difference that it uses the TopicType formfield of a DataForm as standardized by the WikiWorkbench framework. The core rule of this framework is: "All content shall be typed." This means that not only may a wiki topic have a DataForm attached to it. In addition, a certain minimal structure is imposed by at least tree formfields:

• TopicType: the list of types a topic implements
• TopicTitle: the free-form title of a topic (i.e. not constraint by rules for WikiWords)
• Summary: a tagline or sub-title of a topic describing in more detail what the topic is about

For this plugin only the TopicType is of interest to find an appropriate view-, edit or print template for a topic of a certain kind. The content of the TopicType formfield is a list of types ordered from most specific to least specific.

For example the type OrganizationTopic, PartyTopic, CategorizedTopic, WikiTopic is expressing that any topic of that type is finally an OrganizationTopic, which are a more specific kind of PartyTopic, which in turn is able to be categorized (using the ClassificationPlugin), while all topics are at least a WikiTopic. Note that there is only a single DataForm attached to an OrganizationTopic. However it combines all properties of all sub types into one DataForm.

When AutoTemplatePlugin evalutes the type rule by processing the list of TopicTypes left to right looking for an appropriate template. In above example this would check the existence of OrganizationTopicViewTemplate, PartyTopicViewTemplate, CategorizedTopicViewTemplate and WikiTopicViewTemplate. The first on found will be used.

This lets us define a single PartyTopicViewTemplate that is used by OrganizationTopics as well as any other type derived from it, such as a PersonTopic which comes with a TopicType definition PersonTopic, PartyTopic, CategorizedTopic, WikiTopic. The two DataForms share a substantial part of formfields among each other as expressed by the overlapping items in the list of types. Therefore it makes sense to render both topics using a single view template.

Actually in a real-world master data application you would render organizations and persons quite differently listing all contacts of an organization, which does not apply for a person contact. However both may be legal entities and have contact informations.

Mode "section"

A topic with a MyForm will be displayed/editted using the template name stored in the named section viewtemplate, edittemplate, printtemplate. For example given the MyForm form definition topic contains a section viewtemplate whose only content is MyOtherView, then this will be used to view the topic. Likewise, the content of the edittemplate section in MyForm will read to find the edit template.

By default existing values for VIEW_TEMPLATE, EDIT_TEMPLATE and PRINT_TEMPLATE have priority. You can change this behaviour in configure so that the form defined templates have priority.

Examples:

We have a form called PurchaseRequestForm which contains the usual table that defined the form fields.

We want this form to define that the topics are viewed with ViewFormAtTopTemplate and edited with EditPurchaseRequestTemplate.

Below this we place the two sections that defines the templates to be used. Note that you must ommit the ...Template from the template names.

%STARTSECTION{"viewtemplate"}%ViewFormAtTopTemplate%ENDSECTION{"viewtemplate"}%

%STARTSECTION{"edittemplate"}%EditPurchaseRequest%ENDSECTION{"edittemplate"}% 

%STARTSECTION{"printtemplate"}%PrintPurchaseRequest%ENDSECTION{"printtemplate"}% 

Mode "rules"

For both view and edit, a set of rules can be specified in configure or via preference variables where each rule has got the format

   '<pattern>' => '<template name>'

A topic's name will be matched against the regular expression in <pattern> to decide on the template name to be used for the current template. A pattern can either cover the full qualified topic name (web.topic) or just the topic name. Rules are checked against the FQTN first.

Examples:

$Foswiki::cfg{Plugins}{AutoTemplatePlugin}{ViewTemplateRules} = {
  'WebTopicList' => 'WebTopicListView',
  'Tasks\.Item.*' => 'Tasks.ItemView',
  'Item.*' => 'Applications.TaskApp.ItemView',
  'WebSearch.*' => 'SolrSearchView',
};

The same set of rules can be defined by setting VIEW_TEMPLATE_RULES and EDIT_TEMPLATE_RULES preference variables in your SitePreferences or WebPreferences:

   * Set VIEW_TEMPLATE_RULES = 
      WebTopicList => WebTopicListView, 
      Tasks\.Item.* => Tasks.ItemView, 
      Item.* => Applications.TaskApp.ItemView, 
      WebSearch.* => 'SolrSearchView'

This will apply the WebTopicListViewTemplate to the WebTopicList topic in all webs, the SolrSearchViewTemplate to all WebSearch and WebSearchAdvanced topics in all webs and the Tasks.ItemViewTemplate to all Item topics in the Tasks web. Other Item topics will be displayed using the Applications.TaskApp.ItemViewTemplate

Configuration Settings

The following settings can be defined in configure

Setting	Description	Default
{Plugins}{AutoTemplatePlugin}{ViewTemplateRules}	hash of <pattern> > '<template name>' rules to be used for =view
{Plugins}{AutoTemplatePlugin}{EditTemplateRules}	hash of <pattern> > '<template name>' rules to be used for =edit
{Plugins}{AutoTemplatePlugin}{PrintTemplateRules}	hash of <pattern> => '<template name>' rules to be used when printing or exporting to pdf
{Plugins}{AutoTemplatePlugin}{Mode}	A priority list of strategies the plugin uses for defining templates. exist for deriving the template name from the form name section for defining the template in a section of the form definition topic rules for defining the template using the two rule sets below	Default: rules, exist
{Plugins}{AutoTemplatePlugin}{Override}	Form defined templates override VIEW_TEMPLATE and EDIT_TEMPLATE settings	Default: Off

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

None

Change History

12 Nov 2019:	OO-rewrite and performance tweaks
11 Jun 2018:	add type rule to default config
31 May 2018:	wrong template derived under certain conditions
25 May 2018:	added "type" rule
16 Jan 2017:	always at least assign a view template
01 Sep 2016:	do not override the template url param
13 Oct 2015:	bail out early when not in view, edit or print mode
25 Sep 2015:	added support for PRINT_TEMPLATE
31 Aug 2015:	ignore invalid template warning when section not found
17 Jul 2015:	fixed auto-templating of topics being created; fixed auto-templating when the DataForm is changed during edit
03 Nov 2014:	implemented public API to get the auto-assigned template
25 Aug 2011:	added more default views for tools in the System web
05 Apr 2011:	added VIEW_TEMPLATE_RULES, EDIT_TEMPLATE_RULES preference variables
09 Nov 2010:	added defaults to ease templating ChangePassword, SiteChanges, WebIndex
12 Feb 2010:	fixed order rules are matched against the web.topic name
15 Dec 2009:	forked Foswiki:Extensions.AutoViewTemplatePlugin as rule-based feature was rejected. See Foswiki:Development.RulebasedViewTemplates
03 Nov 2009:	added rule-based strategy; made mode a priority list (MD)
06 Oct 2009:	Item2213: Plugin got better documentation. No change in behaviour.
20 Aug 2009:	Item8248: added forward-compatibility for newer Foswikis (MD)
27 Dec 2008:	Item196: moved to Foswiki namespace
15 Nov 2008:	Item196: minor doc changes
11 Jul 2008:	Item5770: try to derive the EDIT_TEMPLATE of a new topic using the WebTopicEditTemplate (MD)
03 Jul 2008:	Item5747: fixed normalizing web part of form names (MD)
13 Nov 2007:	added EDIT_TEMPLATE, speed improvements, docu (MD)
29 Oct 2007:	Item4904: made specification of view template skin agnostic, fixed view templates in subwebs (MD)
04 Sep 2007:	Added build script and installer, minor doc changes
05 Jun 2007:	Initial version