Template Providers

Create a Template Provider

Template providers allow to create wiki pages using an existing template. To create a page template provider, click the DrawerMenuIcon.png button in the upper right corner which will open the drawer menu, then on "Administer Wiki". 


In the wiki preferences page, click on "Content" in the accordion menu to the left, then on "Page Templates".


Under "Available Template Providers" you will notice 8 entries: 

  • Blog Post Template Provider allowing to create a blog article
  • Space Dashboard Template Provider - allows creating a dashboard page
  • Contributors Template Provider - allows to create a Contributor page as part of the Help Center Application
  • Movies Template Provider - allows to create a Movie page as part of the Help Center Application
  • 4 page template providers corresponding to the 4 new templates included by default in XWiki Standard 8.2.x that are detailed in the page creation documentation:
    • Simple Page
    • Article Page
    • Encyclopedia Page
    • Meeting Report

Next, fill in the template provider title and the location in the page hierarchy where the new page will be created.


Additionally, you may check the "Terminal Page" option which means that the template provider page won't have any child pages. Note that this option is available only for advanced users.

To set the page location, click the blue editing pen icon, which will load 2 more fields:

  • Parent - the parent of the new page; when choosing the page name, the suggest feature will display the list of all the occurrences, so that you can select from them. To collapse the suggestion results, just click on "hide suggestions". As soon as you select a parent, the breadcrumb is updated in order to reflect the location of the page in the reference hierarchy.
By leaving this field empty, you will create a top-level page which is the equivalent of an old space home page. 
  • Name - the name of the page i.e. the string appearing in the URL.


Another way of selecting a location is to click on the blue hierarchy icon and select a parent from the document tree or to search it using the integrated finder.


After clicking on "Create", the template provider document will automatically open in "Inline" mode. The "Provider Name" field is the one displayed in the list of available template providers from the "Templates" section in the wiki administration.

The "Template Name" input represents the name displayed in the list of available templates when the create page form is launched. Its value can also be a translation key in order to allow internationalization of the template name.

Provided you have checked the "Terminal Page" option in the previous screen, you will see a "Terminal Page" drop-down referring to whether or not to create terminal documents when using the current template provider. By default, the selected option is "Yes" but you can still override it by manually unchecking it so that the page is created as nested instead.

Given that for regular users the "Terminal Page" checkbox is not displayed in the previous step (thus, it is selected by default), the page created using the current template provider will keep the same preference i.e. it will be a terminal page.


You can add a Font Awesome icon and a description in order to display additional information in the list of template providers. The full list of supported icons is available in the page IconThemes.FontAwesome.

The "Action on Create" option allows you to decide whether the new document will be saved or not before being opened for edition and the possible choices are "Edit" and "Save and Edit". 

Location Restrictions

You may enforce visibility restrictions i.e. decide on which locations the template provider will be visible to an user who wishes to create a new page. To so so, click the + icon below "List of locations where the template must be available" and select them from the page tree - in case you don't specify any location, the template will be available from any wiki page. 

Template providers that are restricted to certain locations are also available from the children of those pages.

The second type of restrictions refer to the list of locations where the template provider allows the creation of pages in order to control where users are allowed to create various types of content. A provider with no creation restrictions can be used to create pages anywhere in the wiki.

Another implicit effect of such a restriction is the automatic fill of the destination location in the "Create Page" form. This means that when you switch template types in the creation form, the parent location field will be pre-filled with one of the template restrictions, provided the newly selected template has a creation restriction. The restrictions will used in the "Create Page" form to validate the "Location" -> "Parent" field.


On the other hand, if in a template provider has the "Creation Restrictions as Suggestions" option is checked, then the creation restrictions will not be enforced and will be used simply for identifying the default parent location that is pre-filled in the creation screen. The user will still be able to change the parent and choose an option outside the restrictions.  


To add a creation restriction, click on the + icon below "Creation restrictions" and select one or multiple locations from the page tree. 


When a template has a creation restriction matching the current location or the parent of the current location, you will notice that, in the page creation screen, the page type "promotes" a certain template meaning that it is automatically selected. For instance, when trying to create a page from the Blog home page or any Blog post, you will see that the "Blog Post Template" is displayed first in the list and that it is pre-selected.


In case multiple such providers are detected for the current location from which the user is trying to create a new page, all of them will be pushed to the top of the list. However, they will be sorted based on the specificity of the matching creation restriction, so that the restriction that matches the current location best is listed first and it is the pre-selected one.

After clicking on "Save & View" to complete the process,


click on "Go back to the Wiki Administration".


Template Hierarchies

Supposing the document specified by the template provider - the page "Ideas.IdeasTemplate" - we created earlier is a non-terminal page and that it has 3 child documents:

  • "Idea Template Admins"
  • "Idea Template Managers"
  • "Idea Template QA"


This structure is named a "template document hierarchy" and whenever you create a new document using the "Idea Proposal" template, the entire hierarchy will be copied to the location of that new page. 

So, if you choose to create a new page using "Idea Proposal",


the first time you hit "Save & View" you will notice a message at the bottom of the form with a percentage representing the progress of the template hierarchy copy process.


Related Pages

Trying to decide between Cloud and On Premise? See the comparison on the XWiki Help Center.

Search this space