Configure the Content Editor

Introduction

Using the Content Editor in censhare you put XML texts from different assets, placed assets and metadata from different assets together in one virtual document. The content of this virtual document is composed of the individual assets of the asset content structure. Assign to this an asset configuration structure. From this moment on users can open the documents and work with them.

The Content Editor offers you great flexibility in putting the content together. In a simple case, the content asset structure has one text asset that stores the XML text at its master file.

You can also put together an extensive content asset structure. Below the main content asset, there are different assets with XML text. Other related assets deliver only metadata. For instance, this could be product assets. Create the relations within the content structure according to your needs. This could be a tree structure with the main content asset as the root node, for instance.

Each XML text of a content asset has to maintain a certain structure that the associated XML schema describes. censhare 5 uses RelaxNG to describe the XML schema for the Content Editor. The RelaxNG schema is the basis to validate if the associated XML text keeps the desired XML structure. Beside that, the Content Editor uses the RelaxNG schema to offer the user at each point of the document the allowed elements for selection. It is also possible that XML texts from different assets use different RelaxNG schemas.

The associated configuration structure defines which data from the content structure are displayed and edited. It specifies for each content asset which metadata or which XML elements of the XML file in the Content Editor appear. It also defines the order in which the data appear in the editor. For example, the SEO data of an article can be displayed at the beginning or at the end of the Content Editor. You can also define that not all SEO data are displayed.

Beside that, the configuration structure defines how the different elements are displayed in the Content Editor. For this purpose, the editor contains different renderers that have the according controls to display the elements respective attributes. Assign the individual XML elements or attributes each to the desired renderer. For example, you can configure the size used to display a certain text element. Or you can determine whether the values of an attribute are displayed as a list or radio buttons.

Create a configuration

First step: Defining the different contents for the Content Editor

First, you have to define which XML elements and metadata should be displayed in the Content Editor. This happens at the "Content Editor Configuration" asset. At the same time, it is the main configuration asset below which all other assets are located.

To present the various XML elements and meta data in one XML document the different entries are included by references nodes. So called virtual nodes structure the different entries. A simple structure can look like this:

<virtual node article>
	<SEO>
	<title>
	<summary>
	<text>
</virtuel node>

In the Content Editor the user sees the following structure:

v article
	> SEO
	> title
	> summary
	> text

"article" is a virtual node respective element because he is not defined at any XML file.

If <text> has the child elements <paragraph>, <list> and <picture element>, for instance, the user can see these elements or work with them, too. In the Content Editor the user can see something like this.

v article
	> SEO
	> title
	> summary
	v text
		> paragraph
		> picture element
		> paragraph
		> list

There are separate assets which define where the referenced XML elements and meta data come from. These assets are related with the main configuration file. For each content asset that delivers some metadata there must be its own metadata configuration asset. The same is with each content asset that delivers some XML elements for the Content Editor. There must be an own master storage item asset. If all metadata and XML elements are only located at the main content asset there is exactly one metadata configuration asset and one master storage item asset.

For each XML text that is referenced by a master storage item asset a RelaxNG schema must exist . This is stored at the XML file of a schema asset. This is related to the master storage item.

Second step: configuration of the display in the Content Editor

For each master storage item asset an own UI configuration asset defines which renderers are used to display the XML elements referenced. This step is not necessary for metadata. In this case, the system selects the appropriate renderer looking at the definition of each metadata.

Third step: Localization of the node names for displaying

For each element respective node in Content Editor, you can specify a name string for the particular language. If a node has no name string, neither for the required language or a standard name string, the system will choose the name of the element, attribute or value. For metadata, the system chooses the according name string that is defined for a feature at the master data of the Admin Client.

For each master storage item asset with its referenced XML elements there is a localization asset that contains the name strings. The virtual nodes defined at the main configuration asset have their own localization asset that is related with the main configuration asset. If you define in a metadata asset your own traits there is an own localization asset necessary for translation. It is related to that metadata asset.

Build a sample configuration

The following example shows the structure of a simple configuration for the Content Editor. The content structure consists only of the "Text Asset", which contains both all metadata and the XML text in the master file. You can choose the names of the assets as you want. The structure and the tasks of the different assets are defined by the asset type and the relations.

