Data & Templates

Page Templates

A page template is the starting point for creating a page in Kestros: it defines the page’s structure and its defaults, including the theme that styles the page, the content inherited from the parent, and the areas where authors can add components. Kestros ships a basic page template you can use directly, or use as the base for your own custom templates.

Template structure

The shared structure a site’s pages inherit, its header, footer, and other inherited regions, lives in the site’s root content, at:

content/src/content/jcr_root/content/sites/{my-site}/.content.xml

The site references its UI Framework through the kes:theme property on its jcr:content node, which is how each page picks up its CSS, JavaScript, and component views. See UI Frameworks & Themes for how themes resolve.

Content areas and inherited content

A template can combine two kinds of region: a content area, a dynamic area where authors add components, and an inherited content area, whose content is defined once upstream and carried into every page that inherits it. Each is a node identified by a unique name and a sling:resourceType:

Default components can be included as child nodes of a content area. In the example below, the <header> node, and all of its children, are inherited by every new page that inherits this structure:

<header jcr:primaryType="nt:unstructured"
        sling:resourceType="kestros/commons/components/inherited-content-area">
  <container jcr:primaryType="nt:unstructured"
             sling:resourceType="/libs/kestros/commons/components/structure/container">
    <content jcr:primaryType="nt:unstructured"
             sling:resourceType="kestros/commons/components/content-area">
      <navigation jcr:primaryType="nt:unstructured"
                  sling:resourceType="/libs/kestros/commons/components/structure/navigation"/>
    </content>
  </container>
</header>

Creating a custom template

Custom templates are authored under apps, at:

application/src/content/jcr_root/apps/{site}/templates

A basic page template ships with the sample sites, for example a {site}-base-page template under apps/{site}/templates/. It inherits the site’s shared structure by default; your custom elements are added as children of the content area. The starting point is a bare jcr:content node:

<jcr:content jcr:primaryType="nt:unstructured"
             sling:resourceType="kestros/commons/components/kestros-base-page"/>

Extend it with your own content areas and default components:

<jcr:content jcr:primaryType="nt:unstructured"
             sling:resourceType="kestros/commons/components/kestros-base-page">
  <main jcr:primaryType="nt:unstructured"
        sling:resourceType="kestros/commons/components/content-area">
    <container jcr:primaryType="nt:unstructured"
               sling:resourceType="/libs/kestros/commons/components/structure/container">
      <heading jcr:primaryType="nt:unstructured"
               sling:resourceType="/libs/kestros/commons/components/content/heading"
               headingText="Welcome to Kestros!" headingType="h1"/>
      <content jcr:primaryType="nt:unstructured"
               sling:resourceType="kestros/commons/components/content-area"/>
    </container>
  </main>
</jcr:content>

Creating a template from the Page Edit view

A custom template can also be created directly from the Page Edit view. When editing a page, the editor ribbon offers a Create Template action that builds a new template from the current page state, with all of its components included as defaults.

The Create Template dialog collects:

The resource name the template is stored under is generated automatically from the title (lower-cased, with non-alphanumeric characters replaced by hyphens).

Once saved, the template appears in the list of templates to choose from when creating a new page for the site.

Creating a page type

The Base Page provides default functionality such as including the Header, Footer, and Main content area, along with the global CSS and JavaScript delivered through the UI Framework. To extend or override it, create a new folder under:

/apps/{site}/components/pages/{page-type-name}

Add a .content.xml that defines the new page type. It is a kes:ComponentType that sets the base page as its sling:resourceSuperType:

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
          xmlns:kes="http://kestros.io/kes/1.0"
          jcr:primaryType="kes:ComponentType"
          sling:resourceSuperType="kestros/commons/components/kestros-base-page"
          jcr:title="Article Page"
          componentGroup="Beta Components"
/>

From here, build out the new page type with a custom layout: it renders all of the static HTML, HTL scripts, and referenced resources it defines, on top of the base page it extends. A page type is a component type like any other, so the same view mechanics apply. See Components and Component Views for how resource-super-type inheritance and views resolve.

Template views

As with components, give each custom page type a Common view: the default HTML used when the type renders. A single component type can have any number of views, letting authors pick between variations of the same general layout, for example minor differences in the same page shape, or static content that is not authorable. Rather than editing components and layouts repeatedly, build those variations as views.

At the most basic level a view should include the content area, so authors can add components to the page. The script to include a content area on a page template is:

<sly data-sly-resource="${'main' @ resourceType='kestros/commons/components/content-area'}"/>