Documentation Template Development Guide Jahia EE v6.1 Jahia delivers the first Web Content Integration Software by combining Enterprise Web Content Management with Document and Portal Management features. Avril 2010 Jahia 9 route des Jeunes, CH-1227 Les acacias Geneva, Switzerland www.jahia.com The Company website www.jahia.org The Community website
Summary 1 Overview...4 1.1 Introduction...4 1.2 What s in this documentation?...4 2 Basic Concepts...5 2.1 Fields...5 2.2 Containers...7 2.3 Container Lists...7 2.4 Pages...8 2.4.1 Child Pages...9 2.5 Site...10 2.6 Metadata and Categories...11 2.7 Content Model...11 2.8 Content Object's Functionalities...12 2.9 Engines...14 3 Template Modularity...15 3.1 Development environment...15 3.2 Implementing a first basic template...15 3.3 Defining a set of templates...16 3.4 Declaring your content object types...19 3.5 Adding a new template...20 3.6 Template resources...20 3.7 Adding libraries and custom taglibs...22 3.8 Customizing error pages...22 3.8.1 Default Jahia error pages...22 3.8.2 How to add and customize site-specific error pages...23 3.8.3 How to override default error pages for a particular template set...23 3.8.4 The lookup sequence...23 3.9 Template Implementation guidelines...25 3.9.1 Have a design prepared...25 3.9.2 Use tags and Expression language as much as possible...25 4 Templates bundled with Jahia...27 Page 2 of 30
4.1 Installing template sets...27 4.2 Template sets bundled with Jahia...28 4.2.1 Web templates...28 4.2.2 Jahia TCK templates (Jahia Test Compatibility Kit)...28 4.2.3 Core templates...29 Page 3 of 30
1 Overview 1.1 Introduction Jahia delivers the first Web Content Integration software by combining Enterprise Web Content Management with Document Management and Portal features. By leveraging state of the art Open Source frameworks and libraries, Jahia offers a complete solution for developing, integrating, delivering, and managing content across intranets, extranets, and internets with a much lower total cost of ownership than proprietary systems. 1.2 What s in this documentation? This documentation aims to describe: how to start a new set of template, how to put in place the right structure, and the general guidelines in terms of template development. This section also presents the new template sets bundled within Jahia EE v6 which you can use as they are or make extensions in your own template set inheriting from the one bundled in Jahia EE v6. We advice to take these templates as an example in order to learn how to customize your own template set. Should you have questions, please do not hesitate to contact us as mentioned on our website (http://www.jahia.com) or Community website (http://www.jahia.org). Page 4 of 30
2 Basic Concepts Jahia's content management system allows users to declare the type of content they want to manage, in order to structure the data in a meaningful way. Many web-based content management systems simply allow users to edit free text on a page, without guiding them through any kind of structure. This last approach has its advantages, as well as drawbacks. The best way to illustrate how structured content may be useful to users is to illustrate this with a simple example: an address list. 2.1 Fields Let's say that on an intranet site you want to build a list of addresses. This list would be a very simple list of people, with a few predefined fields that are common to all users. Such fields could be: 1. first name 2. last name 3. street 4. zip code 5. city 6. country 7. phone number If this was to be stored in a free text form, there would be no way for the users of the content management system to use a uniform structure that would help them input the data in a structured way. In HTML free text for example the temptation would be great to use presentation tags such as tables or lists, but it would lack the semantic information. Jahia introduces the basic elements of Jahia fields, to allow users of the CMS (content management system) to structure their data. Fields may have different types, such as: Limited text Unlimited text List of user-selectable values Page 5 of 30
Date Number Color File (image, binary file) Portlet application The above list is not exhaustive, as the basic field types may be used for all kind of scenarios. Also, the list represents end-user data, meaning the type of data that the end-user will be able to input, but the actual content object used to store the types are a little different as we will see. The first thing we have to do is to choose the field type(s) we will use to store the address data. In order to keep things simple, we will use a limited text field to store each address field. In Jahia the type to store limited text is called smalltext field, and is able to store up to 255 characters. You can find a list of fields in Jahia Compact Nodetype Definitions notation guide. Fields are defined in Jahia using an identifier called the definition name. This name must be unique within the current context, which in Jahia EE v6 is the current container. A field definition name may also be seen as the sense we give the field value, meaning we give the value semantic information by giving it a name. So for our address fields, we can now manage them using field types and definition names. It is recommended to use definition names that do not use spaces, and generally we recommended following the Java CamelCase naming convention (first letter in lower case, and every new word starts with an upper case character). Address field Jahia Field Type Field definition name first name smalltext firstname last name smalltext lastname street smalltext street zip code smalltext zipcode city smalltext city country smalltext country phone number smalltext phonenumber Page 6 of 30
2.2 Containers Jahia allows fields to be grouped into a logical entity called a container. A container may include any number of fields, as well as sub container lists (which we will define later on). As example we will use a container to represent an address. The grouping of fields in containers also defines the ordering (or ranking) of the fields within the address, which will be used by Jahia's edition tools to present the content to the user. This way when a new address must be entered, the order of the fields presented will match the order of the fields when declaring the address container. There is also a possibility to define the order and grouping of fields, by using a definitions.grp file. Just as we were able to identify various fields by a definition name, a container definition may also include a name. In this case the most obvious name for the container would be address, since this is what our logical grouping of fields will represent. So in effect we have a container definition that looks something like this: The container structure we have defined will be used to present to the user for data input. Containers are really a way to define structured grouping of fields, as well as being entries in container lists. 2.3 Container Lists A container list is simply a list of containers. It also defines an order, which by default is the order in which the containers were added to the container list. Container lists may only be composed of containers of a specific definition. In our example, the container list would be an address list, and only our current definition would be accepted as valid entries for the container list. Contrary to containers and fields, container lists do not have definition names; they are simply referred to using the container definition name, which is fine since a container list may only contain one type of container. Container lists cannot be created or deleted by end-users in Jahia, they are objects whose life cycle is automatically managed by Jahia. The system will automatically create the container list when the first container is created, and container lists are deleted once the parent object is deleted. The parent object of a container list is usually a Jahia page, but may also be a container. The possibility to embed a container list within a container is a powerful mechanism to create complex structures. Page 7 of 30
In order to embed container lists within a container, we need to define a container structure that includes another container structure. As the above example illustrates, we can mix fields and sub container lists within a container structure. It is possible to include several sub container lists of different structure within a container, provided we have declared the container to allow for such a sub-container structure. One advanced way of using such a structure would be to use a field to define the sub-container list to display what would look like a varying structure. This technique is used for Jahia s box container structure, which in Jahia EE v6 is more elegantly supported with some easy-to-use tags. It is perfectly allowed to define more than one level of sub-container structures. On the end-user side, the user will be presented with the interface to add containers in the top level container list. Once he has added a container, he will be presented with the possibility of adding subcontainers for the container he has just added. Most of the time containers lists will have as a parent object simply a Jahia page, which will be the next object we will introduce. 2.4 Pages A page in Jahia can be viewed as something similar to an HTML page. When a page is created, it is associated to a template, which will define the structure of the content in the page, as well as how it should be displayed. The page template will generate the full HTML for the page display, and pages may be added to a web site dynamically, to easily extend the information presented. A page template has two responsibilities: 1. declaring the content structure for the page 2. rendering the instances of the content objects that comply to the structure When a new page is created in Jahia, the content structure is used to present all the corresponding user interfaces for input of new data. The next step is to load all the existing instances of content objects and to display them (of course there won't be any for a brand new page, but there are cases where objects will be created automatically upon first access, like in the case of mandatory containers). The rendering part of the template basically queries Jahia for any existing container lists, and then iterates through the containers, retrieving the field values and displaying them. In the case of containers that include container lists, the same process is repeated. Page 8 of 30
Until Jahia 5 the content definitions were done directly in the templates by using tags. From Jahia EE v6 onwards, content definitions are externalized in one or more Java Content Repository (JCR) inspired CND files. It is still possible to add new field definitions at any time, but it is not allowed to change the data type of an existing definition once data has already been captured. When removing a field definition from a container definition, the already captured data will not be completely deleted, but will only be deactivated. If you again add the removed field definition to the container definition, the previously captured data will be accessible again. Finally we will see later in this guide, how to access content in absolute or relative ways, in order to share content between different Jahia pages. 2.4.1 Child Pages One of the particularities of Jahia pages is that child pages are not direct child objects of their parent page. Rather child pages are children of a field type called the pagefield. The logic behind this design is that navigation can be constructed using containers, and so it is possible to have children pages in different container lists on a page, making for a very flexible hierarchy model. This is the standard way for building navigation in Jahia templates. One of the nice side effects of this model is that the ranking (ordering) of containers can be used to set the ranking of the child pages, since they are simply referenced through a page field. In this example we have presented the page field as capable of storing a child reference (also called direct page type) to a page, but the field is also capable of storing link references, which behave as a link to an existing Jahia page anywhere on the web site. Finally the page field is also capable of storing an URL to reference an external web site. Page 9 of 30
2.5 Site A Jahia site is a logical entity that regroups the following data: a set of templates a set of users a set of groups a set of portlet applications a site key an optional site host name (such as demo.jahia.org, where demo would be the site key on the server serving all the *.jahia.org Jahia virtual sites) a home page (the entry page to the site) a search engine index a set of languages in which the content may be input The administration of a Jahia virtual site will be covered in the Jahia Administration Guide. The important points relating to template development are the set of templates that are made available for a Jahia site and the site home page. The set of templates is simply a list of templates that the end-users will be able to use when creating new pages. It is possible to deploy new templates in a site while the system is running. The site's home page is simply the entry point into the virtual site. It is automatically created by Jahia, using the default template when creating a new site. Page 10 of 30
2.6 Metadata and Categories Jahia defines a set of metadata fields (Dublin core) for each page, container list and container. These are defined in the applicationcontext-metadata.xml file. If you need additional metadata fields you may extend the configurations there. A field of type category is directly mapped to the category tree. You can have several different category fields per content object linking to a tree of categories (e.g. classification, category, etc... fields). Template developers are now also capable of defining the entry point in the category tree for each category field. So you are not forced any more to start at the category root level. We also introduced permissions on each node of the category tree in order to restrict the use of certain sub-tree to certain users only. 2.7 Content Model Now that we have presented the basic content structure that is available in Jahia, we will present a summary of the organization of content on a typical Jahia site. In the above drawing, the content object types are indicated in between parenthesis, while the name before varies on the object type: Page object: the name in the graph is the actual display name of the page. container list object: we have no name for this object, so that is why only the type is indicated container object: the name is the container definition name field object: the name is the field definition name The above object tree includes only fields grouped in containers. Fields directly attached to a page have been deprecated in Jahia 5 and are not allowed since Jahia EE v6. Also on the right part of the tree we see a navigation hierarchy, which contains child page reference fields that point to the About Us and Product sub-pages. The only feature not illustrated in this object model, are container lists contained in containers, but they were illustrated previously. Another way of defining the format is to present embedding possibilities: pages may contain container lists container lists may only contain containers containers may contain fields and/or container lists Page 11 of 30
2.8 Content Object's Functionalities Jahia's content management system primarily deals with content objects, these include: pages container lists containers fields As we have seen these content objects may be combined together to build complex content structures using templates that contain their structure definitions. Content objects also share common functionalities that the end-user can interact with, that cover a wide range of functions such as access control, versioning, and so on. Here is the list of features available on all content objects: Feature name ACL (Access control lists) Staging (workflow states) Description Access controls lists allow users to define a list of users and/or groups that may be given/refused permission to either read, write or administer (delegate rights) a content object. For example by removing read access to certain containers for certain users, we can personalize access to the container. The rights on fields are stored at the container list level, that means that fields based on the same field definition have the same right in all containers of the container list. Content objects may go through intermediate stages of workflow before being published live. Usually a new content object will first go to a staging state, then a waiting for validation state, and finally to a live state if it was accepted, or back to staging state if it was refused. Since Jahia 5 you can also define different workflows on up to a per-object basis, so you can for instance define custom N-step workflows or No workflow for immediate publishing or even an External workflow. Versioning Every time a content object is validated, the previous version of the content object (including all it's sub-objects) is versioned, making it possible to later retrieve the state of Page 12 of 30
the content object by restoring the state at a specified date. Locking Multi-language DublinCore Metadata support In-context Copy/Paste option Content Picker (dynamic and static copies) XML Import/Export feature Indexation and score boost Content objects are locked to prevent editing either if another user is currently already modifying the same object, or if the object or one of it's ancestors is in the waiting for validation workflow state. Content objects may either have different values for each language or share their content in all the languages (for example container lists and containers share their content in all the languages, but not all fields do). Since Jahia 5 every container list, container and page has a set of expandable metadata fields attached, which are based on the DublinCore standard (http://en.wikipedia.org/wiki/dublin_core), such as the author name, the publisher name or the creation date. Every content modification or validation is then automatically stored and indexed in the Jahia CMS. You can now easily copy and paste content throughout a site, be it a single container, a container list or a whole section of a site. Jahia will check for "compatibility" between the source content and the target, to only allow you to paste it when similar definitions are used. A content picker has been integrated on top of the XML import/export feature. The content picker allows any author to easily find and reuse existing content on another page. The author has the choice to make a static copy of the existing content (no link) or a dynamic copy (each change on the source will impact the destination). A new XML import/export feature will allow any user to export some Jahia content (a container, a full list, a page or a whole virtual site) and to import it elsewhere (including on another Jahia server). The XML import/export tool will also manage "diffs" and only import changes from a certain date. The content in Jahia is automatically indexed (unless you mark a field as not indexable) and since Jahia 5 you can also set a search score boost factor to content objects. From Jahia EE v6 onwards you can configure term analyzers on a per field level. Page 13 of 30
2.9 Engines One of Jahia's core components is the engine. An engine is a functional unit, which performs specific tasks usually requiring user interactivity. Engines are formed by a set of one or more classes and/or JSP files. For readers familiar with Struts, engines are similar to Struts Actions. In Jahia every operation carried out by the users utilizes an engine. For example, the login operation, the user registration, searching, adding or updating content, updating page properties and so on. A simple way to spot which engine is being used for each operation is to check the current URL. It will typically contain the following identifier /enginename/ and a following keyword which names the engine. Jahia parses the URL and uses the engine identifier to dispatch incoming user requests to the appropriate engine. The point of entry of an engine is usually its *_Engine.class file. This class carries out all the flow control for that particular engine. Typical operations include loading/saving data into the database, verifying submitted form data, loading data into the session and carrying out most of the control logic. An engine can also call other sub-engines (i.e. update container engine calls field-specific engines). The engine class will then usually use an external JSP to render the user response. For example, for the user login, the org.jahia.engines.login.login_engine.class checks the current user status and forwards the request to the login.jsp page. From there, the user submits his login details which are processed by Login_Engine.class. If an error is detected, the user is forwarded to bad_login.jsp, if the login is successful, the user is forwarded to login_close.jsp which closes the login popup and forwards him to his main page. Page 14 of 30
3 Template Modularity This section aims to rapidly describe how to start a new set of template, how to put in place the right structure, and the general guidelines in terms of template development. 3.1 Development environment Before starting the development of your set of template, make sure you have the required environment and applications installed as described in article Configure Jahia for template development. In summary, you will have to install a JDK, Maven and the latest release of Jahia EE v6. Then, using the jahia-templates-archetype or jahia-web-templates-archetype, you will be able to create the structure of your template set project. 3.2 Implementing a first basic template Once your development environment is set up and your template project created, the first step to do is to implement a first template. In order to do that, simply create a home.jsp which will be the template for the home page. The simplest home template could look like this: <%@ page language="java" contenttype="text/html;charset=utf-8" %> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional //EN" "http://www.w3.org/tr/html4/loose.dtd> <html> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8"> <title>my home page</title> </head> <body> <h1>this is my home page</h1> </body> </html> Once you have implemented this first basic template, you will need to declare it in the templates.xml descriptor file. Notice that this is just a demonstration and that your final templates should use the tags <template:template>, <template:templatehead> and <template:templatebody> to create the HTML. Page 15 of 30
3.3 Defining a set of templates Templates are coded using JSP (Java Server Pages) and have to be declared in a descriptor file called templates.xml. The file from our default set of templates community templates looks like this: <?xml version="1.0" encoding="utf-8"?> <template-set xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns="http://www.jahia.net/jahia/templates" xsi:schemalocation="http://www.jahia.net/jahia/templates http://www.jahia.net/shemas/templates_2_0.xsd"> <package-name>community templates</package-name> <root-folder>community_templates</root-folder> <provider>http://www.jahia.org</provider> <thumbnail>images/preview.gif</thumbnail> <resource-bundle>jahiatemplates.community_templates</resource-bundle> <definitions-file>definitions.cnd</definitions-file> <rules-file>rules.dsrl</rules-file> <common-pages> <my-settings>mysettings.jsp</my-settings> <search-results>searchresult.jsp</search-results> </common-pages> <templates default="simple" homepage="home"> <template name="home" display-name="home page" filename="home.jsp" page-type="community_templates:home"/> <template name="news" display-name="news" filename="news.jsp" page-type="community_templates:news"/> <template name="simple" display-name="simple" filename="simple.jsp" page-type="community_templates:simple"/> <template name="double" display-name="double" filename="double.jsp" page-type="community_templates:double"/> <template name="full" display-name="full" filename="full.jsp" page-type="community_templates:full"/> <template name="webapp" display-name="webapp" filename="webapp.jsp" page-type="community_templates:webapp"/> <template name="faq" display-name="faq" filename="faq.jsp" page-type="community_templates:faq"/> </templates> </template-set> As you can see, the above file is an XML file following a specific XML Schema. This means that your templates.xml file should start with the following lines: Page 16 of 30
<?xml version="1.0" encoding="utf-8"?> <template-set xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns="http://www.jahia.net/jahia/templates" xsi:schemalocation="http://www.jahia.net/jahia/templates http://www.jahia.net/shemas/templates_2_0.xsd"> Then, the idea is to describe your set of templates. In order to do that you need to specify a name and a folder, which are two required elements. The package-name is the name of your set of templates, where as the root-folder is the directory where the set of template is held. Just create these two lines as follows. <package-name>my templates</package-name> <root-folder>my_templates</root-folder> You also have other optional elements you can specify in your descriptor. In particular above example, these elements are: <provider>http://www.jahia.org</provider> <thumbnail>images/preview.gif</thumbnail> <resource-bundle>jahiatemplates.community_templates</resource-bundle> <definitions-file>definitions.cnd</definitions-file> <rules-file>rules.dsrl</rules-file> <common-pages> <my-settings>mysettings.jsp</my-settings> <search-results>searchresult.jsp</search-results> </common-pages> Here is the purpose of the above optional elements: provider: Provider of the set of templates thumbnail: Preview image of the set of templates shown when creating a site resource-bundle: Resource name to use for this set of template definitions-file: Content type definition file to use for the set of templates rules-file: Rules file to use for catching and handling events common-pages: Specify what jsp file should be used to display user's settings and search results. Page 17 of 30
There are also other elements you can use which are listed below: description: Describes the set of templates extends: If the set of templates should extend another existing one, here is where to put the parent set name initial-import: If you want an import to be launched upon site creation, you can provide the path to that import file here Then, you also have to use the templates and template elements to specify your templates. The default attribute on the templates element indicates what should be the default selected template when you create a new page. The homepage attribute indicates what template should be used by Jahia when it creates the home page of a site. For each template, you then have to specify what is its name (identifier), what is its display-name and to which page definition type it is bound (see Declaring your page types). You can also provide additional information using the description attribute. Finally, if you want a template to be hidden when users are adding new pages, you can set the visible attribute to false. Using the template we created in the previous chapter, you can simply declare it as follows. <templates default="myhomepagetemplate" homepage="myhomepagetemplate"> <template name="myhomepagetemplate" display-name="home" filename="home.jsp" page-type="my_templates:home"/> </templates> At this stage, we still need to define what are going to be our content object types, and in particular the type my_templates:home. Page 18 of 30
3.4 Declaring your content object types With Jahia EE v6 it is no longer possible to declare content definitions within the templates. This has to be done in an external file and use the Compact Node Type notation (CND), introduced by the JCR-2 specifications. It is required to read and understand this notation described in the article Externalized content definitions before going any further. If you now open the definitions.cnd file of your community templates, you will find, among others, the following definitions. <community_templates = 'http://www.jahia.org/jahia/community_templates/nt/1.0'> [community_templates:headermodule] mixin containerlist basiclink (community_templates:basiclink) containerlist imagelink (community_templates:imagelink) singlecontainer logo (community_templates:logocontainer) [community_templates:home] > jnt:page, community_templates:headermodule containerlist maincontentbox (jnt:maincontentcontainer) containerlist navlink (jnt:navlink) containerlist columna_box (jnt:filesbox,jnt:textsbox,jnt:linksbox) containerlist columnc_box (jnt:linksbox,jnt:textsbox,jnt:linksbox) singlecontainer footer (community_templates:footer) singlecontainer edito (community_templates:edito) containerlist news (community_templates:communitynews) The above lines define a new mixin type called community_templates:headermodule and a new page type called community_templates:home. The latter derives from the generic jnt:page type, thus declaring a new page type, and from the community_templates:headermodule, telling Jahia that this module should be used and available in templates of type community_templates:home. This allows to reusing common and shared nodes as it is possible to do when we include a same jsp file in different templates. Coming back to our example with our basic home page, we have to create a file called definitions.cnd in our set of templates, and then put in the following lines: <my_templates = 'http://www.mydomain.org/my_templates/nt/1.0'> [my_templates:home] > jnt:page containerlist navlink (jnt:navlink) Page 19 of 30
The home definition simply contains a navigation list in order to be able to create other pages. Once you have done this, you are ready to package your set of template and deploy it into the Jahia EE v6. To do that, follow the instructions in chapter Configure Jahia for template development, section Deploying the Templates to the Jahia Server. You will have to restart the Jahia server before you can use your new set of templates. 3.5 Adding a new template In order to add an additional template to your set of templates, you will have to achieve the following tasks: 1. Create a jsp file containing the minimal html code to work in a browser 2. Edit the templates.xml file adding a reference to your template 3. Modify the definitions.cnd file in order to declare the content object types you need in your template 4. Deploy the new template to the server in order to make it available in Jahia 3.6 Template resources Before going into too many details about template resources, we first need to review the directory organization of your template project. Following the war structure of Maven 2, the directory structure will be the following: community-templates - src - main - resources - jahiatemplates - webapp A set of template usually comes with a set of javascript, css and image files. These files should be put in the template set in order to be available and used within Jahia. In particular: All jsp files, javascript files, css files and others have to be put in webapp. All resource bundles files have to be put in jahiatemplates Page 20 of 30
Regarding css and images, be aware that you will have to follow a particular directory structure if you want to define different themes in your set of templates (see next section). Basically, the template set organization should look like this, for the webapp part: webapp - common - images - theme - blacktheme - css - img - scripts - orangetheme - css - img - scripts - skins - alertskin alertskin.jsp - blueskin blueskin.jsp - redskin redskin.jsp definitions.cnd templates.xml rules.dsrl home.jsp If you follow the above organization, Jahia will automatically pick up that you are defining two themes and three skins. In order to use the skins, your content objects will have to be declared as skinnable (jmix:skinnable). The user will then automatically have a drop-down list available in the engine that allows to select a particular skin for the object instance. Themes have to follow the above structure. The theme name will be the name of the root folder. You can provide several different css files for a theme, Jahia will load theme automatically if you use the themedisplay tag, in the head part of the template. Page 21 of 30
3.7 Adding libraries and custom taglibs If you want to use a library, which is not by default present in Jahia, you will simply need to perform the following simple task: Add the jar file on the application server in the WEB-INF/lib directory of the Jahia webapp In case you want to add an external taglib, here is what you need to do: Copy the jar file of the taglib in the WEB-INF/lib directory Copy the tld file of the taglib in WEB-INF/etc/taglibs, if the file is not already included under the META-INF directory of the jar file Optionally add a reference to the tld file in the WEB-INF/web.xml file. It is not necessary if the tld is under the META-INF of the deployed jar. 3.8 Customizing error pages Whenever the user tries to access a non-existing page, or a page he doesn't have the right to see, an error page will be displayed with the corresponding and relevant error code. The user will also get an error page displayed if there is an error in the templates or even within the Jahia engines. These pages can be customized per site or per template set. 3.8.1 Default Jahia error pages Error pages are located in the following folder: /jsp/jahia/errors/ The default page is "error.jsp". There are a couple of other pages, depending on the response status code (if it is available): error_401.jsp - the guest user is trying to access the resource, which requires authentication error_403.jsp - the user has no sufficient permissions to view the requested page error_404.jsp - the requested resource cannot be found on the server error_500.jsp - internal server error Page 22 of 30
3.8.2 How to add and customize site-specific error pages Site-specific error pages are located in the following folder: jsp/jahia/errors/sites/<sitekey>/ where <sitekey> is the key of the current site. The site key is defined when you create a virtual site, from the administration panel. For example, if a custom 404 error page needs to be provided for a Community Portal site with the site key community, the following page should be present: jsp/jahia/errors/sites/community/error_404.jsp Site-specific error pages can be disabled if needed by setting the flag site.error.enabled in the WEB- INF/etc/config/jahia.properties file to false: site.error.enabled = false 3.8.3 How to override default error pages for a particular template set The template set should include an error page JSP in the errors folder. e.g. if the Community Template-set (with the root folder community_templates) needs to override error_401.jsp, the customized JSP should be placed under: jsp/jahia/templates/community_templates/errors/error_401.jsp You can also benefit from the template set inheritance feature in this case. I.e. the customized error_401.jsp will be used (if not overridden) in all template sets, which extend Community Templates in our example. 3.8.4 The lookup sequence The following sequence is used to lookup an error page: 1. site-specific error page 2. template set error page 3. default error page For example, in case a 404 error occurred for a site with the key community and template set Community Templates (with the root folder community_templates), the following paths will be tested (the lookup procedure will stop when the resource path is found): Page 23 of 30
jsp/jahia/errors/sites/community/error_404.jsp jsp/jahia/errors/sites/community/error.jsp jsp/jahia/templates/community_templates/errors/error_404.jsp jsp/jahia/templates/community_templates/errors/error.jsp jsp/jahia/ errors/error_404.jsp jsp/jahia/ errors/error.jsp Page 24 of 30
3.9 Template Implementation guidelines In order to have a readable and maintainable set of template, it is strongly recommended to follow the these guidelines. Indeed, after a decade of experience in template development, the Jahia team has reached the following conclusions: 3.9.1 Have a design prepared Before starting your template implementation, you need to know what your site is going to look like. The best start is to have an HTML/CSS based static mockup of the site. Based on that, you will then be able to start creating templates using the correct design and HTML structure. 3.9.2 Use tags and Expression language as much as possible Jahia offers different taglibs containing handy tags in order to manipulate everything related to Jahia. You will be able to display content objects, paginate a container list, display a navigation menu, etc. using tags developed by the Jahia team. In addition, Jahia strongly uses the JSTL tags and Expression Language inside its templates. Scriptlet code is to ban as much as possible: it is harder to support and maintain and complicates migration, so you should really do the right thing from the beginning, by using the provided tags, or implementing your own. You will find a good example below, with the code of the home template coming from the Core templates: <%@ page language="java" contenttype="text/html;charset=utf-8" %> <%@ include file="common/declarations.jspf" %> <template:template> <template:templatehead> <%@ include file="common/template-head.jspf" %> <utility:applicationresources/> </template:templatehead> <template:templatebody> <div id="header"> <template:include page="common/header.jsp"/> </div> <div id="pagecontent"> <div class="content3cols"> <div id="columna"> <template:include page="common/loginform.jsp"/> Page 25 of 30
<template:include page="common/box/box.jsp"> <template:param name="name" value="columna_box"/> </template:include> </div> <div id="columnc"> <template:include page="common/searchform.jsp"/> <!-- in HomePage we display site main properties --> <div class="properties"> <utility:displaysiteproperties/> </div> <template:include page="common/box/box.jsp"> <template:param name="name" value="columnc_box"/> </template:include> </div> <div id="columnb"> <!--news--> <template:include page="common/news/newsdisplay.jsp"/> <div> <a class="bottomanchor" href="#pagetop"> </div> </div> <utility:resourcebundle resourcename='pagetop' defaultvalue="page Top"/></a> <br class="clear"/> </div> <!-- end of content3cols section --> </div> <!-- end of pagecontent section--> <div id="footer"> <template:include page="common/footer.jsp"/> </div> </template:templatebody> </template:template> Page 26 of 30
4 Templates bundled with Jahia Jahia EE v6 is bundled with template sets, which you can use as they are make extensions in your own template set inheriting from the one bundled in Jahia take them as example to learn how to do your own templates There will be more template sets available soon and downloadable from our website. 4.1 Installing template sets When installing Jahia, existing template sets are bundled with the product. There are even small demo sites prepackaged. When creating a new site, you can either choose to import the prepackaged sites, based on the provided template sets, or you can create an empty site and choose the template set you want to use. The template sets described in the following paragraphs can be found on the Jahia server after installation in the directory: <jahia-home>\webapps\root\jsp\jahia\templates In order to use your own template sets on site creation, you have to deploy it (like described in Deploying the Templates to the Jahia Server or Deploying Templates to Jahia Server from Eclipse ), before starting the Jahia server. Page 27 of 30
4.2 Template sets bundled with Jahia 4.2.1 Web templates The Web templates are succeeding the Corporate portal templates used in Jahia 4 and 5. They provide similar functionalities but have been redeveloped from the ground up. The implementation has no scriptlets and is thus easier to understand. The CSS design is much cleaner, so that the look & feel can easily be completely changed with solely refactoring the CSS. The new template sets implement some of the best practices for Jahia templates and should also be a used as model/sample usage of Jahia. Thus these templates may be used in production environments. If you decide to use them for your project, but want to change the style or add some new features or add templates, then we recommend creating a new template set project, which inherits from our Web templates. This way you will be able to easily deploy future upgrades or hotfixes of the web templates set, because you will hardly have to do any merges with your changed template versions. There will be a detailed article about how to change the look & feel or make extensions to the Web templates. 4.2.2 Jahia TCK templates (Jahia Test Compatibility Kit) The bundled TCK templates are, as its name suggests, just test templates. They are not intended to be used by real projects, although some ideas or code snippets can be used via copy & paste. The intention of the templates is to create a simple template set to use for our automatic tests. The number of templates will grow as we will try to have templates for all Jahia features as the other template sets are using just a subset of Jahia features. Do not expect that the TCK templates are error free or show excellent performance: with this template set we sometimes try to push the limits of Jahia and use rarely used features. Also we may have added test templates to prove and reproduce bugs, which are of a lower priority and will only be fixed in the next Jahia releases. The TCK templates are also used along with our Jahiapedia documentation, so you will often see articles with links to our TCK demo site or links to TCK template sources in order to demonstrate, how some feature works in practice. Page 28 of 30
4.2.3 Core templates The Core templates are also bundled with Jahia, because the TCK templates derive from them in order to test template inheritance. The Core templates are very simple templates, which could be a good starting point for beginners to quickly understand the structure of templates and the usage of Jahia tags. Page 29 of 30
9 route des Jeunes, CH-1227 Les acacias Geneva, Switzerland www.jahia.com The Company website www.jahia.org The Community website