ASPRunner Professional 7.1 manual

Quick jump

The purpose of layouts is to simplify and improve the page modifications. This will allow the users to easily create their own templates as well as import existing templates such as Wordspress or Joomla themes. Layout structure doesn't contain any HTML code - only the layout elements definition.

So, layout is a set of pages templates (templates for Add page, Edit page etc.). Each page template contains some page structure and is stored in the individual .ly file in the folder C:\Program Files\ASPRunnerPro7.1\templates\layouts. Based on this files ASPRunnerPro generates HTML files and uses it to build the pages. When you design a new layout you can either use the .ly file (pseudocode) or modify the HTML layout file.

All predefined layouts are described in the file C:\Program Files\ASPRunnerPro7.1\templates\layouts\layouts.xml.

Layout elements

Page structure consists of the following layout elements: blocks, containers and bricks.

Blocks

Blocks are high-level page elements. A typical List page consists of four blocks. Some blocks can be empty.

layout_with_three_column

Here is a typical Amsterdam layout for the List page. Note that the right block is empty.

layout_blocks

Containers

Containers are visual elements within the blocks. Each container has a border, background color and other properties. Containers are always stacked inside the block one under another.

On the picture above the header block consists of two containers (buttons and search), left block has one container and the center block has four containers (buttons, message placeholder, grid and pagination).

layout_containers

Bricks

Bricks are page elements that carry a certain functionality. Each container has one or more bricks that are arranged either vertically or horizontally. A typical brick would be a search box, pagination control, the grid, CAPTCHA, "records found" etc. For example, on the picture above container 2 of the Header block contains four bricks: search, details found, pages and records per page.

layout_bricks

Structure of page template file (.ly file)

Each page template is stored in the individual .ly file. So let's examine its structure.

Example of the .ly file:

beginblock top

begincontainer horizontal style=undermenu width=100% search

brick left search

brick right details_found

brick right page_of

brick right recsperpage

endcontainer

endblock

Block description

beginblock [parameters] <name>

·	parameters - defined as width=N, where N - block width in percent.

·	name - possible values are center, right.e top, left,

Examples:

beginblock width=100 top

beginblock center

Container description

Block can include 1-N containers. Containers are always placed vertically on the page.

begincontainer <parameters> <name>

·	name - container name. Must be unique within the layout.

·	parameters - you can define the following parameters:

§	type - possible values are horizontal, vertical, grid.

§	style - skin name applied to the container. Required parameter. Defined as style = <style>, where <style> is one of the predefined style names:

§	empty - transparent shapeless skin. Used for elements which should be "in the air", for example, master table info, detail table, etc.

§	menu - style of the container that includes a vertical menu.

§	hmenu - style of the container that includes a horizontal menu.

§	undermenu - style of the container under a horizontal menu. If the page does not include horizontal menu, this style can be applied to the horizontal container, for example, for container with search.

§	fields - style of the container with fields on the Add/Edit/View/Register/Search pages.

§	form - style of the container for data entry on the Login/Change password/Remind password pages.

§	3 general-purpose containers with names 1, 2, 3.

§	width - block width in pixels or percent. Defined as width = <N\|N%>.

§	align - alignment of the container in the block. Defined as align = <left\|center\|right>.

§	columns - number of columns with data in vertical container. Defined as columns = N. By default N=1. Used when the container includes special bricks, consisting of more than one column. Used on the Add, Edit and other pages.

§	delimx, delimy - spacing in pixels between items within container. Used in the grid for a vertical/multicolumn view.

Examples:

begincontainer vertical style=3 left

begincontainer vertical style=1 width=500 align=center edit

begincontainer vertical columns=2 color=1 style=fields width=100% fields

Containers can be nested.

Brick description

brick <parameters> name

header <parameters> name

·	name - name of the brick used in bricks.xml - file that stores description of all bricks.

·	parameters - you can define the following parameters:

§	align - alignment of the brick in the horizontal container. Possible values are left, right, center.

§	color1/color2/color3 - style of the brick for plain, header and alternative parts. In the horizontal container color1 style is always used.

Example:

brick center pagination

The header brick is located at the top of the container. Its use reduces visible padding of the brick. In the header you can place only those bricks, which are always displayed on the page. If you hide such brick, the page will be broken.

Example of page template modification

Below you can see the List page with horizontal menu:

layout_list_page

This page looks nice however we want to create a new layout rearranging a few items on the page. Page structure is defined in the list.ly file:

beginblock top

begincontainer horizontal style=empty master

brick masterinfo

endcontainer

begincontainer horizontal style=2 toplinks

brick left toplinks

brick right loggedas

endcontainer

begincontainer horizontal style=hmenu hmenu

