public Customize a User Interface package

Contents [-]

1 Use the UI package as a framework and override it with an external CSS files
2 Complete UI package customization

Use the UI package as a framework and override it with an external CSS files

This is the best approach for small customizations. It will keep the advantage of the UI pack being maintained and updated automatically. You need to maintain only the external css files that override the package ones.

To override a CSS file, you need to define the same CSS elements and load them after the original. In our case this is done by following these steps:

Log in to the WordFrame Integra Core Administration
Click on the "Builder" tab in the upper left corner
Click on the "Content components" menu in the main navigation bar
Click on the “Global meta tags” link in the “Content extensions” section on the left of the screen.
Click on the corresponding edit link of the "Meta HEAD bottom"
To define custom CSS overrides you have two alternatives:
- include external CSS files by pasting in the textarea declaration similar to
```
 <link rel="stylesheet" type="text/css" href="http://domain.com/css-folder/style.css" media="screen, projection" /> 
```
- embedding styles by pasting them in the textarea declaration similar to
```
 <style> div {background:none;} </style> 
```
check the checkbox for enabling the element
Press the Save button.
After the background job is finished you should see a green icon "ON" in front of the "Meta HEAD bottom" section

Complete UI package customization

The process of completely customizing an User interface is quite similar to the process of creating a new one from an existing template package. To do that you need to

Download the original UI package

Log in to the WordFrame Integra Core Administration
Click on the "Architect" tab in the upper left corner
Click on the "Software management" menu in the main navigation bar
Click on the "Customize packages" link in the "Software packages" section on the left of the screen
Click on the "download" link of the package you need to customize
If the package is not in this list, you need to install it first

Extract the UI package contents

You can extract the package contents by using a simple unzip program. More about the files themselves you can learn on this page. You need to additionally extract the repository.zip file to access the actual layout and skin CSS and XML files.

The UI Package folder structure and files

The standard folder structure of the UI packs look like this:

wfpack.info (the xml file with the pack meta details)
wfpack.signature (the pack integrity signature and vendor public key)
repository (the pack contents stored as .zip archive in the pack)
- common ( (optional) shared css, js and images between all skins)
- layouts ( includes all layout folders)
  - layout-1 ( the files of one layout)
    - head.meta (meta tags that will be embedded in all pages using that layout.)
    - layout.xml (the layout template in XML format)
    - screenshot.png (150x120 pixels thumbnail of the layout displayed to the admins)
  - layout-N (one UI package can have multiple layouts)
- skins ( includes all skin folders)
  - skin-1 (the files of one skin)
    - images ( (optional) you can create your own folders here)
    - head.meta (meta tags that will be embedded in all pages using that skin.)
    - skin.css (the CSS of the skin. Needs to be included in the head.meta to be used)
    - editor.css ( (optional) this is a CSS applied withing the WYSIWYG Editor box. No need to add it to the head.meta file, automatically used if present. )
    - file123.css ( (optional) a skin can include multiple CSS files. All need to be included in the head.meta)
    - screenshot.png (150x120 pixels thumbnail of the skin displayed to the admins)
  - skin-N (one UI package can have multiple layouts)
- static ( (optional) use for css development or implementation showcases)
  - homepage.html ( (optional) possible implementation example of the homepage styles)
- uipack.xml (the layout and skins definitions and folders)

Apply the needed changes to the CSS and layout files

You can change all the files and layouts according to your needs. The best approach that we are using is to install on a local system a dummy package with only layouts and skins with empty CSS files. The real files you can embed as an external CSS files as instructed in the previous section. In this way you can place them locally on your machine, edit them and see the changes immediately without the need to reinstall constantly new version of the package. Once you are ready, replace the empty CSS files with the production ones.

head.meta file

For implementing a layout or a skin you need to load CSS and JS files. You can define them by defining the meta tags that should be embedded in each page which uses the skin or the layout, which holds the head.meta file. All skin files have their own head.meta files as they need to embed their own CSS or JS scripts. In the normal case a layout folder contains a head.meta file too but it is empty. In our experience, we use it for embedding custom JS scripts for automatically generate columns heights or widths, but this is rarely needed.

