The User Interface software package

Overview

The software in WordFrame Integra platform is organized in so called software packages. The package manager enables you to install, uninstall or update those packages, while complying strictly with the dependency policy of the software package developer.

It automatically checks and synchronizes its package collection from the software repositories it is subscribe to. You should regularly update your system in order to apply important security and bug fixes.

Each software package has the ability to be signed by its vendor in which case its integrity and vendor could be guaranteed.

The UI package provides skins and layouts to the system. The package includes CSS, layout XML, images, javascript, favicon and other files needed for the proper organization and presentation of the page contents and is managed by the master page.

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, less, js and images between all skins)
    • images ( (optional) you can create your own folders here)
    • styles.css (the CSS of the skin. Needs to be included in the head.meta to be used)
    • styles.less ((optional) LESS files will be automatically generated and cached on the first page load)
    • file123.css ( (optional) a skin can include multiple CSS files. All need to be included in the head.meta)
  • 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 (depreciated - the layout template in XML format)
      • layout.html (new - the layout template in HTML 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 skins)
  • 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)

Description of the UI pack files

wfpackage.info file

a XML file with the packages description. IMPORTANT: This file is mandatory, if missing, the platform will consider this archive as invalid wordframe packages. Read more about this file

wfpackage.signature file

This file is generated by the packing program and cannot be edited by hand. It is used by the Integra platform to verify the vendor, package integrity and information. Read more about this file

head.meta file

For implementing a layout or a skin you may 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. We often 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 (depreciated)

The old way of creating layout templates was in XML format. It is still used in some of our packages, but the layout.html template is widely adobted now. 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="content" id="content" class="main" />
	<wrapper>
	<![CDATA[
	</div>
	<div id="aux-body-bg"></div>
	]]>
	</wrapper>
</placeHolders>

layout.html file

The layout.html definition file is pure html. You can define regions by assigning them the rel="wfi" attribute. Then the system will render this file into a layout template by following these rules: 

• all contents of the <head> meta will be ignored
• in the <body> all HTML outside the defined regions will be preserved
• in the <body> all HTML inside the defined regions will be ignored

The result is that the system can generate the layout template right from your static HTML file.

<div id="top-nav" name="Top navigation" rel="wfi">  <!-- REGION, defined by rel="wfi" -->	
    <!-- The region WebFrames will be nested here -->
</div>

<div id="header" rel="wfi" name="Header" nowrap>  <!-- REGION, defined by rel="wfi" will not generate HTML because of the "nowrap" -->	
    <!-- The region WebFrames will be nested here -->
</div>

<div id="content-wrapper" class="layout-cs"> <!-- wrapper outside the region -->	
    <div class="row">

        <div rel="wfi" id="content" class="span19">  <!-- REGION, defined by rel="wfi" -->
            <!-- The region WebFrames will be nested here -->
        </div>
        <div rel="wfi" class="sidebar span5" id="sidebar">  <!-- REGION, defined by rel="wfi" -->	
            <!-- The region WebFrames will be nested here -->
        </div>

    </div>
</div>

<div id="footer">
    <div class="container">

        <div class="row" rel="wfi" name="Footer">	<!-- REGION, defined by rel="wfi" -->	
            <!-- The region WebFrames will be nested here -->
        </div>

    </div>
</div>	

Warning Nesting webframe regions is not allowed by the system and will result in pack installation error "Failed layout validation. Incorrect HTML or nested region definitions found!"

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 a skin folder only. The system will automatically use it on all pages that apply this skin.

The "editor.css" file will loaded after the default CSS ("content.css") so you can use it to override. It will influence the elements in this iframe only.

favicon.ico file

Favicon.ico could be inserted two ways. From the Core Administration or adding it to the common files of the package and including it into the skin meta.head