Loading...
 

Layouts


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 \templates\layouts. Based on this files PHPRunner/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 \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.

Image

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

Image

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.

Image

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:

@leftmargin=20
@topmargin=20

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

In the beginning of .ly file you can specify left and top margin values:

@leftmargin=20
@topmargin=20

Default margin is 10 pixels.

Block description

beginblock [parameters] <name>
  • parameters - defined as width=N, where N - block width in percent.
  • name - possible values are center, right, 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. Defines how bricks will be positioned inside the container. Default value is horizontal. grid is a special type of container that is used for grids on the list page only.
    • 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 any horizontal container, for example, for container with search.
      • fields - style of the container with edit fields on Add/Edit/View/Register/Search pages.
      • form - style of the container for data entry on the Login/Change password/Remind password pages.
      • ''three general-purpose containers with names 1, 2, 3 i.e. style=2
    • 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.
    • rmargin, bmargin - right and bottom margins respectively. For instance bmargin defines the vertical margin between this container and the next one.

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:

Image

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 listed in red.

beginblock top
	begincontainer horizontal style=empty master
 		brick masterinfo
	endcontainer	

    begincontainer horizontal style=2 toplikns
        ~~#F00:brick left search~~
        brick left toplinks
        brick right loggedas
    endcontainer
endblock 

beginblock ~~#F00:right~~
    begincontainer vertical style=3 search
		brick searchpanel
   endcontainer
   	~~#F00:begincontainer vertical style=menu menu
		brick vmenu
	endcontainer~~
endblock 

beginblock center
    begincontainer horizontal style=3 recordcontrols
        brick left recordcontrols
    endcontainer
 ~~#F00:   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.

<layout>
    <file>add.ly</file>
    <page>add</page>
    <name>add1</name>
</layout>
  • <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).

Image

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.