OpenWGA 7.7 - Guide for OpenWGA Content Manager


Content management modules

There are situations where fixed content item structure in content types is too restrictive for the author. For this reason the concept of "content management modules" has been introduced in OpenWGA Content Manager 2.3 (part of OpenWGA 5.3). CM Modules, also often referred as simply "content modules", are ready to use "intelligent page fragments" the author can add to a page in a structure suitable for exactly the page content he is working on.

Using content modules in custom OpenWGA designs

To use content modules in your site design you have to do the following:

  1. In your HTML-Head section (typically in your outer layout) you have to include the module "htmlhead-includes" from the cm-plugin.
  2. Inside the TML that renders your content type add an include of "modules:render" from the cm-plugin.

HTML-Includes

Add the following line to the HTML-Head section of your outer layout:

<head>

  <tml:htmlhead/>

  <tml:include designdb="plugin-cm-modules" ref="htmlhead-includes"/>

  ...

</head>

The included TML module ensures that all CSS and JavaScripts necessary to run the content modules from the cm-plugin are available to your site.

Include the module renderer from cm-modules plugin

Inside the TML that renders your content type add one or more includes of "modules:render" from the cm-modules plugin:

<tml:include designdb="plugin-cm-modules" ref="modules:render" o_section="content"/>

The option o_sections specifies a "content section". You may define more than one content sections and allow different content modules for each section. F. e. you may have a section "content" just below any other content items of the content type and a second section for the teaser elements of the site.

Example:

<div>

  <div style="float:left; width:600px">

    <tml:include designdb="plugin-cm-modules" ref="modules:render" o_section="content"/>

  </div>

  <div style="margin-left:600px">

    <tml:include designdb="plugin-cm-modules" ref="modules:render" o_section="teaser"/>

  </div>

</div>

The names of the sections are up to the designer. They are referred in the definitions of the allowed modules described later.

There is however a default section name of "content". This means if you want to include the module renderer for a section of name "content" the o_section option may be omitted:

<tml:include designdb="plugin-cm-modules" ref="modules:render"/>

Define the allowed content modules for a section

In addition to option "section" the TML module "modules:render" accepts options "modules" and "exclude-modules". Use this options to defined the allowed and disallowed modules for a section:

Option "modules":

This option is a comma separated list of module IDs that are allowed in this section. If you omit this option all available modules are allowed in this section.

Example:

<tml:include designdb="plugin-cm-modules" ref="modules:render" o_modules="cm_rtf,cm_horrizontal_line"/>

In this example only the modules cm_rtf (Rich text module) and cm_horrizontal_line (horizontal line) are allowed.

Option "exclude-modules":

If you want to allow all modules except some of them you can use this option to define only the module IDs that sould be excluded from the allowed module list.

Example:

<tml:include designdb="plugin-cm-modules" ref="modules:render" o_exclude-modules="cm_google_map"/>

In this example the author can use any module except the google maps module.

The option "exclude-modules" is ignored if you have specified a "modules" option.

How to find the IDs of available modules:

The list of all registered modules and its IDs depends on your OpenWGA installation and can be looked up in the OpenWGA Admin Client in section "plugins / content modules".

RTF Options

One of the most used content module is the RTF module.

Typically you want to define RTF options to be used by this module in the same way as you define RTF options in normal RTF items.

This can be done by specifying an option "rtf-editor-styles" in the include of modules:render:

<tml:include designdb="plugin-cm-modules" ref="modules:render">

    <tml:option name="rtf-editor-styles">

        showoptions: "all",
        sectionStyleList: ["Advice|advice", "Code|code"],
        css: "<tml:url type="css" name="style"/>"

    </tml:option>

</tml:include>

Global module configuration

Some CM modules need global configuration before they work. This mostly is the case for modules which retrieve data from a special type of app, like forums, image gallerys etc. In this configuration you configure what apps should be used by those modules.

The global module configuration is done on OpenWGA admin client. Navigate in the menu to "Plugins > Content Modules". Below a list of all installed modules you see the global module configurations, showing all modules which can be configured:

global-module-config.png

Click a module to bring up the individual configuration:

global-module-config-foren.png

This example is from the "forums" module. It receives the database keys of forum apps installed on the server. 

When using a "forums" module somewhere in content management  it will retrieve the global configuration as options for the source app selection in its individual config:

module-config.png

Creating new content modules

If you want to use your own content modules you have to "register" those modules. Each module is defined through a JSON object of the following format:

{

  id: '<unique id>',

  title: '<title of the module>',

  tml: '<tml to render this module>'

}

Here is a complete reference of available properties:

PropertyOptionalValue
allowedchildrenYesArray of id-s of the allowed children modules of this module. A child module is a module that gets rendered inside this module. Omitting this will mean that your module may have no children.
allowedparentsYesArray of id-s of the allowed parent modules of this module. Must be in sync with the "allowedchildren" property of those parent modules.
categoryYesA name for the category in which this module is presented in the CM module editor. Omitting this will let this module be offered at the top level in the module hierarchy.
iconYesURL to an icon which the CM content module editor should display for your module
id
A unique ID of your module. Use a format similar to Java package names to keep them unique, and build it from a web domain of yours (in reverse order of domain parts) plus some individual module identifier. For example "de.innovationgate.somemodule".
id_aliasYesAn alias ID for a module. If you once decide to change the ID of a module place the old ID in field id_alias. Otherwise contents containing modules with the old ID will not be found.
settingstmlYesThe WebTML module used for module settings. This one is shown in the module editor to configure modules of this type. Use the Design References form of your WebTML module name.
title
The module title which will show up in the module selection dialog in Content Manager.
typeYesSpecify value "container" for container modules
includesYes

An Object defining additional TMLs, JS, CSS and query plugins to be included when this module is rendered.

Properties:

- jquery_plugins: A name of a jquery-plugin or an array of OpenWGA query plugins

- css: A name of a CSS-TML or an array of TMLs that will be included

- js: a name of a JavaScript-TML or an array of TMLs that will be included

- tml: An additional TML or an array of TMLs that will be included in the header section


Each JSON module definition JSON needs to be placed into a separate WebTML module of custom location and name. To finally register those modules with OpenWGA you need to call the following method:

CMM.registerConfigTML("<name-of-your-definition-TML>")

Again use the Design References form of your WebTML module names as parameter for this call. You should place this call into the connect script of your design so the module will be immediately available after an app with that design gets connected.

Using items in render TML

If your module uses its own items to put out content you need to "scope" the item names that you use. As multiple modules use the same content document to store their individual items they may not use plain item names. The WebTML scoping functionality puts a generated suffix on each of your items so they do not "collide" with the items of other modules. Just use the "scoped"-function everywhere you refer to your item name:

<tml:item name="{scoped:myitem}" editor="rtf"/>


<tml:script>

   if (item(WGA.scoped("my item")) != "") {

    ...

   }

</tml:script>

That way a page may also choose to use the same module multiple times. As every module uses a different scope suffix they have all individual items.

Creating a settings TML

The settings TML is a WebTML module which is used in the module editor in content manager to configure your module. You can fill it with <tml:input> tags which create controls for the configuration. The names of the inputs also need to be scoped:

Color: <tml:input name="{scoped:thecolor}" type="select" options="red,green,blue"/>

The fields in the settings of a module are available to the render TML by using the built-in TMLScript methods CMM.setting() or CMM.settingList(). Those methods takes the name of the setting field, this time without the scope:

<div style="color:<tml:script expression="CMM.setting('thecolor')"/>">

  ...

</div>