public Create a User Interface package from blank

Contents [ show ]

Summary

To create an UI package from blank you will need to constantly check your work, while extending the CSS classes. Achieving that with a constant process of updates is not the best alternative as you will lose a lot of time in packing and installing. The approach that proves most efficient is to create initially a UI packages with only layouts and empty CSS file. Afterwards with the help of the Builder's functionality "Global meta tags" you can insert an external CSS file from your CDN or localhost. In this way all the changes that you make will be immediately visible in the site.

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)

Description of the UI pack files

wfpackage.info file

You can read more about this file on this location

 

wfpackage.signature file

You can read more about this file on this page

 

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.

Last edited by Boz Zashev on 20 Dec 2010 | Rev. 52 | This page is public | Views: 1
Comments: 0 | Filed under: Software management | Tags: