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:
-
exist
-
section
-
rules
-
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}{Override} |
Form defined templates override VIEW_TEMPLATE and EDIT_TEMPLATE settings |
Default: Off |
{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}{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 |
|
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
27 Apr 2022: |
backwards compatibility setting the actual template |
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 |