Editing the Skins and Layouts

Editing the Skins and Layouts
The default layouts and skins provided by ActiveGrid are defined in the layoutRenderer.lyt (for layouts) and layoutRenderer.skn files (for skins). This appendix explains how to create custom layouts and skins. It contains the following sections:
Creating Custom Skins
Skins are defined in the layoutRenderer.skn file. The location of this file depends on the operating system you’re using:
Windows and Mac: The files are located in the prod\python\static directory under your ActiveGrid Studio installation directory.
Linux: The files are located in the lib/common/python/static directory.
To edit the skins for your application, copy the LayoutRenderer.skn file into your project’s static directory and then add it to your project file. You can name the file whatever you want. Delete the old skin file from your project. Now open the skin file in a text editor and make your changes. (There is no editor for this file, so you have to edit the XML directly.)
Note: If you prefer, you can edit the main LayoutRenderer.skn file in your python\static directory. However, you modify a skin name that is in use by another application, that application will lose its reference to the skin. You will then have to regenerate or edit the application to specify the new skin name.
Reusing Style Customizations
Each ActiveGrid project can use only one .skn file. To reuse the styling from one application in another application, you need to create a .style file containing ag:skin_element tags and add it to your project.
For example, follow these steps:
1.
Open the .skn file that contains the ag:skin_element tags that you wish to reuse. Here is an example .skn file, called et.skn:
<?xml version="1.0" encoding="utf-8"?>
<ag:skins xmlns:ag="http://www.activegrid.com/ag.xsd">
<ag:skin name="wer" type="default">
<ag:skin_element_ref name="ET"/>
<ag:skin_element_ref name="Verdana, Arial, Helvetica, sans-serif"/>
<ag:skin_element_ref name="Normal"/>
<ag:category_substitutions>
<ag:substitution category="(navigation,horizontal)" use_layout="TabBar"/>
<ag:substitution category="(table)" use_layout="PaginatingTable"/>
<ag:substitution category="(heading,title)" use_layout="TitleBarWithLogo"/>
<ag:substitution category="(heading)" use_layout="BorderedGroup"/>
</ag:category_substitutions>
</ag:skin>
<ag:skin_element name="ET" type="color">
<ag:parameters>
<ag:parameter name="Site Background Color" key="SiteBackgroundColor" value="#FFFFFF" type="color"/>
....
</ag:skin_element>
</ag:skins>
2.
Delete the ag:skin tag completely, so that the file contains only ag:skin_element tags. After this step, the example .skn file, et.skn now looks like this:
<?xml version="1.0" encoding="utf-8"?>
<ag:skins xmlns:ag="http://www.activegrid.com/ag.xsd">
<ag:skin_element name="ET" type="color">
<ag:parameters>
<ag:parameter name="Site Background Color" key="SiteBackgroundColor" value="#FFFFFF" type="color"/>
[... content omitted ...]
</ag:skin_element>
</ag:skins>
3.
Save the edited file as a .style file. In this example, we save the edited et.skn file as et.style. Put the .style file either in prod/python/static or in a local project directory.
4.
Add the .style file to your project to make it deployable.
Note: In general, when you create your own ag:skin_element elements, put them in a .style file rather than a .skn file.
Example .style File
Here’s an example .style file.
<?xml version="1.0" encoding="utf-8"?>
<ag:skins xmlns:ag="http://www.activegrid.com/ag.xsd">
<ag:skin_element name="ET" type="color">
<ag:parameters>
<ag:parameter name="Site Background Color" key="SiteBackgroundColor" value="#FFFFFF" type="color"/>
<ag:parameter name="Images Background Color" key="SiteImagesBackground­Color" value="adc1dc" type="color"/>
<ag:parameter name="Title Bar Background Image" key="SiteTitleBarBGImage" value="skins/blue_top_gradient.gif" type="image"/>
<ag:parameter name="Title Bar Logo Image" key="SiteTitleBarLogoImage" value="skins/blue_poweredlogo.gif" type="image"/>
<ag:parameter name="Title Bar Title Color" key="SiteTitleBarTitleColor" value="#bdcee7" type="color"/>
<ag:parameter name="Title Bar Background Color" key="SiteTitleBarBack­groundColor" value="#587aac" type="color"/>
<ag:parameter name="Navigation Main Color" key="SiteNavigationMainColor" value="#28456d" type="color"/>
<ag:parameter name="Navigation Main Label Color" key="SiteNavigationMain­LabelColor" value="#FFFFFF" type="color"/>
<ag:parameter name="Navigation 3D Highlight Color" key="SiteNavigation3DHighlightColor" value="#7e9bc2" type="color"/>
<ag:parameter name="Navigation 3D Lowlight Color" key="SiteNavigation3DLowlightColor" value="#40577a" type="color"/>
<ag:parameter name="Navigation Highlight Color" key="SiteNavigationHigh­lightColor" value="#afc1db" type="color"/>
<ag:parameter name="Navigation Highlight Label Color" key="SiteNavigation­HighlightLabelColor" value="#28456d" type="color"/>
<ag:parameter name="Navigation Unselected Color" key="SiteNavigationUnse­lectedColor" value="#526d94" type="color"/>
<ag:parameter name="Navigation Unselected Label Color" key="SiteNaviga­tionUnselectedLabelColor" value="#afc1db" type="color"/>
<ag:parameter name="Navigation Unselected 3D Highlight Color" key="SiteNavigationUnselected3DHighlightColor" value="#869dbf" type="color"/>
<ag:parameter name="Navigation Unselected 3D Lowlight Color" key="SiteNavigationUnselected3DLowlightColor" value="#3b4f6b" type="color"/>
<ag:parameter name="Menu Main Color" key="SiteMenuMainColor" value="#EEEEEE" type="color"/>
<ag:parameter name="Menu 3D Highlight Color" key="SiteMenu3DHighlightColor" value="#FFFFFF" type="color"/>
<ag:parameter name="Menu 3D Lowlight Color" key="SiteMenu3DLowlightColor" value="#CCCCCC" type="color"/>
<ag:parameter name="Menu Label Color" key="SiteMenuLabelColor" value="#000000" type="color"/>
<ag:parameter name="Menu Dropdown Color" key="SiteMenuDropdownColor" value="#EEEEEE" type="color"/>
<ag:parameter name="Menu Dropdown 3D Highlight Color" key="SiteMenuDropdown3DHighlightColor" value="#EEEEEE" type="color"/>
<ag:parameter name="Menu Dropdown 3D Lowlight Color" key="SiteMenuDropdown3DLowlightColor" value="#EEEEEE" type="color"/>
<ag:parameter name="Bordered Group Border Color" key="SiteBorderedGroup­BorderColor" value="#D6D3CE" type="color"/>
<ag:parameter name="Bordered Group Header Footer Background Color" key="SiteBorderedGroupHeaderFooterColor" value="#EFEFEF" type="color"/>
<ag:parameter name="Bordered Group Background Color" key="SiteBorder­edGroupBackgroundColor" value="#EFEFEF" type="color"/>
<ag:parameter name="Bordered Group Label Color" key="SiteBorderedGroupLa­belColor" value="#636563" type="color"/>
<ag:parameter name="Input Label Color" key="SiteInputLabelColor" value="#636563" type="color"/>
<ag:parameter name="Input Border Color" key="SiteInputBorderColor" value="#D6D3CE" type="color"/>
<ag:parameter name="Input Error Label Color" key="SiteInputErrorLabelColor" value="#CC0000" type="color"/>
<ag:parameter name="Input Error Border Color" key="SiteInputErrorBorderColor" value="#CC0000" type="color"/>
<ag:parameter name="Output Label Color" key="SiteOutputLabelColor" value="#7191be" type="color"/>
<ag:parameter name="Output Border Color" key="SiteOutputBorderColor" value="#75a3ed" type="color"/>
<ag:parameter name="Button Label Color" key="SiteButtonLabelColor" value="#FFFFFF" type="color"/>
<ag:parameter name="Button Main Color" key="SiteButtonMainColor" value="#5A2CBD" type="color"/>
<ag:parameter name="Button 3D Highlight Color" key="SiteButton3DHighlightColor" value="#869dbf" type="color"/>
<ag:parameter name="Button 3D Lowlight Color" key="SiteButton3DLowlightColor" value="#3b4f6b" type="color"/>
<ag:parameter name="Table Border Color" key="SiteTableBorderColor" value="#EFEFEF" type="color"/>
<ag:parameter name="Table Header Color" key="SiteTableHeaderColor" value="#EFEFEF" type="color"/>
<ag:parameter name="Table Header Label Color" key="SiteTableHeaderLabelColor" value="#636563" type="color"/>
<ag:parameter name="Table Header 3D Highlight Color" key="SiteTableHeader3DHighlightColor" value="#FFFFFF" type="color"/>
<ag:parameter name="Table Header 3D Lowlight Color" key="SiteTableHeader3DLowlightColor" value="#CCCCCC" type="color"/>
<ag:parameter name="Table Row Background Color" key="SiteTableRowBack­groundColor" value="#FFFFFF" type="color"/>
<ag:parameter name="Table Row Divider Color" key="SiteTableRowDividerColor" value="#EEEEEE" type="color"/>
<ag:parameter name="Table Column Divider Color" key="SiteTableColumnDi­viderColor" value="#EEEEEE" type="color"/>
<ag:parameter name="Link Color" key="SiteLinkColor" value="#28456d" type="color"/>
</ag:parameters>
</ag:skin_element>
<ag:skin_element name="Normal" type="font-size">
<ag:parameters>
<ag:parameter name="Font Size Normal" key="SiteFontSizeNormal" value="9pt" type="font-size"/>
<ag:parameter name="Font Size Small" key="SiteFontSizeSmaller" value="8pt" type="font-size"/>
<ag:parameter name="Font Size Larger" key="SiteFontSizeLarger" value="10pt" type="font-size"/>
<ag:parameter name="Font Size Title" key="SiteFontSizeTitle" value="22pt" type="font-size"/>
</ag:parameters>
</ag:skin_element>
<ag:skin_element name="Arial, Helvetica, sans-serif" type="font-family">
<ag:parameters>
<ag:parameter name="Font Family" key="SiteFontFamily" value="Arial, Helvetica, sans-serif" type="font-family"/>
</ag:parameters>
</ag:skin_element>
</ag:skins>
Creating Custom Layouts
Layouts are defined in the layoutRenderer.lyt file. The location of this file depends on the operating system you’re using:
Windows and Mac: The files are located in the prod\python\static directory under your ActiveGrid Studio installation directory.
Linux: The files are located in the lib/common/python/static directory.
You can edit any included layout or create your own. To edit layouts, first open the layout file in the Layout Editor. Select File > Open and then navigate to the python/static directory. Open the layoutRenderer.lyt file.
Note: To access the layoutRenderer.lyt file more easily in the future, add the file to your ActiveGrid project. Then you can open the file directly from the Project Panel.
To edit an existing layout, select the layout from the Layout: pull-down menu. To add a new layout, click the New... button.
Layout File Structure
The .lyt file consists of a single ag:layouts tag wrapping any number of ag:layout tags. The ag:layout tag can contain any number of ag:css, ag:generator, and ag:head tags and a single, optional, ag:parameters tag:
The ag:layout tag defines a layout. It is the parent element to the other elements in this list. See The ag:layout Tag for more details.
The ag:css element is where you define any custom style sheets to apply to your layout. See The ag:css Tag for more details.
The ag:generator element contains the HTML for the layout. builds the HTML markup that you want to generate for each instance of this layout on a given page. See The ag:generator Tag for more details.
The ag:head element is where you define any JavaScript functions that you would like to be included in the head tag of the generated page. See The ag:head Tag for more details.
The ag:parameters element is where you define any parameters that you want to expose for the layout. These parameters are string-substituted for their values throughout the layout. See The ag:parameters Tag for more details.
Note: There are also various pieces of code that you can access in the layouts. These are called Code Snippets and give you access to the data model and some basic coding mechanisms.
The ag:layout Tag
The ag:layout element is the parent element for each layout. All the elements that define the layout are children of the ag:layout element. An ag:layout tag looks like this:
<ag:layout name="BorderedGroupFooterBar" category="(footer,centered)" description="Bordered Group Footer" applyToTypes="XFormsGroup">
The layout name should be unique. If a layout name is duplicated, then the application uses the last-defined layout of that name.
The application first loads the built-in layoutrenderer.lyt file, followed by any other .lyt files in the application's static directory. This allows the application to override a particular layout.
The ag:layout element has the following attributes:
 
