Build UI package - from scratch

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.

Step 1 - Create the folder structure

The initial folders we will need to create before the start are:

package working folder (the folder that will hold your work and that will be submitted to the package tool)
- repository (the pack contents stored as .zip archive in the pack)
  - common ( shared css, js and images between all skins)
    - css ( common for all skins css)
    - images ((optional) images you may need)
  - layouts ( includes all layout folders)
    - layout-1 ( the files of one layout)
    - layout-N ((optional) one UI package can have multiple layouts)
  - skins ( includes all skin folders)
    - skin-1 (the files of one skin)
    - skin-N ((optional) one UI package can have multiple skins)
  - static ( (optional) use for css development or implementation showcases)
    - cms ( htmls of general page elements)
    - application-N (html for application elements )

The "layout-N", "skin-N" and "application-N" are optional. They are needed if you plan to support multiple layout, skins or applications with this UI Package

We need subfolders in the static folder as in this way the layout html files and the static html files will have the same code for accessing the Common CSS files in their HEAD meta. This is done as often the layout files are also just normal html static files representing elements, so we copy-paste-ing them in the static folders is convenient.

Step 2 - Create the common CSS, LESS, javascript or media files

The next step is to create or paste all the files that will be used from your skins in general. These files should be placed in the "path/repository/common/" folder. In this folder you can create your own subfolders too.

Note Integra supports the LESS stylesheet language. All ".less" files will be automatically generated into CSS and cached on their first load in Integra. You will need a less conversion JS library most probably during the development.

Step 3 - Start working on a layout.html file

The layout is compiled by Integra system from ordinary HTML file. Place a file with "layout.html" name in a layout folder and start creating the static page. You can place the needed css files in the "/common/css" folder or in one of the skin folders. Media and JS files can also be placed there and included in the HEAD meta of the static file as you will ordinary do.

It is important to follow the presentation structure while building the layout.

The layout.html definition file is pure html. You can define regions by assigning them the rel="wfi" attribute.

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!"

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.

Here is an example of a layout html body elements. Have in mind the content inside the regions and the <head> was removed just for the example.

<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>

Step 4 - Create the uipack.xml file

After you are finished with all the needed layout.html files; skin and common css files, you can proceed with the creation of the xml definition file of the layouts and skins available in the ui package.

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.

Step 5 - Create the wfpack.info file

This file is generated by the packing program, but can be edited by hand also. It is used by the repositories and package manager to identify and categorize the packages. It includes specific information about the package like:

XML tag	Description
name	the package name. The naming convention is "Vendor.Application.packageName". The name is set by the author.
type	the package's type name or ID. The package types currently are: application, webframe, user interface, language and utility. The available types are predefined by the WordFrame team and are not case sensative. You can also use the corresponding IDs instead of the strings - Application = 1, WebFrame = 2, UserInterface = 3, Language = 4, Utility = 5
major-version	an integer representing the package version. The package version is set according to the following convention - major-version.minor-version.release-version (ex. 1.0.1). The major-version is set by the author.
minor-version	an integer representing the package subversion. It is set by the author.
release-version	an integer representing the package release. It is set by the author.
size	the size of the whole package in MB. Showed to the user as expected download size. It is set by the author.
summary	brief description of the package. It is set by the author.
description	long description of the package. It is set by the author.
change-log	list of all changes and the corresponding releases in a special HTML format. Should include all released versions of the package. It is set by the author.
author	The name of the vendor and/or developer that created the package.
copyright	Company or person that holds the copyrights
license	Under which license the package is distributed
creation-date	when this package was created
categories	A list of categories under which this package needs to be presented in the repositories
dependencies	A list of packages which need to be installed also if this package is installed

XML tag

Description

name

the package name. The naming convention is "Vendor.Application.packageName". The name is set by the author.

type

the package's type name or ID. The package types currently are: application, webframe, user interface, language and utility. The available types are predefined by the WordFrame team and are not case sensative. You can also use the corresponding IDs instead of the strings - Application = 1, WebFrame = 2, UserInterface = 3, Language = 4, Utility = 5

major-version

an integer representing the package version. The package version is set according to the following convention - major-version.minor-version.release-version (ex. 1.0.1). The major-version is set by the author.

minor-version

an integer representing the package subversion. It is set by the author.

release-version

an integer representing the package release. It is set by the author.

size

the size of the whole package in MB. Showed to the user as expected download size. It is set by the author.

summary

brief description of the package. It is set by the author.

description

long description of the package. It is set by the author.

change-log

list of all changes and the corresponding releases in a special HTML format. Should include all released versions of the package. It is set by the author.

author

The name of the vendor and/or developer that created the package.

Company or person that holds the copyrights

license

Under which license the package is distributed

creation-date

when this package was created

Step 6 - Create the editor.css files (optional)

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") of the editor, so you can use it to override. It will influence the elements in this iframe only.

Step 7 - 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.

When you start the program it will initially ask you for you vendor name (or developer name of the the packages signor) and the private-public key pair. It will generated one for you if you do not have, and you'd better archive them asap. You will need to set also a working folder, where the newly created packages should be saved.

Once the settings are done you will be asked to browse the folder of the package you need to create from and sign. Have in mind that the package folder needs to follow the folder structure as described in the wiki documentation or generally the contents should be:

1. wfpack.info - and xml format file according to the structure defined

2. repository folder containing the package contents.

That's it.