Site Configuration and Inheritance

From bemoko developer wiki

(Redirected from Site)
Jump to: navigation, search

Site Configuration

Site configuration is defined in the site-config.xml file in the root directory of the site. If none is provided then the site will be configured with the "default" site as the parent. In most cases all sites extend from the "default" site - this site contains standard configuration which is most commonly needed, although you are free to override or all of the site configuration as needed.

Inheritance

All sites can inherit from one or more parent sites. This means that the behaviour - i.e. site configuration, such as content plugins and UI configuration, or UI resources is taken from these parent sites.

For example 

<site parent="components">
   ...
</site>

indicates that the site should inherit all the behaviour from the "components" site, whereas : 

<site parent="components:cms">
   ...
</site>

indicates that the site should inherit all the behaviour from the "components" site and then "cms" site. For configuration or resources of the same name the one found first in the site fallback is applied.

Site Configuration Elements

Plugins

Plugins can be configured in two ways. (1) Available to all intents by configuring the content-sources element  : 

<site>
  <content-sources>
    <source name="manager" plugin="authentication.ManagerPlugin" 
      scope="session" expr="user.identity.inGroup('admin')"/>
    <source name="initialiser" plugin="authentication.InitialiserPlugin" 
      scope="site"/>
    <source name="breadcrumbs" plugin="Breadcrumb" scope="session" 
        expr="intent.name != null and intent.name ne 'r' and intent.name ne 't'">
      <param name="home_intent">i</param>
      <param name="navigation_yaml">data/navigation.yaml</param>
    </source>
    <source name="twitter" plugin="Twitter" scope="site">
      <param name="twitter_name">bemoko</param>
    </source>
  </content-sources>
</site>

and on (2) a per intent basis: 

  <intent name="cache" type="template" view="index.html">
    <param name="page">cache/index.html</param>
    <source name="cache" plugin="cache.CacheManagerPlugin" 
      scope="site" expr="user.identity.inGroup('admin')"/>
  </intent>

Source xml doc

element attribute values description
source name [a-zA-Z]+ Name for the plugin. This as the plugin is referred to in a template
  plugin [a-zA-Z\.]+ Plugin class name. This as the name of the plugin class without the extension, for example if you have a plugin called MyPlugin.groovy defined in the plugins folder, then you would refer to it as MyPlugin. If you have a plugin called MyPlugin.groovy defined in the plugins/mypackage folder then you would refer to it here as mypackage.MyPlugin. If you do not specify a name then the plugin attribute value is the name by which the plugin is made available in the templates.
  scope request (default), session or site Scope that the plugin is stored at. Request scoped plugins are created new for each request, session scoped plugins are created once and reused for a given users sessions, site scoped plugins are created once for the site and reused for all users
  expr expression When the expression is true the plugin will be available for the given request

the source element can include multiple nested param elements which are passed into the initialise method of the plugin - see Plugin liefcycle

Param xml doc

element attribute values description
param name [a-zA-Z]+ Name of the parameter. The value of the parameter is taken from the content of the param element

Header Configuration

You can configure which HTTP headers should be sent in the response ... 

<site>
  <headers>
    <header name="Cache-Control" value="no-transform"/>
    <header name="Cache-Control" value="no-cache" expr="!(uri.endsWith('.css') || uri.endsWith('.gif') || uri.endsWith('.png') || uri.endsWith('.jpg') || uri.endsWith('.ico') || uri.startsWith('/lib'))"/>
    <header name="Cache-Control" value="max-age=3600" expr="uri.endsWith('.css') || uri.endsWith('.gif') || uri.endsWith('.png') || uri.endsWith('.jpg') || uri.endsWith('.ico') || uri.startsWith('/lib')"/>
  </headers>
</site>

Header xml doc

element attribute values description
header name [a-zA-Z]+ Name of the HTTP header to be sent in the response
  value [a-zA-Z]+ Value of the HTTP header to be sent in the response
  expr expression The header will be sent when the expression is true (or if the expression is not set)

Intent Configuration

<site>
  <intents>
    <intent name="i" type="template" view="template-home.html">
      <param name="page">homepage.html</param>
    </intent>
    <intent name="artists" type="template" view="template-pages.html">
      <param name="page">artists.html</param>
      <source name="datetime" plugin="datetime" scope="site"/>
    </intent>
  </intents>
</site>

Intent xml doc

element attribute values description
intent name [a-z]+ Name of the intent as referenced to in the URI context, e.g. http://myhost/site/intent
  type template (default), application or renderer. The type of the template. Template indicates that the view is text file with template instructions in, e.g. Freemarker. Application indicates that the view is an application, e.g. a PHP page. Renderer indicates that the intent is delivered by a render plugin which gives you full control from within a plugin to deliver response content.
  view file name The name of file to use to render the intent whether it be a template or an application, e.g. index.html

The intent element can be defined with multiple nested param elements which define the intent parameters which are available to both the template rendering, e.g. intent.myparam and the execute method of the plugins enabled for this intent.

Param xml doc

element attribute values description
param name [a-zA-Z]+ Name of the parameter. The value of the parameter is taken from the content of the param element

UI Configuration

The UI segmentations for the site are configured with the uigroup element, e.g. 

<site>
  <uigroup default="unknown" index="index.html">
    <ui name="pc" expr="!device.isMobile" fallback="320" />
    <ui name="320" expr="device.displayWidth ge 320" fallback="240" />
    <ui name="240" expr="device.displayWidth  ge 240" fallback="208" />
    <ui name="208" expr="device.displayWidth ge 208" fallback="176" />
    <ui name="176" expr="device.displayWidth ge 176" fallback="128" />
    <ui name="128" expr="device.displayWidth lt 176" fallback="root" />
  </uigroup>
</site>

UI xml doc

element attribute values description
source name [a-z]+ Name of the UI
  expr expression When the expression is true the UI (or a child of this UI) will be enabled
  fallback [a-z]+ Name of a UI that this UI inherits from

See UI Configuration for more information.

Site Level Configuration

Character Encoding

The character encoding for the site is configured with the characterEncoding attribute on the site element, e.g. 

<site characterEncoding="utf-8">
  ...
</site>
Retrieved from "http://bemoko.com/wiki/Site_Configuration_and_Inheritance"