Used for category substitutions in the skin file. All the layouts of a particular category can be skinned, provided the skin contains a <substitution> tag for the category.
An optional, comma-separated list of internal types that a particular layout can be used with. When you double-click the Layout field in the Property Editor, the layout picker dialog comes up. The list of layouts that are available is filtered using applyToTypes. If the list is empty, then the layout may be used with any type.
The ag:css Tag
An ag:css tag simply contains CSS content, which is accumulated as a page is rendered and output to the browser for inclusion in the head of the page. Note that the contents must be in a CDATA section.
An ag:css tag looks like this:
<ag:css agent="default"><![CDATA[
.$agATOM03Link {
color: #0000FF;
text-decoration: none;
} ]]></ag:css>
The agent attribute is used to determine whether a particular tag's contents get rendered for a particular browser. It’s safest to just use agent="default", which means that the tag's contents will be rendered for all user agents (browsers).
The ag:generator Tag
The ag:generator tag produces HTML content for the body of the page. A simple ag:generator tag looks like this:
<ag:generator agent="default" language="JAVASCRIPT"><![CDATA[
<table width="100%" class="$agBorderedGroupFooterBar" cellpadding="0" cellspacing="0">
<tr><td align="center">
<% data = makeArray(data) %>
 
<% for (var i in item.data) { %>
<% for (var j in item.children) { %>
<span class="$agBorderedGroupFooterText">
<% item.renderChildForData(item.children[j], item.data[i]) %>
</span>
<% } %>
<% }%>
</td></tr>
</table> ]]></ag:generator>
The ag:generator tag has the following two attributes:
The language attribute specifies the language used by the generator. Valid values for the language attribute are: 'JAVASCRIPT' and 'PYTHON' and 'PHP'. If the language is PYTHON then the generator contains a single python function.
The agent attribute is used to determine whether a particular tag's contents get rendered for a particular browser. It’s safest to just use agent="default", which means that the tag's contents will be rendered for all user agents (browsers).
An Example Generator in Python
Here is a Python version of the above generator tag (the earlier example used JavaScript):
<ag:generator agent="default" language="PYTHON"><![CDATA[
def renderHook(ctx, component, data, parametersDict, parentParametersDict=None):
import rendersupport
ctx.writeOutput("\n <table width=\"100%\" class=\"$agBorderedGroupFooterBar\" cellpadding=\"0\" cellspacing=\"0\">\n <tr><td align=\"center\">\n ")
if not isinstance(data, list): data = [data]
for childData in data:
for child in component.children:
ctx.writeOutput("\n <span class=\"$agBorderedGroup­FooterText\">\n ")
rendersupport.renderComponent(ctx, component, child, childData)
ctx.writeOutput("\n </span>\n ")
ctx.writeOutput("\n </td></tr>\n </table> ")]]></ag:generator>
Note that parameters (such as the selector $agBorderedGroupFooterBar work equally well in JavaScript or Python.
Code snippets are, for the most part, handled by direct string substitution of Python code. The valid snippets can be found in the file layoutcode.txt.
In the above example, for instance:
<% data = makeArray(data) %>
Is replaced with:
if not isinstance(data, list): data = [data]
The item.data[i] snippet is often useful. This resolves to an ActiveGrid data object. You can dereference the fields on it using a -> arrow (or simply a '.' (though this will not work under PHP). An example would be:
item.data[i]->user_name
Where you know that user_name is a valid field on the current data object.
The ag:head Tag
An ag:head tag contains content (typically script) to be placed in the head of the rendered Page. Here’s an example:
<ag:head agent="default" language="JAVASCRIPT" execute="True"><![CDATA[
<script language="javascript">
 
function swapMenuItemColor(menuItem){
if (menuItem.className == "$menuBarCell") menuItem.className="$menuBarOnCell";
else menuItem.className="$menuBarCell";
return;
}
function clearMenuBar(){
var tds = document.getElementsByTagName("td");
for (i=0; i<tds.length; i++){
if(tds[i].className == "$menuBarOnCell"){
tds[i].className = "$menuBarCell";
}
}
}
</script> ]]></ag:head>
The ag:head tags are just like ag:generator tags, except that they are not converted to python code by default. However, if you include the execute="True" attribute in the ag:head tag then it will be converted to Python. This allowsyou to use code-snippets in the ag:head tag.
The agent attribute is used to determine whether a particular tag's contents get rendered for a particular browser. It’s safest to just use agent="default", which means that the tag's contents will be rendered for all user agents (browsers).
The ag:parameters Tag
An ag:parameters tag defines the parameters for a given layout. You can specify parameters in any of the other section (head, css, or generator). A parameters section looks like this:
<ag:parameters>
<ag:parameter name="Bordered Group Footer Bar Selector" key="agBorderedGroupFoot­erBar" value="agBorderedGroupFooterBar" type="selector"/>
<ag:parameter name="Bordered Group Footer Text Selector" key="agBorderedGroupFoo­terText" value="agBorderedGroupFooterText" type="selector"/>
</ag:parameters>
Each ag:parameter tag defines one parameter. The ag:parameter element has the following attributes:
 
key
A string used in the layout to access the parameter's value. This is done by putting the key, prepended with a $, somewhere in the layout. At render time the $ and key will be replaced with the parameter's value.
Used as the value of the parameter if the user has not set a value through the Property Editor.
Rarely used. Parameters type="selector" setting are permuted during the render process so that unique CSS selectors are created for instances of a layout that might have parameters affecting their CSS content. Make your CSS selectors (in ag:css) into parameters of type selector.
 

ActiveGrid
Application Developer's Guide
Version 2.0