Layouts

A layout is like a template in that it separates the design from the programming. Layouts are more powerful than templates, but they are also more complex to use.

A layout, unlike a template, can be embedded in another layout. A typical use of this is to define standard parts of HTML pages, such as the top and bottom of an HTML page. See Embedding layouts.

One of the main purposes of a layout is to display a set of fields in a particular manner. The way that this is done differs from that for templates. See Passing values.

Embedding layouts

In this example you will create standard parts of web pages that can be incorporated into other web pages. You will create a web page that looks similar to this:

Example of layouts

To create standard parts of a web page

  1. Create the main.html file in the /config/template directory. The code is shown below.
  2. Create the topfile.html file in the /config/template directory. It should contain:
    <P>The content of this file (topfile.html) will appear at the top of the page.</P>
  3. Create the infile.html file in the /config/template directory. It should contain:
    <P>The content of this file (infile.html) will appear in the table.</P>
  4. Create a new configuration.1.xml file in the /config directory. The code is shown below.
  5. Open a browser and type the URL of the welcome.html file. The URL consists of the base URL followed by the file name (you do not need to type the .html extension).
  6. The page should appear. If it does not, or if any error messages appear, refer to the "Troubleshooting" topic.

main.html

Arcos will substitute the two KLAYOUT tags with the HTML code that is defined in the two other layout files (topfile.html and infile.html). To see how it does this, refer to the code in the configuration.1.xml file.

<HTML>
<BODY>
  <KLAYOUT Name="Top">This is where the top will go</KLAYOUT>
  <TABLE border="1">
    <TR>
      <TD><KLAYOUT Name="TableInsides">this will be in a table</KLAYOUT></TD>
    </TR>
  </TABLE>
</BODY>
</HTML>

configuration.1.xml

This file defines a web page called "welcome". It creates a an autotemplate called layoutExample, which we don't need to consider further.

You can see how the collections called "Top" and "TableInsides" are referenced, and how they are related to the HTML files that contain them.

<Configuration>
   <Page PageName="welcome">
      <SYS_Display_Template TemplateFile="LOCAL_layoutExample">
         <SYS_Display_Layout Layout="LOCAL_main">
            <Collection Name="Top">
               <SYS_Display_Layout Layout="LOCAL_topfile"/>
            </Collection>
            <Collection Name="TableInsides">
               <SYS_Display_Layout Layout="LOCAL_infile"/>
            </Collection>
         </SYS_Display_Layout>
      </SYS_Display_Template>
   </Page>
</Configuration>

Passing values

This is an advanced topic. You need a good understanding of previous topics before you tackle this one.

When you use a template (or autotemplate) to display fields, each field must be explicitly listed. If a page definition uses different recordsets with the same autotemplate component, Arcos must produce a different autotemplate for each different recordset. If you then want to modify the autotemplates, then you must make many similar changes in the different files. However, if you use a layout, you need only make a single global change. This is because a layout can refer to a general field which can be passed from the XML definition (using KLOOPs to work with all the pages, recordsets and fields).

The following piece of code shows how to pass values to a layout. It uses the RecordColumnList.html layout file, which is an autotemplate. This produces a table that lists all fields that you pass to it using the FieldFilter property. The code looks complex, but it has a regular structure. There are many similarities with templates. If any components (for example, buttons) are not needed, the relevant section of code can be removed.

<SYS_Display_Template TemplateFile="LOCAL_RecordColumnList">
   <SYS_Display_Layout Layout="SYS_RecordColumnList" DisplayMethod="editable">
      <Property Name="Recordsets">
        <Property>
         <Properties RecordsetName="rstContacts" DisplayMethod="readonly"  />
         <Properties SorterName="spContacts" PagerName="spContacts" />
            <Property Name="Fields">
               <Property><Properties
                      FieldName="ContactName" DisplayMethod='link'
                      LinkExpr='mailto:{rstContacts.ContactEmail}'
                      LinkTestExpr="{? {rstContacts.ContactEmail} != {CONST.NULL}}" />
               </Property>
               <Property><Properties FieldName="ContactPosition" /></Property>
               <Property><Properties FieldName="ContactCompany" /></Property>
               <Property><Properties FieldName="ContactEmail" DisplayMethod="editable"/></Property>
            </Property>
          <Property Name="Messages">
             <Property Name="RecordCount" Value="There are {rstContacts..recordcount} record(s)" />
             <Property Name="NoRecords" Value="There are no records" />
          </Property>
          <Property Name="Buttons">
              <Property Name="RowButtons">
                  <Property><Properties ButtonName="RowButton" /></Property>
              </Property>
           </Property>
       </Property>
    </Property>
    <Property Name="Buttons">
        <Property Name="EndButtons">
           <Property><Properties ButtonName="EndButton" /></Property>
        </Property>
    </Property>
    <Property Name="Forms">
      <Property Name="MainForm" Value="frm1" />
    </Property>
    <Property Name="Messages">
        <Property Name="Title" Value="Record Column List" />
    </Property>
  </SYS_Display_Layout>
</SYS_Display_Template>