Page tree
Skip to end of metadata
Go to start of metadata

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

Page template availability is controlled on several levels:

  • visible property in a page definition.
  • availability node in a site definition
    • to configure the availability per site 
    • configuring role based availability per template (per site).
    • Using page template definition property type 

Availability by page definition

The template availability can be set on page template definition with the visible property.

visible

optional , default is true

true makes the template available to editors.

When visible is set to false, the template is not available. However, the opposite is not always true. There are more ways to control page template availability.

Availability by site

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.

Option 1: Define page templates explicitly

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 nameValue

 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 <module name>:<path to page definition> format.

The ID has two parts separated by a colon:

  • <module-name> : Name of the module which contains the page definition.
  • <path>: Relative path to the page definition inside pages root item. For example, the page ID my-module:pages/home either points to a YAML file $magnolia.resources.dir/my-module/templates/pages/home.yaml or to a JCR node /modules/my-module/templates/pages/home in the config workspace.

You can reference templates from any module.

Option 2: Make all templates available

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 nameValue

 travel

 

 templates

 

 availability

 

  templates

 

 enableAll

true

Option 3: Make templates available by 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 nameValue

 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:

  • Community Edition and Enterprise Edition Standard:
    • /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.
  • Enterprise Edition Pro:
    • /modules/multisite/config/sites/<site-definition>/templates/availability when you have multiple sites and use the Multisite module.

Availability by role

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 nameValue

 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:

roles

optional

<role name>

optional

The property name is arbitrary but the value must match a valid role as configured in the Security app.

Availability by 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:

  1. Add a type property to your page definitions.
  2. Implement a custom TemplateAvailability class that reacts to the types.
  3. Configure the custom TemplateAvailability class in the site definition. 

Adding a type property

Example: Type home in a page definition

example/templates/pages/home.yaml
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 nameValue

 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 content

(warning) You have to define the template types yourself. Magnolia does not provide ready-made types.

Most web pages fall into these types:

  • home: Home page. Root of the site.
  • section: Sections that organize the site.
  • content: Core content pages.
  • feature: Special templates that collect or aggregate content.
  • functional: Templates that perform actions such as redirect rather than render content.

Implementing a template availability class

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 sectionfeature or functional

Configuring a template availability class

Example: Configuring a TemplateAvailability class in the Site app.

Node nameValue

 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.

Component template availability

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).

Restricting component availability in an area template

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 nameValue

 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.

Restricting the number of components in an area template

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 nameValue

 areas

 

 myArea

 

 availableComponents

 

 maxComponents

5

 renderType

freemarker

 type

list

Restricting component actions in a component template

You can restrict the actions that editors can take on a component in the component definition using the deletable, writable, and moveable properties, and in Magnolia EE Pro also the personalizable property. By default, all components can be deleted, edited, moved, and personalized but you can change this behavior by setting these properties to false

deletable: false
writable: false
moveable: false
personalizable: false
dialog: my-module:components/html
renderType: freemarker
templateScript: /my-module/components/html.ftl
Node nameValue

 html

 

 deletable

false

 writable

false

 moveable

false

 personalizable

false

 dialog

my-module:components/html

 renderType

freemarker

 templateScript

/my-module/components/html.ftl

Restricting component actions in an area template

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 nameValue

 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.

<write|move|delete|personalize>

optional

Action to which the restriction applies. ((warning) personalize is available only in Magnolia 5.4.9+ EE Pro)

roles

required

Note that roles must be added as list in the YAML file. (See YAML-Lists).

<roleName>

required

identifies the role. The name of the attribute is arbitrary but the value must match an existing role