There is one exception though. There is no need to add "editor.css" file to the head.meta in order it to be used by the system. If it is present in the current skin, it will be automatically applied by any WYSIWYG editor embedded in the pages that use this skin.

In these files there are two very important tags you should remember:

$PATH$- when used in the head.meta file, this tag will be substituted with from the system with the layout or skin current path. As an example, if you need to add to the "skin-1" head.meta file a css file located inside the "skin-1" folder you will insert the following statement into the head.meta:
```
<link rel="stylesheet" type="text/css" href="$PATH$/../../common/css/apps.css" media="screen, projection" />
```
$APP_PATH$- if you need to use file local to the system, but not included to the UI package, like ones uploaded through the Core File manager, you can define their location with the help of this tag. Example:
```
<link rel="stylesheet" type="text/css" href="$APP_PATH$/usf/css/apps.css" media="screen, projection" />
```

layout.xml file

The layout template is in XML format. The two most important elements are the wrapper and the region.

region - the region is the Integra page webframe holder. When the layout is applied all regions will be made available by the system for inserting webframes in them. They can have multiple webframes which will be rendered in their order in the region.
wrapper - when implementing design layout you need often additional wrappers around one or many webframe placeholders (regions). In the example bellow you can see that all the pages regions are surrounded by the "site-wrap" wrapper. The specific here is that because an XML v.1.0 is used you need to use CDATA around the wrapper contents.

<?xml version="1.0" encoding="UTF-8"?>
<placeHolders>
	<wrapper>
	<![CDATA[
	<div id="site-wrap">
	]]>
	</wrapper>

		<region name="top-navigation" id="top-nav" />
		<region name="header" id="header" />
		<region name="navigation" id="nav" />
		<region name="top-content" id="top-content" />

		<wrapper>
		<![CDATA[
		<div id="middle" class="layout-c layout-home">
		]]>
		</wrapper>

		<region name="content" id="content" class="main" />

		<wrapper>
		<![CDATA[
		</div>
		]]>
		</wrapper>
		<region name="bottom" id="bottom" />
		<region name="footer" id="footer" />
	<wrapper>
	<![CDATA[
	</div>
	<div id="aux-body-bg"></div>
	]]>
	</wrapper>
</placeHolders>

screenshot.png file

This image with width: 150px and height:120px will be presented to the site administrators as the layout or skin visual representation.

uipack.xml

This is the most important file in the UI package and should be placed in the repository folder. It defines for the system what skins or layouts are provided by the system and what is their location. If this file is missing or defines non existing layout or skin folders, the installation of the package will fail. If a skin or layout is not defined in this file, the system will not made them available to be used. An example of the file contents is provided bellow:

<?xml version="1.0" encoding="UTF-8"?>
<uipackage>
	<layouts>
		<layout>
			<name>Layout-1</name>
			<folderName>layout-1</folderName>
			<description>
			<![CDATA[
				As presented in the example folder structure above
			]]>
			</description>
		</layout>
	</layouts>
	<skins>
		<skin>
			<name>Skin-1</name>
			<folderName>skin-1</folderName>
			<description>
			<![CDATA[
				As presented in the example folder structure above
			]]>
			</description>
		</skin>
	</skins>
</uipackage>

In the example you can clearly notice the XML structure and elements of the uipack.xml. Each layout is defined in its own "layout" tag, with the specification for the layout name, description and folder inside the main layouts folder. The same applies for the skins too.

Editor.css file

The WordFrame Integra uses one of the best WYSIWYG editors to make your text input easy and intuitive. But this editor applies its own css for presenting the text and the images inside its textarea. You can manipulate this presentation by inserting a file named editor.css in the skin folder. The system will automatically use it on all pages that apply this skin.

The "editor.css" file will be automatically inserted by the system and there is no need to embed it into the head.meta file of the system.

Build the new UI package

To build the newly customized UI package and sign it for distribution you need to use the Wordframe Integra packaging tool. The specifics in the UI package type is that you need to have in the repository folder the uipack.xml file. This file will be later used by the install program to check for available layouts and skins in the package.