Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
Template availability defines which templates editors can use to create pages and components. Available page templates are displayed in a dropdown list in the Pages app. Available component templates are listed in the page editor when adding a component inside an area.
Example: The template dropdown in the Pages app shows available templates
Page template availability is controlled on several levels:
visible
property in a page definition.availability
node in a site definitiontype
The template availability can be set on page template definition with the visible
property.
| optional , default is
When |
The availability
node in a site definition allows you to make templates available per site. This means, an editor working on site X can only choose templates that are available on site X. As a use case, a small campaign site may only have one available template whereas your main site has many templates.
Use the Site app to configure template availability by site.
You need the Site module in order to create a site definition. The Site module is not always included, such as when you create your own bundle based on the empty webapp. Add a dependency to the Site module in your webapp pom file. The Site module provides the same availability definitions that were previously in the Standard Templating Kit module.
You may define page templates explicitly under the availability/templates
node in your site definition. Add the child nodes as shown in the example below, where the home
and standard
templates are made available on the travel
site:
Node name | Value |
---|---|
travel | |
templates | |
availability | |
templates | |
home | |
id | travel-demo:pages/home |
standard | |
id | travel-demo:pages/standard |
Properties:
id | required ID of the page definition in The ID has two parts separated by a colon:
You can reference templates from any module. |
You can make all templates available by adding the enableAll
property to the availability
node in your site definition and set the property to true
:
Node name | Value |
---|---|
travel | |
templates | |
availability | |
templates | |
enableAll | true |
RenderType
By adding the enableAllWithRenderType
node to the availability
node, you can make templates available by RenderType
. In the example below, the templates rendered by freemarker
and jsp
are made available on the travel
site:
Node name | Value |
---|---|
travel | |
templates | |
availability | |
templates | |
enableAllWithRenderType | |
freemarker | freemarker |
jsp | jsp |
Options 1 and 3 can be combined.
Configure template availability under the availability
node in the site definition:
/modules/<my-module>/config/<site-definition>/templates/availability
when you want to store the site definition in your own module./modules/site/config/site/templates/availability
when you want to store the site definition in the Site module./modules/multisite/config/sites/<site-definition>/templates/availability
when you have multiple sites and use the Multisite module.The roles
node in a site definition allows you to make templates available to users who have a specific role. The roles themselves are managed in the Security app. Reference them by name from the site definition.
Use the Site app to configure template availability by role.
Example: Only users in the superuser
role have a permission to create home
pages. Users with superuser
or editor
roles can create pages based on the standard
template.
Node name | Value |
---|---|
travel | |
templates | |
availability | |
templates | |
home | |
roles | |
superuser | superuser |
id | travel-demo:pages/home |
standard | |
roles | |
superuser | superuser |
editor | editor |
id | travel-demo:pages/standard |
Properties:
| optional |
| optional The property name is arbitrary but the value must match a valid role as configured in the Security app. |
type
The optional type
property in a page definition allows you to make templates available per page type. Common page types are home, section and article. Types allow you to control where in the page tree a template can be used. If a template type is not allowed in a given place in the tree, it will not be available to editors.
To limit template availability by type you need to:
type
property to your page definitions.type
propertyExample: Type home
in a page definition
renderType: freemarker templateScript: /my-module/templates/pages/home.ftl dialog: my-module:pages/homePageProperties # areas: visible: true type: home class: com.example.templates.CustomTemplateDefinition modelClass: com.example.templates.HomePageModel
Node name | Value |
---|---|
templates | |
pages | |
home | |
areas | |
<area definitions> | |
class | com.example.templates.CustomTemplateDefinition |
dialog | my-module:pages/homePageProperties |
modelClass | com.example.templates.HomePageModel |
renderType | freemarker |
templateScript | /my-module/templates/pages/home.ftl |
type | home |
visible | true |
Properties:
type | optional , default is
Most web pages fall into these types:
|
Implement and configure your own TemplateAvailability class that reacts to the defined types. Write your own implementation of the info.magnolia.rendering.template.TemplateAvailability
interface (source). You may want to subclass info.magnolia.module.site.templates.ConfiguredSiteTemplateAvailability
(source).
You can find inspiration in info.magnolia.module.templatingkit.sites.TemplateAvailability#isAvailable
(source). Templates of type home
can only be used on the site root page. Templates of type content
can only be used on a page that resides under a page whose template belongs to types section
, feature
or functional
.
Example: Configuring a TemplateAvailability class in the Site app.
Node name | Value |
---|---|
templates | |
availability | |
class | com.example.myModule.site.CustomTemplateAvailability |
Standard Templating Kit legacy
The type
property originates from the Standard Templating Kit module where it was used to enforce a page hierarchy.
STKPage
still has a category
property which you can use in STK templates. If you do not use STK, use the type
property which is defined in
TemplateDefinition
in Magnolia 5.4.
The add-availability
and create-component
commands in the Magnolia CLI allow light developers to define component availability in a page template.
The availability of a component is defined per area in an Area definition (and an area definition is always part of page template definition).
You can restrict access to components made available in an area template definition to users assigned a specific role.
In this example component textImage
can be used by any editor, but only users assigned the superuser
role in the Security app can create a HTML
component. See Roles for more.
areas: myArea: availableComponents: textImage: id: my-module:components/textImage html: id: my-module:components/HTML roles: - superuser # could also be written as # roles: [superuser]
Node name | Value |
---|---|
article | |
areas | |
myArea | |
availableComponents | |
textImage | |
id | my-module:components/textImage |
html | |
roles | |
superuser | superuser |
id | my-module:components/HTML |
Where id
is the Component definition ID in <module name>:<path to component definition>
format. See Area properties for more.
You can restrict the number of components that render in a list
area by adding a maxComponents
property. Once the limit is reached the New Component box is replaced with a Maximum Components Reached notification preventing editors from adding additional components.
areas: myArea: availableComponents: maxComponents: 5 renderType: freemarker type: list
Node name | Value |
---|---|
areas | |
myArea | |
availableComponents | |
maxComponents | 5 |
renderType | freemarker |
type | list |
You can restrict the actions that editors can take on a component in the component definition using the deletable
, writable
, moveable
and personalizable
(EE Pro) properties. By default, all components can be deleted, edited, moved, and personalized but you can change this behavior by setting these properties to false
.
renderType: freemarker templateScript: /my-module/components/html.ftl dialog: my-module:components/html deletable: false writable: false moveable: false personalizable: false
Node name | Value |
---|---|
html | |
deletable | false |
writable | false |
moveable | false |
personalizable | false |
dialog | my-module:components/html |
renderType | freemarker |
templateScript | /my-module/components/html.ftl |
You can define which roles can edit, move, delete, and in Magnolia EE Pro also personalize components in an area definition .
areas: myArea: availableComponents: myComponent: id: my-module:components/myComponent permissions: write: roles: [editors, superuser] move: roles: [senior-editor, superuser] delete: roles: [editors, superuser] personalize: roles: [senior-editor, superuser]
Node name | Value |
---|---|
areas | |
myArea | |
availableComponents | |
myComponent | |
permissions | |
write | |
roles | |
editors | editors |
superuser | superuser |
move | |
roles | |
senior-editors | senior-editors |
superuser | superuser |
delete | |
senior-editors | senior-editors |
superuser | superuser |
personalize | |
roles | |
senior-editors | senior-editors |
superuser | superuser |
id | my-module:components/myComponent |
Nodes and properties:
permissions | optional Required parent item that contains the action restrictions. |
| optional Action to which the restriction applies. ( |
| required Note that roles must be added as list in the YAML file. (See YAML-Lists). |
| required Identifies the role. The name of the attribute is arbitrary but the value must match an existing role |
3 Comments
Christian Ringele
regarding the the section "Availability by type":
This section leads to the assumption, that one can use template types (content, section, home) OTB for the templates availability behavior.
This was implemented in the former STK's templatesAvailability, but is not anymore in any of the OTB provided implementations of the {{TemplateAvailability}} interface:
Non of these implementations are checking the template type in their
isAvialable
method.info.magnolia.module.site.templates.ConfiguredSiteTemplateAvailability.isAvailable(Node, TemplateDefinition)
info.magnolia.module.site.templates.SiteAwareTemplateAvailability.isAvailable(Node, TemplateDefinition)
info.magnolia.rendering.template.configured.DefaultTemplateAvailability
This means, that the customer must implement their own implementation of the {{TemplateAvailability}} interface.
Christoph Meier
I disagree with your 1st paragraph. We state: "Implement a custom TemplateAvailability class that reacts to the types."
But we may have to make this statement more explicit.
We know that there is no out-of-the-box replacement for the former STK's templatesAvailability. There are different opinions whether the product should deliver this or not. (I'm not sure whether there is a ticket for it.)
Rajeev Singh
Hi,
For "You can find inspiration in
info.magnolia.module.templatingkit.sites.TemplateAvailability#isAvailable
(source)" Can yopu provide some inspirational source without using STKPage (meaning without STK dependency ) ?Secondly, for this
info.magnolia.rendering.template.TemplateAvailability
interface (source). seems like link is broken for source. or may be I am not authorized ...basically, what is the alternative for STKPage