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:
Skins are defined in the layoutRenderer.skn file. The location of this file depends on the operating system you’re using:
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.
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.
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:
|
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:
|
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.
|
<ag:parameter name="Site Background Color" key="SiteBackgroundColor" value="#FFFFFF" type="color"/>
<ag:parameter name="Images Background Color" key="SiteImagesBackgroundColor" value="adc1dc" type="color"/>
Layouts are defined in the layoutRenderer.lyt file. The location of this file depends on the operating system you’re using:
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.
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.
|
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:
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:
|
|
|
|
|
|
|
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.
|
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:
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 produces HTML content for the body of the page. A simple
ag:generator tag looks like this:
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).
|
Here is a Python version of the above generator tag (the earlier example used JavaScript):
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.
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:
Where you know that user_name is a valid field on the current data object.
An ag:head tag contains content (typically script) to be placed in the
head of the rendered
Page. Here’s an example:
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).
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:
Each ag:parameter tag defines one parameter. The
ag:parameter element has the following attributes:
|
|
|
|
|
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.
|
|
|
|
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.
|