Graphic integration

Prerequisites
Some technical knowledge is required for the graphical integration of a Ametys application. In particular, knowledge of the following languages is essential: XML, XSLT, HTML and CSS.

Graphic integration involves personalizing the display of pages and content for visitors. All page, content and service renderings on a site managed with Ametys are defined by XSLT and CSS style sheets.

The XSLT style sheets use the XML data supplied by CMS to generate HTML to display the web page.

Stylesheets CSS are used to define the graphic styles, colors and images that dress up pages, and are often accompanied by javascript files that complete the graphic behavior of the various renderings.

A Ametys website is made up of pages built around templates (xsl). These templates contain zones that allow contributors to add content or services to the page.

Three types of input data are therefore possible:

• The contents
• Services: content feed, RSS, calendar, etc.
• Dynamic Input Data (context-dependent): sitemap, filters, user preferences, etc.

All this data is aggregated in a XML file, in which content and service data are organized according to the zones in which they have been inserted. The template.xsl file ( XSL template style sheet), combined with content, services and dynamic data(Input Data), is used to build the HTML website pages.

Rendering processing order
It should be noted that content and services are first processed by their own XSLT rendering stylesheet. They are therefore first transformed into HTML before being integrated into the global XML file.

Tip
This XML file is dynamically generated and does not actually exist on the server. To view it and make it easier to write style sheets XSLT, add ?cocoon-view=content to the page'sURL , in preview mode.

To sum up, the graphic integration of a Ametys application comes down to :

• create templates and zones,
• customize the rendering of content and services inserted in these zones,
• if necessary, create labels to add data to Input Data to organize pages and content,
• configure the various options available to contributors to create their own pages and content, while respecting the defined graphic charter.

Definitions

In the Ametys vocabulary, a graphic charter (assigned to a site) is called "skin"a template (assigned to a page) is calleda "template" and is made up of"zones".

Zones can be filled with"content" or"services" whose renderings are called"views".

Each content or service can have several views, depending on its location in the site, the page template, etc.

Graphic charter

A complete graphic charter in Ametys is defined by :

• graphic charter description (name, description and preview thumbnail),
• template declaration,
  • definition of static and dynamic template elements (navigation, header and footer, breadcrumb trail, etc.)
  • the definition of zones where contributors can insert their content and/or services,
  • configuration of available content and services by zone and template,
  • configuration of templates selectable by contributors,
  • the creation of content and/or page filters (to create content and/or page feeds),
• the creation of labels for content and/or page filters in templates,
• customized rendering of content and services (default: 3 renderings per content and at least 1 rendering per service),
• the creation of new views of content and/or services,
• the creation of all styles usable by contributors in the rich content editor (from the transformation of Docbook format into HTML code, to the customization of buttons),
  
  • paragraph styles,
  • styles for each title level,
  • link styles according to the nature of the link (link to an address mail, link opening a new window, link to a downloadable file, etc.),
  • image styles,
  • table styles.
• translation of all terms used in the public site (so-called internationalization files)

Organization of the graphic charter

To find out how a graphic charter is organized in CMS Ametys , go to Graphic charter organization.

Defining templates and zones

A graphic charter has one or more templates. Any page containing information is necessarily associated with a template. It is this template that displays the different zones where the contributor can insert content and/or services. Graphic charter integration therefore requires the creation and configuration of templates and zones. For more information, see Template definition.

Labels

Labels are used to display pages or content managed by Ametys in a display zone defined by the graphic charter. For example, navigation menus are generally managed by a set of labels.

These tags are also useful for filtering or sorting content through the use of services or static filters.

These labels can also be used to define a page in the sitemap for special treatment. For example, import an additional style sheet to vary the colors of the same template.
To find out more about declining styles, see Declining templates.

All these chart labels are defined in the file cms/skins/[skinName]/conf/tag.xml.
For more information on defining chart labels, see Chart labels.

Content and services

Content is made up of a set of input fields, including rich fields, which are then displayed in a structured way.

Services are a set of parameters that enable elements stored in the database to be placed or used in a different context, such as a content feed, a word cloud, a site map...

Content types or services are available to contributors to supply and manage the site. They can be inserted in pages whose template contains at least one zone accepting this element.

Most content and services have a parameter named"view" or"display mode" allowing contributors to choose which style sheet to use when rendering. By default, there are 3 views for content ( full view, summary view and link view), and at least one display mode per service. You can override existing views or create new ones. For further information, please consult the pages Graphic rendering of a service and Graphic rendering of a content.

It may be useful to know about the various XSLT variables that can be used in a chart's XSL files: see the Variables page XSLT.
Similarly, Ametys offers a number of methods for accessing different values in the application: see the AmetysXSLTHelper page.

To manage sites in different languages, it is important to internationalize all messages: see the Internationalization page.

Styles

All the resources used in the graphic charter can be found in the cms/skin/ [skinName]/resources/ folder.

Ametys imports the jquery, jqueryui and pirobox frameworks as standard; you can override their rendering, choose another theme or add any other framework. For more information, see Template writing (Overloading useful templates).

Rich field styles

By default, rich content fields feature a minimum number of buttons and menus to control the rendering of images, text, links and other objects HTML . Style options can also be added.
To find out more about implementing editor styles, see Configuring the rich editor.

Getting started

To get started, a demonstration chart is available for integrators: the graphic chart called "demo".

Other charters are also available: 

https://code.ametys.org/projects/WEB/repos/skin-doc/browse

https://code.ametys.org/projects/WEB/repos/skin-intranet/browse

https://code.ametys.org/projects/WEB/repos/skin-intranet-cards/browse

https://code.ametys.org/projects/WEB/repos/skin-workspaces/browse