brick hmenu

endcontainer

endblock

beginblock left

begincontainer vertical style=3 left

brick color2 vsearch1

brick color1 vsearch2

brick color2 vdetails_found

brick color1 vpage_of

brick color1 vrecsperpage

brick searchpanel

endcontainer

endblock

beginblock center

begincontainer horizontal style=3 recordcontrols

brick left recordcontrols

endcontainer

begincontainer horizontal style=2 message

brick center message

endcontainer

begincontainer grid style=grid grid

brick grid

endcontainer

begincontainer horizontal style=2 pagination

brick center pagination

endcontainer

endblock

Lets say we need to move search panel and menu to the right side of the page, move search box to the top horizontal panel and display Details found in its own container. For this purpose we create a copy of the list.ly file that defines the list page structure in the following way, copying and pasting containers definitions. See changes highlighted.

beginblock top

begincontainer horizontal style=empty master

brick masterinfo

endcontainer

begincontainer horizontal style=2 toplikns

brick left search

brick left toplinks

brick right loggedas

endcontainer

endblock

beginblock right

begincontainer vertical style=3 search

brick searchpanel

endcontainer

begincontainer vertical style=menu menu

brick vmenu

endcontainer

endblock

beginblock center

begincontainer horizontal style=3 recordcontrols

brick left recordcontrols

endcontainer

begincontainer horizontal style=3 detailsfound

brick color1 details_found

brick color1 page_of

brick color1 recsperpage

endcontainer

begincontainer horizontal style=2 message

brick center message

endcontainer

begincontainer grid style=grid grid

brick grid

endcontainer

begincontainer horizontal style=2 pagination

brick center pagination

endcontainer

endblock

How to create a new layout

layouts.xml file

The list of layouts is stored in templates\layouts\layouts.xml file. To add a new layout add <projectLayout> node. Here is the sample:

<projectLayout>
<name>My new layout</name>
<parent>Default</parent>
<pages>
<pageLayout>
<page>add</page>
<file>add2.ly</file>
</pageLayout>
<pageLayout>
<page>list</page>
<file>list2.ly</file>
</pageLayout>
</pages>
</projectLayout>

·	<name> - your new layout name.

·	<parent> - layout name we inherit all pages from. You can override one or more pages.

·	<pages> - defines pages that belong to your layout. Pages that are not defined explicitly will be borrowed from the parent layout.

pages.xml file

You can mix and match .ly files creating new layouts. You can also create new .ly files as we discussed above. New layout files have to be defined in templates\layouts\pages.xml file.

·	<file> - .ly file name.

·	<page> - page type: add, edit, edit, list, login, register etc.

·	<name> - layout file name as it appears in Style Editor (see below).

page_layout_selection

Bricks

bricks.xml

Bricks are HTML files stored in templates\bricks directory. Bricks are defined in bricks.xml file. Here is the sample brick definition.

<brick>
<name>details_found</name>
<orientation>h</orientation>
<file>detailsfound_horizontal</file>
<plexpr>@TABLE.nType!=titCHART</plexpr>
<xtname>details_block</xtname>
</brick>

Here is how this brick description translates into actual template code:

##if @TABLE.nType!=titCHART##

{BEGIN details_block}

<tr><td></td><td>The actual brick content</td><td></td></tr>

{END details_block}

##endif##

·	<name> - brick name to be used in .ly files.

·	<orientation> - v (vertical) or h (horizontal). Use this option when you have two instances of the same brick, one to be used in vertical containers and another one to be used in horizontal containers. Optional.

·	<file> - file name (without .htm extension).

·	<plexpr> - template language expression that defines when this brick will included in the build process. For example:

<brick>
<name>loggedas</name>
...
<plexpr>@BUILDER.bCreateLoginPage</plexpr>

Brick named loggedas will be built only if login page is enabled. In other case this brick don't make much sense.

·	<xtname> - snippet name as it appears in template file. Optional.

·	<noWrapper> - if true, no wrapper will be added when brick is inserted into template file. In most cases <noWrapper> parameter is not required.

·	<parameters> - a way to pass parameters to the brick. Sample parameter:

<parameter>
<name>addfield</name>
<default>addfield.htm</default>
</parameter>

Sample usage in brick file:

##foreach @TABLE.arrAddPageLayout as @l order @l.order##

##if !@l.type##

##brick_param addfield##

##elseif @l.type==2##

##brick_param addsection##

##elseif @l.type==1##

##brick_param addtab##

##endif##

##endfor##

##brick_param addfield## will be replaced with addfield parameter value: addfield.htm.

Depending on layout type we insert either edit field control or tab or folding section. Parameters allow us to re-use bricks instead of copying and pasting template code from one brick to another.