Content Models mini howto
What Content Models are and how to configure them
This document is for designers who are preparing to develop a new portal using the Entando platform. So the recipients are experts in graphical interfaces for Web and Java developers.
In order to take the maximum advantage of the present document, it is necessary to have basic knowledge about:
The purpose of Content Models is to represent in the proper manner information, which are enclosed in Contents, within the pages of an Entando-based portal.
Usually each Content Type has at least two models: one is used to display the details of a given Content, the other is needed when the content appears in a list (for example in the ListViewer Widget).
Content Models can be created from the administration interface from the left menu → Contents → Content Models.
From the Content Model Management page the administrator can create new Content Models or edit existing ones.
For each Content Model the administrator must specify:
-
Id: an unique number needed by Entando .
-
Type: this drop down menu is used to select the Content Type for which this model is created. Pressing the Set will give a clue on which Content Type we are working on so that it will help suggesting also the attribute names.
-
Description: a brief description of the purpose of the model
-
Model: the content model written using the Velocity language
-
Style Sheet: the name of a CSS style sheet; this is the only optional parameter.
Pressing the Save button the XML representing the configuration will be saved in the Port Database in the table contentmodels.
The model takes advantage of the functionality offered by the Velocity template engine: variables, control functions and expression are made available to the designers.
It is important to stress that the model must produce a result coherent with the portal pages: for example if the portal is XHTML based the model must produce a XTHML fragment.
IIn the examples that we are going to show the Velocity templating language coexists with the markup language used in the portal pages.
Entando makes available to the Velocity context the following objects:
-
$content
-
$i18n
As it can be easily guessed, this object represents the content; it is possible to fetch the value of any of the content attribute using the following syntax:
$content.ATTRIBUTE_NAME
Every attribute has its own properties used to access its value.
Moreover, Entando makes available the following methods:
-
$content.getCategories(): a map containing the list of the categories associated to the content
-
$content.getContentLink(): returns a string representing the link to the portal page where the content is explicitly published.
-
$content.getContentOnPageLink("<PAGE_CODE>"): this is a method which takes as input argument the code of a page and returns a symbolic link which points to the content itself within the desired page.
-
$content.getCreated("<DATE_PATTERN>"): this method returns the creation date in the desired format
-
$content.getId(): this method return the content id
-
$content.getLangCode(): this method return the code of the language of the current page
-
$content.getLastEditor(): this method returns the username of the last user who modified the content
-
$content.getLastModified("<DATE_PATTERN>"): this method returns the date, in the specified format, in which the content was last modified.
-
$content.getVersion(): this method return the current version of the content. Content versioning system follows this convention:
- published Contents have always version X.0, e.g. 3.0 (the content has been published 3 times)
- Contents which have been modified Y times since the last publication have a version X.Y, e.g. 2.8
- Contents which were never published have version 0.Y (however they cannot be displayed in the portal for obvious reasons)
This objects is used to retrieve labels from the database.
This objects exposes this unique method:
- $i18n.getLabel("<LABEL>"): this method returns the label associated to the given label code in the current portal language.
There are a number of criteria to follow when creating new content models and assigning ID, giving description and associating stylesheets.
The value of IDs starts from 1.
As stated earlier, each content type must have at least two models: one for the detailed view and other one for lists; they are commonly called defaultmodel and listmodel, respectively.
By convention we proceed assigning the ID to defaultmodels, then listmodels and finally the remaining ones.
For default models we assign an increasing number.
For example, given a portal with two Content Types, News and Generic Content, the designer could assign to the respective Content Models for the default view (defaultmodels) the id 1 and 2.
For list models we add another number, starting from 1 which by convention is assigned the model used for list (listmodels).
In the hypothetic portal above the listmodels for News and Generic Content would have the id 11 and 21.
A hypothetic listmodel id relative to the ninth Content Model would be 91; the listmodel id of the tenth Content Model would be 101 and so on.
So, to recap:
-
id for the defaultmodel for the News Content: 1
-
id of the listmodel for the News Content: 11
-
an alternate model id for the News Content: 12
-
id of the default model for the Generic Content: 2
-
id of the listmodel for the Generic Content: 21
-
alternate model id for the Generic Content: 22
… 7 Content Models more...
-
id of the defaultmodel for the tenth content: 10
-
id of the listmodel for the tenth content: 101
-
an alternate model id for the tenth content: 102
There are no particular conventions for the description of the content models apart from reporting the information which will be shown.
For example, taking as reference the a content type “Generic Content” shown in the document Content Types – mini-howto, composed of the following attributes:
-
Title
-
Abstract
-
Body
-
Image_1
-
Image_2
-
Links
-
Attach
we are going to show a few examples of effective descriptions.
A description of a model which is going to show the Title, Body, (the list of) links, (the list of) attachments and the Image_1 would be:
Full (Title, Body, Links, Attach, Image1)
A description of a model for lists which just shows the Title and the Image_1 would be:
Model for List (Title and Image1)
It is always useful to include additional information or to underline particular behaviour of the model as shown in the next example:
List Model – Red (Title, Img1)
Please also notice that the Description field is a free text, so there is no need to match the information to actual attributes: in the examples above we used Image1 and Img1 instead of the actual attribute name Image_1.
To keep a simple yet strict order during the portal development it is a good practice to always have style sheets organized in a directory on its own, called (for example) contentmodels.
Commonly the name of the CSS file has as prefix the id of the content type followed by a description without spaces.
A wise organization of the CSS files would be the following:
…/contentmodels/CNG_full.css
…/contentmodels/CNG_box_green.css
…/contentmodels/CNG_list_red.css
In this chapter we are going to show a few examples which demonstrate how to create and utilize different Content Models for different Content Types.
Taking as reference the following Content Type – Generic content or simply CNG -
<contenttype typecode="CNG" typedescr="Contenuto generico"
viewpage="contentview" listmodel="11" defaultmodel="1">
<attributes>
<attribute name="Title" attributetype="Text" required="true" />
<attribute name="Abstract" attributetype="Longtext" />
<attribute name="Body" attributetype="Hypertext" />
<attribute name="Image_1" attributetype="Image" />
<attribute name="Image_2" attributetype="Image" />
<list name="Links" attributetype="Monolist" nestedtype="Link" />
<list name="Attachs" attributetype="Monolist" nestedtype="Attach" />
</attributes>
</contenttype>we are going to create the complete model and the model for lists.
To create a model aimed at the visualization of all the attributes -except Abstract which is used only fo r list – an administrator would compile the the form of the first chapter in the following way:
-
id: 1
-
Type (drop down menu): Generic content
-
Description: Complete (title, body, img1-2, links, attach)
-
Model:
$content.Title.text
$content.Body.text
$content.Image_1.text: $content.Image_1.imagePath("1") -
$content.Image_2.text: $content.Image_2.imagePath("1")
#foreach ($link in $content.Links)
$link.text: $link.destination -
#end
#foreach ($attach in $content.Attachments)
$attach.text: $attach.attachPath -
#end- Style Sheet:
contentmodels/CNG_complete.css
A generic CNG content will output something similar to the following:
Test Content
<p>This is a test with images, links and attachment</p>
My Logo: /myPortal/resources/cms/images/myImage_d1.jpg
Company Logo: /myPortal/resources/cms/images/anotherImage_d1.png
jAPS Homepage - http://www.japsportal.org
jAPS Developers Site - http://dev.japsportal.org
Architecture - /myPortal/resources/cms/documents/articolo1.pdf
Advantages - /myPortal/resources/cms/documents/vantaggi.pdf
Entando has simply displayed the value of the attributes of the content; the next step is to transform this output into valid HTML:
<div class="generic">
<h3>$content.Title.text</h3>
$content.Body.text
<img src="$content.Image_1.imagePath("1") alt="$content.Image_1.text" />
<br />
<img src="$content.Image_2.imagePath("1") alt="$content.Image_2.text" />
<h4>Link</h4>
<ul>
#foreach ($link in $content.Links)
<li>
<a href="$link.destination">$link.text</a>
</li>
#end
</ul>
<h4>Attachments</h4>
<ul>
#foreach ($attach in $content.Attachments)
<li>
<a href="$attach.attachPath">$attach.text</a>
</li>
#end
</ul>
</div>
In the configuration of the Content Type above no attributes
were declared mandatory.
To check if an attribute holds a valid value we can use the Velocity
syntax:
<div class="generic">
<h3>$content.Title.text</h3>
#if ($content.Body.text != "")
$content.Body.text
#end
#if ($content.Image_1.imagePath("1") != "")
<img src="$content.Image_1.imagePath("1")" alt="$content.Image_1.text" />
<br />
#end
#if ($content.Image_1.imagePath("2") != "")
<img src="$content.Image_2.imagePath("1")" alt="$content.Image_2.text" />
#end
#if ($content.Links && $content.Links.size() > 0)
<h4>Links</h4>
<ul>
#foreach ($link in $content.Links)
<li>
<a href="$link.destination">$link.text</a>
</li>
#end
</ul>
#end
#if ($content.Attachments && $content.Attachments.size() > 0)
<h4>Attachments</h4>
<ul>
#foreach ($attach in $content.Attachments)
<li>
<a href="$attach.attachPath">$attach.text</a>
</li>
#end
</ul>
#end
</div>
When the generic content appears in a list there's no need to show all of its attributes; in the following model we just show the abstract
<p>
<a href="$content.contentLink">$content.Titolo.text</a>
#if ($content.Abstract.text != "")
<br />
$content.Abstract.text
#end
</p>
Given the News Content Type defined as follows:
<contenttype typecode="NEW" typedescr="New" viewpage="newsview"
listmodel="21" defaultmodel="2">
<attributes>
<attribute name="Title" attributetype="Text" required="true" />
<attribute name="Date" attributetype="Date" required="true" />
<attribute name="Abstract" attributetype="Longtext" />
<attribute name="Body" attributetype="Hypertext" required="true" />
</attributes>
</contenttype>Again, the first step is to fill the content model form in the administration area with the following values:
-
id: 2
-
type: 2
-
Description: Complete (Title, date, body)
-
model
<div class="complete">
<h3>$content.Title.text</h3>
<p class="data">$content.Date.longDate</p>
$content.Body.text
</div>
<p>
<a href="$content.contentLink">$content.Title.text –
$content.Date.shortDate
</a>
#if ($content.Abstract.text != "")
<br />
$content.Abstract.text
#end
</p>