-
Notifications
You must be signed in to change notification settings - Fork 3
Page Models mini howto
How to configure Page Models with some real-life examples
This howto is for those who are preparing to develop a new portal using the Entando Platform.
The present document is intended for both developers and experts in graphical interfaces for the Web.
In order to take the maximum advantage of the present document, it is necessary to have basic knowledge about: (X)HTML, CSS, and XML, as well as to use the development environment, as explained in other guides.
A Page Model is a summary of the characteristics of a Page: every page in the Entando platform has a model associated with it which lets administrators to configure the properties of the page and to deploy Widgets into it.
Pages have two souls: the XML and the Markup. The XML configuration specifies the positions – or frames – where Widgets can be placed, while the Markup defines the graphical aspect.
Even if Portal can have as many Page Model as it needs, usually two are always present: a page model for the home page and another one for the internal pages.
Before moving on, it is worth noting that Andrea Dessì made available for public use a tool that assists designers in the creation process of the page models. It can be found here.
The first decision the designer must make is about the structure of the pages: that means establishing the position of default Widgets and to organize the spaces where the remaining Widgets can be placed by the administrator.
Let's say we have just created a new project whose artifactId is myportal: the project will have a database named myportlPort; this is the where we are going to put the configuration of the Page Models providing, in the table named - guess how? - pagemodels, the following data:
- the code (in the column code): this must match the name of the corresponding JSP which will provide the markup of the page. Valid names are:
home, internal_2columns
- a description (in the column description): a readable string which describes the aim of the model:
Homepage, Internal with 2 columns
- a configuration (in the column frames) : this is the XML configuration containing the frames ranging from 0 to frames – 1, where 'frames' is the total number of frames of the page.
<frames>
<frame pos="0">
<descr>Language</descr>
<defaultShowlet code="lang" />
</frame>
<frame pos="1">
<descr>Search</descr>
<defaultShowlet code="search_form" />
</frame>
<frame pos="2">
<descr>Breadcrumbs</descr>
<defaultShowlet code="breadcrumbs" />
</frame>
<frame pos="3">
<descr>Left Box 1</descr>
</frame>
<frame pos="4" main="true">
<descr>Middle Box 1</descr>
</frame>
..........
<frame pos="11">
<descr>Footer</descr>
</frame>
</frames>Important: if the configuration is not for the homepage, don't forget to specify which is the main frame using the proper attribute as shown above; this helps finding the preferred frame of the page where a content can be published (as well as other things not important for the purpose of this document).
The configuration above represents a page with twelve frames, starting from 0 to 11. Some frame has a description which helps the administrator or the designer to figure out what is the aim of that frame.
When a group of Widgets repeats itself over all pages which use a given page model it is handy to use the tag <defaultShowlet/> so that the system automatizes the deploy process (on request).
Some Widgets might also require a configuration: in this case the properties must be specified. In the following example the administrator is creating a menu with all the pages which derive from the Homepage:
<properties>
<property key="navSpec">code(homepage).children</property>
</properties> Once we have established what we want to see in the page and in what order, we must not create the markup which embodies our ideas.
As we have seen in the previous chapter the code of a page models corresponds to a JSP that must be placed in the directory
../src/main/webapp/WEB-INF/aps/jsp/models.
Considering the examples of the previous chapter, meaningful names would be:
home.jsp, internal_2columns.jsp
How we declare the presence of a Widget within the jsp? This is easily accomplished by placing a <wp> tag a place of our choice:
<%@ taglib prefix="wp" uri="/aps-core" %>
<!-- insert content negotiation, doctype etc. -->
. . . .
<!-- Show me the frame 0 Widget in all its splendor -->
<wp:show frame="0">
. . . .
Interface experts will also need to create CSS files in the directory
…/src/main/webapp/resources/static/ css.
Designers are strongly encouraged to organize their CSS' in apposite folders; for example, the Entando team usually create the pagemodels, contentmodels and Widgets directories, depending on the project requirements.
For your convenience, the tag <wp:cssURL /> points to this folder.
Another good practice used by our developers is to create two different stylesheets: one for the definition of the layout, say general.css, placed in the pagemodels directory and a second one for the general
style, say myportal.css.
In this chapter we show two working Page Model examples, one for the homepage and the other for the Internal page, with the associated JSP.
Please do not copy and paste blindly from this document because embedded elements of the document can corrupt the resulting XML!
<frames>
<frame pos="0">
<descr>Search</descr>
<defaultShowlet code="search_form" />
</frame>
<frame pos="1">
<descr>Breadcrumbs</descr>
<defaultShowlet code="navigation_breadcrumbs" />
</frame>
<frame pos="2">
<descr>Column 1, Box 1</descr>
<defaultShowlet code="navigation_menu">
<properties>
<property key="navSpec">code(homepage).children</property>
</properties>
</defaultShowlet>
</frame>
<frame pos="3">
<descr>Column 1, Box 2</descr>
</frame>
<frame pos="4">
<descr>Column 1, Box 3</descr>
</frame>
<frame pos="5">
<descr>Column 1, Box 4</descr>
</frame>
<frame pos="6">
<descr>Central, Box 1</descr>
<defaultShowlet code="news_latest" />
</frame>
<frame pos="7">
<descr>Central, Box 2</descr>
<defaultShowlet code="events_latest" />
</frame>
<frame pos="8">
<descr>Central, Box 3</descr>
</frame>
<frame pos="9">
<descr>Central, Box 4</descr>
</frame>
<frame pos="10">
<descr>Central, Box 5</descr>
</frame>
<frame pos="11">
<descr>Column 3, Box 1</descr>
</frame>
<frame pos="12">
<descr>Column 3, Box 2</descr>
</frame>
<frame pos="13">
<descr>Column 3, Box 3</descr>
</frame>
<frame pos="14">
<descr>Footer</descr>
<defaultShowlet code="navigation_menu">
<properties>
<property key="navSpec">code(site_map)+code(contact_us)</property>
</properties>
</defaultShowlet>
</frame>
</frames>
In this example we see the model for the Homepage: we have 15 frames (0 → 14). Some Widgets, namely the search form, breadcrumbs, the two menus, latest news and the latest events are declared as defaults for the respective frames whereas the remaining frames are left free for general use. The corresponding Widget code are, respectively: search_form, navigation_breadcrumbs, navigation_menu, news_latest, events_latest
It is important to notice that:
-
the navigation menu placed in the first column, box 1 (frame #2) was configured to display all the children of the Homepage
-
the navigation menu located in the Footer (frame #14) was configured to display the page with the Site Map and the Contacts page
But the configuration alone would be nothing without the associated markup page (remember that the name of the JSP must match the code declared in the database)
<%@ taglib prefix="wp" uri="aps-core.tld"%>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="it">
<head>
<title>
myportal|
<wp:currentPage param="title" />
</title>
<link rel="stylesheet" type="text/css" href="<wp:cssURL />myportal.css" />
<link rel="stylesheet" type="text/css" href="<wp:cssURL />pagemodels/general.css” />
<wp:outputHeadInfo type="CSS">
<link rel="stylesheet" type="text/css" href="<wp:cssURL /><wp:printHeadInfo />" />
</wp:outputHeadInfo>
</head>
<body>
<div id="header-up">
<wp:show frame="0" />
</div>
<div id="header-down">
<wp:show frame="1" />
</div>
<div id="column1">
<wp:show frame="2" />
<wp:show frame="3" />
<wp:show frame="4" />
<wp:show frame="5" />
</div>
<div id="column2">
<wp:show frame="6" />
<wp:show frame="7" />
<wp:show frame="8" />
<wp:show frame="9" />
<wp:show frame="10" />
</div>
<div id="column3">
<wp:show frame="11" />
<wp:show frame="12" />
<wp:show frame="13" />
</div>
<div id="footer">
<wp:show frame="14" />
</div>
</body>
</html>In this example we see how to include the Widgets in the Markup.
Please note how:
-
the Search Form and the Breadcrumbs have been included within the <div> tag, respecting the position given in the XML of the frames 0 and 1.
-
the three columns, defined by <div> tags, have 4, 5 and 3 boxes each, respectively.
-
finally, a <div> tag is used for the Footer , which contains the last Frame (number 14.)
<frames>
<frame pos="0">
<descr>Search Form</descr>
<defaultShowlet code="search_form" />
</frame>
<frame pos="1">
<descr>Breadcrumbs</descr>
<defaultShowlet code="navigation_breadcrumbs" />
</frame>
<frame pos="2">
<descr>Column 1, Box 1</descr>
<defaultShowlet code="navigation_menu">
<properties>
<property key="navSpec">code(homepage).children</property>
</properties>
</defaultShowlet>
</frame>
<frame pos="3">
<descr>Column 1, Box 2</descr>
</frame>
<frame pos="4">
<descr>Column 1, Box 3</descr>
</frame>
<frame pos="5">
<descr>Column 1, Box 4</descr>
</frame>
<frame pos="6" main="true">
<descr>Central, Box 1</descr>
</frame>
<frame pos="7">
<descr>Central, Box 2</descr>
</frame>
<frame pos="8">
<descr>Central, Box 3</descr>
</frame>
<frame pos="9">
<descr>Central, Box 4</descr>
</frame>
<frame pos="10">
<descr>Central, Box 5</descr>
</frame>
<frame pos="11">
<descr>Footer</descr>
<defaultShowlet code="navigation_menu">
<properties>
<property key="navSpec">code(site_map)+code(contacts)</property>
</properties>
</defaultShowlet>
</frame>
</frames>In the example above we have an Internal Page with 12 frames (again, 0 → 11)
We have a number of default Widget namely search_form, navigation_breadcrumbs, navigation_menu while the remaining Frames were left free.
The menu placed in the Box #1 of the first column has been configured to display all the child pages originating from the homepage, while the menu in the footer displays the site map e the contact-us page.
<%@ taglib prefix="wp" uri="aps-core.tld"%>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="it">
<head>
<title>myportal|
<wp:currentPage param="title" /></title>
<link rel="stylesheet" type="text/css" href="<wp:cssURL />myportal.css"/>
<link rel="stylesheet" type="text/css"
href="<wp:cssURL />pagemodels/general.css"/>
<wp:outputHeadInfo type="CSS">
<link rel="stylesheet" type="text/css" href="<wp:cssURL /><wp:printHeadInfo />"/>
</wp:outputHeadInfo>
</head>
<body>
<div id="header-up">
<wp:show frame="0" />
</div>
<div id="header-down">
<wp:show frame="1" />
</div>
<div id="column1">
<wp:show frame="2" />
<wp:show frame="3" />
<wp:show frame="4" />
<wp:show frame="5" />
</div>
<div id="column2">
<wp:show frame="6" />
<wp:show frame="7" />
<wp:show frame="8" />
<wp:show frame="9" />
<wp:show frame="10" />
</div>
<div id="footer">
<wp:show frame="11" />
</div>
</body>
</html>As you can see, the Search Form and the Breadcrumbs menu have been included inside <div>, respecting the order declared in the XML configuration (Frame #0 and 1).
The following <div> tags organize the page in two columns: four Frames available in the first and five in the second. The last frame (#11) is inside a <div> on its own.
All the material here contained is published under the GNU Free Documentation License v1.3
The Entando trademark and logo are registered trademarks of Entando, srl. All
Rights Reserved.
All other trademarks are the property of their respective owners.