Structure of a simple configuration

The configuration of the content editor behaves statically. Changes only take effect when the user reloads the text asset. In opposite to this, the Content Editor behaves dynamically when the user is working with it. Changes within the text or meta apply immediately and will be saved at once.

In the download area of the article on the left, you can download a simple example of a text asset including the configuration, import it into your censhare system and try it out.

Content asset structure

You can mostly build your content structure as you want. The only requirement is that the main content asset has the internal feature "Content Editor Configuration". This field of the asset stores the resource key of the corresponding main configuration asset. You create this feature at the tab "Features" within the section "Features (internal) in the censhare-Java-Client. The administration mode has to be activated there.

Without this feature, you cannot open the content asset structure in the Content Editor of censhare Web respectively work with it. Without the configuration, it does not make sense to use the Content Editor.

The relation "Assignment" between the main content asset and the main configuration asset is not necessary. For test purposes, this could be useful. When working productive this should be avoided. The number of assets related with the configuration assets can grow very large. This may cause performance problems.

As a simple case, the content structure consists of a text asset ('Asset type = "Text") as the main content asset which stores the XML text in the master file. This also simplifies the specification which asset within the content asset structure is referenced by a configuration asset. If there is no according XPATH expression as a feature the Content Editor always uses the main content asset to get its data from.

Main configuration asset

The main asset for the configuration has the type "Module/Content Editor/Content Editor Configuration". The identification of the asset is done by a key that is defined in the censhare-Java-Client at the tab "Advanced" in the section "Resource". Besides that, the checkbox "Enabled" has to be activated.

The main configuration asset stores the XML content structure for the editor. There are three different nodes respective elements to describe the XML content structure:

• Virtual nodes

• Reference to an XML element

• Reference to metadata

The individual entries are explained below.

Virtual nodes

A virtual node itself has no data. He is used to create a better structure of the XML content.

An XML content structure must have at least one virtual node that owns references to XML elements or meta data:

<virtual-node name="article">
	[Reference]
	...
</virtual-node>

[Reference] is a placeholder for a reference to an XML element or meta data. There can be sevaral reference nodes below each other. For example, a minimal configuration with one text element and a meta data block as a references looks like this:

<virtual-node name="content">
	<ref namespace="cs-meta-trait" name="seo" node-source="Meta Data" 
															path="traits/seo/seo"/>
	<ref name="title" node-source="Master Storage Item" path="article/title"/>
</virtual-node>

Each virtual node has the attribute "name". The definition is 'name="XXX"'. In the example above is 'name="article"'. You are free to choose the names of the virtual nodes as you want. They just have to obey the rules for XML identifiers. For instance, the name is used as a key to add name strings for different languages for a virtual node. For example, the association looks like this:

<entry key="article">Article</entry>

"key" contains the "name" of the virtual node, here "article". "Article" is the associated name string. For more information see the section about localization assets. For better organization of the content, you can nest multiple virtual nodes. This may look like this:

<virtual-node name="content">
	<virtual-node name="publication">
		[Reference]
		...
	</virtual-node>
	<virtual-node name="article">
		<virtual-node name="headline">
			[Reference]
			...
		</virtual-node>
		<virtual-node name="text">
			[Reference]
			...
		</virtual-node>
	</virtual-node>
	<virtual-node name="print">
		[Reference]
		...
	</virtual-node>
</virtual-node>

In the Content Editor the structure looks like this:

v content
	> publication
	v article
		> headline
		> text
	> print

Reference to an XML element

For each XML subtree that you want to display in the Content Editor, add an own reference element.

<ref name="title" node-source="Master Storage Item" path="article/title"/>

The attribute "name" adds the name to the element, here "title". For the localization you can add different name strings for the individual languages. Typical values for "name" are "title", "subtitle" or "text", for example.

The "node-source" attribute provides the connection to the master storage Item asset that stores the XML text that contains the referenced XML element. At the master storage item asset the internal feature "Node Source Name" must contain the value that is used for the "node-source" in the reference entry in the main configuration asset. Here, the "node-source" has the value "Master Storage Item".

Using "path" you refer to the desired XML element within the XML text, here ="article/title". In this example is "article" the root element and "title" a child element. When selecting the path you have to care for that the entry is unambiguous. Otherwise, an error may occur. For instance, this could be the case with the path: "article/text/paragraph". If the element "text" has more than one "paragraph", the path is not unambiguous anymore.

You are free which XML elements of an XML text of a content asset you want to include. You can simply reference the root element of the according XML schema:

<ref name="article" node-source="Master Storage Item" path="article"/>

On the other side you can also reference individual XML elements. This make sense, for instance, if the user should not see all XML elements respectively edit them. The entry looks like this:

<ref name="headline" node-source="Master Storage Item" path="article/headline"/>
<ref name="summary" node-source="Master Storage Item" path="article/summary"/>
<ref name="text" node-source="Master Storage Item" path="article/text"/>

The important thing is that the individual references do not overlap, resulting in duplicated elements. For instance, the following configuration is not allowed:

<ref name="article" node-source="Master Storage Item" path="article"/>
<ref name="summary" node-source="Master Storage Item" path="article/summary"/>

Reference to metadata

You add an own reference element for each feature or feature set, also called "Trait", that you want to show in the Content Editor. For instance, this looks like this:

<ref namespace="cs-meta-trait" name="exif" node-source="Meta Data" path="traits/exif/whiteBalance"/>

The 'namespace="cs-meta-trait"' attribute defines the namespace "cs-meta-trait" for referenced feature or trait. This information is necessary for the system in order to process the feature or the trait correctly.

The "name" attribute adds a name to the element, here "exif". For the localization, you can add different name strings for the individual languages.

The "node-source" attribute provides the connection to the metadata asset which stores the referenced feature or trait. At the metadata asset there must be an internal feature "Node Source Name" that contains the value of the "node-source" attribute. In this case, the "node-source" contains the value "Meta Data".

The "path" attribute points to the desired trait or element within the trait. In the shown example the "path" attribute has the "traits/exif/whiteBalance" value and refers to the "whiteBalance" feature within the "exif" trait. If you want to point to the trait itself the path has the "traits/exif" value.

You can use the Admin client to determine the path for a particular feature. To do so, open the "Feature" table with the "master data" section. Search for the desired feature and open its definition. The "Trait" field contains the name of the respective trait. The "Property name" field has the name of the feature. If 'Trait="address"' and 'Property name="country"' is, the path looks like this: 'path="traits/address/country".

The important thing is that the individual references do not overlap, resulting in duplicated elements. For instance, the following configuration is not allowed:

<ref namespace="cs-meta-trait" name="exif" node-source="Meta Data"
 path="traits/exif/creationDate"/>

<ref namespace="cs-meta-trait" name="exif" node-source="Meta Data" 
 path="traits/exif"/>

You can also include traits created by a company or a service provider.

Metadata asset

Using the metadata asset you can include metadata from an asset within the content structure. You have to reference this metadata in the main configuration asset in order to show up in the Content Editor.

Configuration of the asset

Each metadata asset has the "Module/Content Editor/Content Editor Node Source Definition/Content Editor Meta Data Configuration" asset type. It is linked with main configuration asset using the "Content Editor Node Source" reference.

You have to add the "Node Source Name" feature as "Feature (internal)"s to the asset in order to reference the metadata in the main configuration asset that you have defined here.

Each metadata asset points to a specific content asset that's metadata are then accessed. Without further definition the main content asset is used. If you want to use another content asset you have to point to this asset using an XPATH expression. In order to do so, create the "Asset Reference (XPath)" Feature (internal) at the metadata asset and enter the XPATH expression that points to the desired asset. The starting point of the XPATH path is always the main content asset.

For instance, the main content asset has the "Text" asset type and a parent relation with the "Main content" type. The parent asset has the "Article" asset type. The following XPATH expression references the article asset and not the text asset:

"Asset Reference (XPath)"="cs:parent-rel()[@key='user.main-content.*']/
   cs:asset()[@censhare:asset.type='article.']"

If you want to reference metadata from various content assets, you need to create your own metadata asset for each content asset and refer to the respective content asset.

Definition of the metadata

The XML meta data configuration of the meta data asset has the following root element:

<meta-data>
	<trait name="exif"/>
	...
<meta-data/>

You can only reference the metadata in the main configuration asset that you defined here. Otherwise, you cannot access them.

The definition of metadata is done using traits. In the simplest case, you include a trait already defined in censhare. This may look like this:

<trait name="exif"/>

This is the respective definition at the main configuration asset:

<ref namespace="cs-meta-trait" name="exif" node-source="Meta Data" 
    path="traits/exif"/

The Content Editor shows all features belonging to this trait. In this case, the following features belong the trait: "exposureCompensation", "meteringMode", "iso", "whiteBalance", "lens", "creationDate", "shutterSpeed", "aperture" "model" "focalLength" and "flash".

You can also include a single feature. In order to do so, refer to the feature in the reference entry:

<ref namespace="cs-meta-trait" name="exif" node-source="Meta Data" path="traits/exif/shutterSpeed"/>

The path has the following parts: "traits", the desired "exif" trait and the associated "shutterSpeed" feature. At the Content Editor the user will only see the "shutterSpeed" feature instead of the whole trait. In the same way you can also include other features of the same trait:

<ref namespace="cs-meta-trait" name="exif" node-source="Meta_Data_Example" 
   path="traits/exif/shutterSpeed"/>
<ref namespace="cs-meta-trait" name="exif" node-source="Meta_Data_Example" 
   path="traits/exif/aperture"/>

Both entries will now appear as individual features below each other. It can be more useful to define your own trait and add the desired features there. Now, the user shall see both the "shutterSpeed" and "aperture" features in one group. Create for each feature a property entry:

<property trait="exif" name="aperture"/>
<property trait="exif" name="shutterSpeed"/>

For the "trait" attribute enter the trait name defined in the feature table in the master data. The "name" attribute contains the "Property name" of the feature.

Now, you still have to define the trait the features should belong to:

<trait name="exif">
	<property trait="exif" name="aperture"/>
	<property trait="exif" name="shutterSpeed"/>
</trait>

Using 'name="exif"' you overwrite the standard definition of the "exif" trait in the system for the Content Editor.

You can also combine features to a trait that are defined in different traits in the system:

<trait name="exifIptc">
	<property trait="exif" name="aperture"/>
	<property trait="iptc" name="headline"/>
</trait>

Enter the following line at the main configuration asset:

<ref namespace="cs-meta-trait" name="display" node-source="Meta Data" path="traits/workflow"/>

The user will see the following elements in the Content Editor:

v exifIptc
	> aperture
	> headline

If you have defined traits like "exifIptc" in a metadata asset, it is advisable to define a localization for these metadata. This is also done using a localization asset connected via the "Localization" reference to the metadata asset. Using the trait name you can define name strings for the different languages. For example, the association looks like this:

"key" contains the "name" of the element, here "exifIptc". "Camera data" is the assigned name string. For more information see the section about localization assets.

The order of the property entries determines the order in the Content Editor. The definition of the "exifIptc" trait now looks like this:

<trait name="exifIptc">
	<property trait="iptc" name="headline"/>
	<property trait="exif" name="aperture"/>
</trait>

In the Content Editor it looks like this:

v exifIptc
	> headline
	> aperture

You can also include your own traits. In this case, it is important that you add your own prefix to the trait name. This may look like this:

<trait name="company:productName"/>

Master storage item for XML text

Configuration of the asset

The master storage item has the "Module/Content Editor/Content Editor Node Source Definition/Content Editor Storage Item Configuration" asset type. It is linked with main configuration asset using the "Content Editor Node Source" reference.

The "Storage Item Key" feature says which file of the according content assets has to be used. Usually, this will be the main file of the content asset. In this case, the definition is '"Storage Item Key"="master"'.

Beside that, you have to create the "Node Source Name" Feature (internal), for example, "Node Source Name"="Master Storage Item". Using the "Node Source Name" you reference the individual XML elements in the XML file at the main configuration asset:

<ref name="title" node-source="Master Storage Item" path="article/text"/>

To use another content asset besides the main content asset, an XPath expression must point to the desired asset. Create the "Asset Reference (XPath)" Feature (internal). The starting point is the main content asset.

Every master storage item has some related configuration assets:

• The "Localization" asset contains the translations of the element names of the master storage item.

• The "Schema" asset contains the RelaxNG schema definition of the referenced XML text.

• The "UI Definition" asset is responsible for the presentation of the elements of the referenced XML text.

Schema asset

The RelaxNG schema asset for the XML text has the "Module/Content Editor/RelaxNG Schema" asset type. It is linked with the master storage item asset using the "Content Editor Schema" relation type.

UI definition asset for the presentation

For each master storage item, a UI definition asset must be available, which defines the representation of the XML elements or attributes. A UI definitions asset has the "Module/Content Editor/Content Editor UI Definitionen" asset type. It is related with the master storage item Master-Storage-Item using the "Content Editor UI Definitions" relation.

The Content Editor calls a renderer for every XML element's respective attribute. If there does not exist an entry at the XML file of the UI definitions asset the Content Editor uses the associated standard renderer. It may be that this does not always provide the desired presentation. It is therefore advisable to define a renderer for these elements or attributes.

Depending on the data type a different renderer is used. For example, there are renderers for text, placed assets or the presentation of attributes. According to its task, the renderer possesses controls like text, radio buttons or drop-down to show the data.

The "csContentEditorTextRenderer" displays plain text, no matter, if there are inline elements defined. In opposite to that, the "csContentEditorInlineTextRenderer" recognizes the inline elements and displays the text accordingly, for instance, bold, underline or italic. The "csContentEditorTextRenderer" is the standard for displaying text. If no renderer is defined for a text element, the Content Editor uses the default renderer. There must be an entry for a text element if it has inline elements that should be displayed accordingly.

The XML UI definition has the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<ui-description>
	<elements>
		[Renderer-Definition für Element, Attribut oder Inline-Element]
		...
	</elements>
</ui-description>

The definition for an element looks like this:

<element name="paragraph" icon="cs-gi-justify">
	<renderer>
		<csContentEditorInlineTextRenderer style="font-size:24px;"/>
	</renderer>
</element>

"name" defines the element name at the associated RelaxNG schema, here "paragraph". "csContentEditorInlineTextRenderer" is the defined renderer.

For all elements respective attributes, you can define an icon. The Styleguide of the censhare Web client gives you an overview about all available icons in the "Icons" section of the "Library-Atoms" area. There, copy the name of the icon and enter it as value for "icon" attribute. Defining 'icon=""' has the same result as to leave out the entry.

For every renderer you can define the "style" attribute. It influences the presentation and contains CSS declarations. A useful option is "font-size", for instance, 'style="font-size: 180%;"' or 'style="font-size:24px;"'.

If you want to have a common definition of an attribute that is independent from its associated element, see the following example:

<attribute name="style" icon="cs-gi-sampler">
	<renderer>
		<csContentEditorAttributeRadioRenderer/>
	</renderer>
</attribute>

The value of the "name" attribute defines the element of the associated XML schema, here "style". "csContentEditorAttributeRadioRenderer" is the defined renderer for the attribute.

If the attribute definition should be valid for a certain element you have to create it within the element definition:

<element name="title" icon="cs-gi-tag">
	<attribute name="style">
		<renderer>
			<csContentEditorAttributeRadioRenderer/>
		</renderer>
	</attribute>
	<renderer>
		<csContentEditorInlineTextRenderer style="font-size: 130%;"/>
	</renderer>
</element>

UI renderer

In the following, find a description of common renderers. For a complete list of renderers, see the developer documentation.

Example of the use of the "csContentEditorAssetRenderers":

<element name="image" icon="cs-gi-picture">
	<renderer>
		<csContentEditorAssetRenderer>
			<layout type="borderLessImage"/>
			<filter assettype="picture.*"/>
		</csContentEditorAssetRenderer>
	</renderer>		
</element>

Inline style definition

For the "csContentEditorInlineTextRenderer" you can define how the different inline elements are displayed. The definitions only have an effect when using the inline text renderer.

This is how you define the presentation of inline elements:

<element name="bold" icon="cs-gi-bold">
	<inline style="font-weight:bold"/>
</element>

The text marked accordingly will be displayed bold. The "style" attribute contains the desired CSS declarations. The following style definitions are useful to add:

• font-weight:bold

• font-style:italic

• text-decoration: underline

• vertical-align:super

• vertical-align:sub

• font-size:smaller

• color:yellow

With "color" you must insert the desired color, yellow here.

You can also combine multiple CSS declarations. This may look like this:

<element name="sup">
	<inline style="vertical-align:super;font-size:smaller;"/>
</element>

The correspondingly selected text will be raised and appear smaller.

Renderer for inline elements

Using buttons on the toolbar, the user can mark text with inline elements. With certain elements like "Bold", it is only necessary to set the accordingly tags. However, other inline elements like links await user input. If the user clicks on such a button a dialog will open. For the display of the attributes in this dialog you can also define renderer. Otherwise, the standard renderer will be used.

You can determine if an inline element expects that the user enters values in a dialog. Have a look at the definition of the element at the RelaxNG schema if the element has an attribute as a child node.

For example, the following element definition opens a dialog box when the user clicks the corresponding button. The "link" element has the "url" attribute and the optional "target" attribute as child nodes:

<define name="el_link">
	<element name="link">
		<text/>
		<attribute name="url">
			<text/>
		</attribute>
		<optional>
			<attribute name="target">
				<choice>
					<value>self</value>
					<value>new-window</value>
				</choice>
			</attribute>
		</optional> 
	</element>
</define>

The UI definition of the "link" element looks like this:

<element name="link" icon="cs-gi-link">
	<inline style="color:blue;text-decoration:underline;"/>
	<attribute name="url" icon="cs-gi-hl-paperclip"/>
	<attribute name="target" icon="cs-gi-more_windows">
		<renderer>
			<csContentEditorAttributeRadioRenderer />
		</renderer>
	</attribute>
</element>

There is a definition for the "link" element. The element gets the style parameters "color:blue;" and "text-decoration:underline;". The "URL" attribute just receives an icon. The "target" attribute can have the values "self" and "new-window". The "csContentEditorAttributeRadioRenderer" is used to present them as radio buttons. Without specifying the renderer, the "csContentEditorAttributeRenderer" would present the "target" attribute as a drop-down list. It is responsible for the representation of an attribute if there is no renderer defined.

Specify icon only

If the default renderer presents the desired result, a definition for the item is not necessary. If you just want to define an icon, there is a short version. This is what it looks like:

<element name="text" icon="cs-gi-edit"/>

Definition of renderer displaying metadata

For presenting metadata there are no definitions of renderers necessary. The selection of the appropriate renderer is done internally in the system using the existing information about metadata.

Localization asset

Assign name strings to elements, attributes and values to a certain language in the Content Editor using the localization asset. There may be localization assets for each master storage Item asset, each metadata asset and for the main configuration asset.

Each localization asset has the type "Module/Localization". It is linked with the belonging asset using the reference "Localization".

The master file of the localization asset stores the XML structure. It looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<localization>
	<properties locale="">
		<entry key="workflowTarget">Workflow target</entry>
		...
	</properties>
	<properties locale="de">
		<entry key="workflowTarget">Workflow-Ziel</entry>
		...
	</properties>
	...
</localization>

"locale" specifies which language the following definitions apply. If the value for "locale" is empty, censhare uses the name strings for all languages where no specific definition is provided. For the definition of existing language codes have a look at the table "languages" in the Admin Client.

"key" defines the name string is valid for. It identifies an element, an attribute or a value defined at RelaxNG schema. At the same time, the "key" defines the scope of a name string for attributes and values. If several elements have the same attribute, the name string may be either different for all elements or equal for each element. With values it is mostly the same. You can define a value for a particular element and attribute, for an attribute independently of the related element or globally. The identifier then applies regardless of the element or attribute value it occurs.

This is the syntax for "key":