This documentation is still in progress. We are working hard to update all our screenshots to the new Magnolia 6 style. Please bear with us.

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

The SiteMesh module integrates the SiteMesh 3 decoration and Web application integration frameworkwith Magnolia. If you intend to use SiteMesh only as the mechanism  for dynamic page caching you can skip this page after its installation and continue with Advanced Dynamic Page Caching.


SiteMesh intercepts requests to any static or dynamically generated HTML page requested through the web-server, processes the content and then merges it with one or more decorators to build the final result." – SiteMesh 3

Installing

Maven is the easiest way to install the module. Add the following to your bundle:

<dependency>
  <groupId>info.magnolia.sitemesh</groupId>
  <artifactId>magnolia-module-sitemesh</artifactId>
  <version>1.1.2</version>
</dependency>

Pre-built jars are also available for download. See Installing a module for help.

Uninstalling

  1. Remove the /server/filters/sitemesh node.
  2. Remove the /server/rendering/engine/listeners/sitemesh node.
  3. Remove the /modules/sitemesh node and its subnodes
  4. Shut down Magnolia, remove the SiteMesh module JAR (magnolia-module-sitemesh.jar) from WEB-INF/lib and start up Magnolia again.

Filter

SiteMesh filter processes by default only text/html but can be configured to process any text resources such as css or javascript:

 sitemesh


      enabled

true

      class

info.magnolia.cms.filters.FilterDecorator

      bypasses


          nonHtml


              enabled

true

              class

info.magnolia.voting.voters.ResponseContentTypeVoter

              not

true

              allowed


                  html

text/html


Decorators

The decorator contains the common layout and style that should be applied to the pages in the web application". – Getting Started with SiteMesh 3

If you have samples and demo/project installed, you can find SiteMesh sample under /demo-features/modules/sitemesh-sample.html and its decorator under /demo-features/modules/sitemesh-sample/decorator.html. You can configure more that one decorator per path (and of course use regular expression for path). You can find the templates under templates:/sitemesh-sample.

Decorator selector chooses the decorators for pages. MetaTagBasedDecoratorSelector is used by default.

 sitemesh


      enabled

true

      class

info.magnolia.cms.filters.FilterDecorator

      decoratedFilter


          class

info.magnolia.sitemesh.config.MagnoliaConfigurableSiteMeshFilter

          contentProcessor


          decoratorSelector


              class

org.sitemesh.config.MetaTagBasedDecoratorSelector

          pathToDecoratorMapping


              sample


                  path

/demo-features/modules/sitemesh-sample.html

                  decorators


                      0

/demo-features/modules/sitemesh-sample/decorator.html


Content processor

Processes the text content tag by tag. You can configure sets of rules under tagRuleBundles. You can use the bundles provided by SiteMesh 3.0.0. Just use info.magnolia.sitemesh.content.TagRuleBundleWrapper as class, create node wrapped and set the bundle class as the property class:

 sitemesh


      enabled

true

      class

info.magnolia.cms.filters.FilterDecorator

      decoratedFilter


          class

info.magnolia.sitemesh.config.MagnoliaConfigurableSiteMeshFilter

          contentProcessor


              class

info.magnolia.sitemesh.content.MagnoliaContentProcessor

              tagRuleBundles


                  magnolia


                  coreHtmlTagRuleBundle


                      class

info.magnolia.sitemesh.content.TagRuleBundleWrapper

                      wrapped


                          class

org.sitemesh.content.tagrules.html.CoreHtmlTagRuleBundle

                  decoratorTagRuleBundle



Tag rule bundles

Because the bundles provided by SiteMesh 3 are fixed sets of rules, Magnolia offers you also configurable info.magnolia.sitemesh.content.MagnoliaTagRuleBundle. You can dynamically add info.magnolia.sitemesh.content.MagnoliaRules to this bundle:

 sitemesh


      enabled

true

      class

info.magnolia.cms.filters.FilterDecorator

      decoratedFilter


          class

info.magnolia.sitemesh.config.MagnoliaConfigurableSiteMeshFilter

          contentProcessor


              class

info.magnolia.sitemesh.content.MagnoliaContentProcessor

              tagRuleBundles


                  magnolia


                      class

info.magnolia.sitemesh.content.MagnoliaTagRuleBundle

                      rules


                          InjectUriRule


                          InjectUrlRule


                          injectAdminCentralButtonRule


(warning) Magnolia 5.4.6+ / Sitemesh 1.0.3+. You can configure the baseURL in the InjectUriRule node. 


Set /server/filters/sitemesh/decoratedFilter/contentProcessor/tagRuleBundles/magnolia/rules/InjectUriRule/tag/baseUrl to http://localhost:8080${contextPath}, for example. 

  • Request:  https://demo.magnolia-cms.com/ .
  • Fragment request:  https://localhost:8080/magnoliaPublic~mgnlArea=main~ .

(warning) Site-specific configurations are not taken into account.

If baseURL is not set, the base URL of the current request is used:

  • Request:  https://demo.magnolia-cms.com/.
  • Fragment request:  https://demopublic.magnolia-cms.com/~mgnlArea=main~ .

Rules & Tags 

Every info.magnolia.sitemesh.content.MagnoliaRule holds tag. info.magnolia.sitemesh.content.AbstractTag processes a html tag. You can implement for example  a tag which replaces all occurrences of <b> with <s>. Set  includeInContent=true on rule if you don't want to replace the original tag but only append new content after it. Add content node named tagTypes to a tag to tell which  tag types  you want to process. All types (open, close, ...) will be processed if no tagTypes node will be added.

 sitemesh


      enabled

true

      class

info.magnolia.cms.filters.FilterDecorator

      decoratedFilter


          class

info.magnolia.sitemesh.config.MagnoliaConfigurableSiteMeshFilter

          contentProcessor


              class

info.magnolia.sitemesh.content.MagnoliaContentProcessor

              tagRuleBundles


                  magnolia


                      class

info.magnolia.sitemesh.content.MagnoliaTagRuleBundle

                      rules


                          InjectUriRule


                              enabled

true

                              class

info.magnolia.sitemesh.content.MagnoliaRule

                              tag


                                  class

info.magnolia.sitemesh.content.inject.InjectUriTag

                                  name

mgnl:injecturi

                                  forceUriRequest

false

                                  tagTypes


                                      open

open



Out of the box rules
classdescriptionconfigurable fields (default values)
info.magnolia.sitemesh.content.inject.InjectTagTag for any text injection.contentToInject (empty string)
info.magnolia.sitemesh.content.inject.sample.InjectAdmincentralButtonTagTag injects admincentral button to navigate to admincentral when accessing pages outside of admincentral.contentToInject (empty string)
info.magnolia.sitemesh.content.inject.InjectUrlTag

Tag for injection of content retrieved by URL specified as argument target of this tag.

<mgnl:includeurl target=http://somePage.html />

readTimeout (600000)
connectTimeout (10000)
bufferSize (4096)
info.magnolia.sitemesh.content.inject.InjectUriTag

Tag for injection of content retrieved by URI (that means a URI which points to the same webapp) specified as argument target of this tag. The current original request is used to create URL. Other arguments are set as request headers such as X-Magnolia-Fragment  header which allows you to set time to live of this dynamic fragment.

  <mgnl:injecturi target="/demo-project/about~mgnlArea=branding~" X-Magnolia-Fragment=" ttlValue =0 , CacheKeyGenerator=, " />

readTimeout (600000)
connectTimeout (10000)
bufferSize (4096)

Fragment Injection Listener


 rendering


      engine


          listeners


              sitemesh


                  enabled

true

                  class

info.magnolia.module.advancedcache.rendering.FragmentInjectionListener

                  skipRendering

false

                  targetPath

RELATIVE_TO_CONTEXT_ROOT

  before
<mgnl:injecturi target="${targetPath}" X-Magnolia-Cache="ttlValue=${ttlValue},CacheKeyGenerator=${CacheKeyGenerator},">

                  after

</mgnl:injecturi>


Samples

The SiteMesh sample contains two preconfigured dynamic components for Standard Templating Kit:

  • /modules/multisite/config/sites/default/templates/prototype/areas/branding/areas/metaNavigation/fragmentDefinition
  • /modules/commenting/templates/components/comments/fragmentDefinition

Set /modules/multisite/config/sites/default/templates/prototype/areas/branding/areas/metaNavigation/fragmentDefinition=true, disable SiteMesh filter (/server/filters/sitemesh@enabled=false) and open a demo-project page to see the result of the sitemesh fragment injection listener: 


...a static page content before the dynamic component...
<mgnl:injecturi target="/demo-project/about~mgnlArea=branding,metaNavigation~" X-Magnolia-Cache="ttlValue=-1,CacheKeyGenerator=info.magnolia.sitemesh.samples.MetaNavigationCacheKeyGenerator,">
an dynamic meta navigation area
</mgnl:injecturi>
...a static page content after the dynamic component...


External fragment

There is the trivial sample for external fragment inclusion:

  • component: config:modules/sitemesh/templates/components/externalFragment
  • dialog: config:modules/sitemesh/dialogs/externalFragment
  • availability: config:modules/standard-templating-kit/templates/pages/stkSection/areas/main/areas/opener/availableComponents/externalFragment
  • template: templates:sitemesh-sample/externalFragment

Go to website/demo-project/about, delete the opener teaser component and add External Fragment instead. Add URL of a page which you want to render.