SYS_Display_Layout

SYS_Display_Layout can be defined in two ways: the preferred properties and the old style AutoTemplate defiintion properties. The preferred new style is outlined first.

Preferred Style

The preferred XML definition of SYS_Display_Layout has the following parts:

Recordset-tied and Standalone Entities

Buttons, forms, messages and tests can also be "tied" to a recordset - i.e. defined as part of the recordset display definition. This is particularly useful when KLOOPing around the recordsets defined in a layout file. Entities not tied to a recordset are referred to in the documentation as "standalone".

^Top

Basic Properties

<SYS_Display_Layout Layout [DisplayMethod]>
	...
</SYS_Display_Layout>

Property

Optional?

Description

Layout

N

The layout file. This does not need the path or ".html" suffix. The file will be looked up in "arch/layouts/", or "config/layouts/" if prefixed with "LOCAL_".

DisplayMethod

Y
(if left out defaults to readonly)

The default display method for all of the fields in the layout (individual fields can override this). See the Display Methods section for possible values for this property.

^Top

Recordsets

<SYS_Display_Layout ... >
	...
	<Property [Name]>
<Properties RecordsetName [Style] [PagerName] [SorterName] [DisplayMethod] [FormName] [Message] [TestExpr] /> <Properties [UseRecordsetFieldFilter] [FieldFilterName] [ValidationDisplay] [ValidationMessage] /> [<Property Name="Fields">
<Property><Properties [FieldName] [DisplayMethod] [Style] [TestExpr] [StaticValue] [Caption] [DisplayAs] [ValidationDisplay] [ValidationMessage] [GroupName] [GroupFieldSeparator] /></Property> </Property>] [<Property Name="Groups"> <Property [Name]
<Property><Properties [FieldName] [DisplayMethod] [Style] [TestExpr] [Caption] [DisplayAs] [ValidationDisplay] [ValidationMessage] /></Property> </Property>]
 		[<Property Name="Buttons">  ... </Property>]
 		[<Property Name="Messages"> ... </Property>]
 		[<Property Name="Tests">    ... </Property>]

		[<Property Name="Rows">
<Property><Properties [Style] [TestExpr] /></Property>
</Property>] </Property> ... </SYS_Display_Layout>

^Top


Recordset Display Definition

Property

Optional?

Description

Name

Y

This is know as the "RecordsetHandle". Being as layouts can handle multiple recordsets, they need a generic name to identify each one in the layout XML. They can not use actual recordset names, because then layouts would only be able to use that specific recordset. In the XML, a recordset is then mapped to a handle in the layout.
Each recordset defined in the XML must therefore have a different handle name.

The standard handle name for one-recordset layouts is "MainRecordset", but of course it is up to each layout file as to which handle names have actually been used.

RecordsetName

N

The name of the recordset to be mapped to the handle.

Style

Y

The style of this recordset, if it is inside a KSTYLE_SELECT tag (see the KTAG reference)

PagerName

Y

A pager to be used by this recordset

SorterName

Y

A sorter to be used by this recordset

DisplayMethod

Y

The default display method for all of the fields in this particular recordset (individual fields can override this). See the Display Methods section for possible values for this property.

FormName

Y

A form to be used by this recordset

Message

Y

A HTML message that can be linked to this recordset, inserted into a layout file using <KMESSAGE RecordsetHandle="..." />. If this was present in the layout but no message was supplied in the XML, SYS_Display_Layout will ignore the KMESSAGE tag.

TestExpr

Y

A test that corresponds to the KTEST tags for the recordset in the layout. When the test is true the KTEST tag contents are displayed - therefore KTEST tags for the recordset can be used to include or ommit the entire recordset depending on the result of the test.

UseRecordsetFieldFilter

Y

Use a field filter defined as part of the recordset definition? If set to true (default is false) uses a filter called "FieldFilterExt" unless the FieldFilterName property is also set

FieldFilterName

Y

See above

ValidationDisplay

Y

Overrides the DisplayAs type for the recordset's validation message, if it has a validation message. Probably will be rarely used, but there if needed.

ValidationMessage

Y

A message, to be displayed in the event of recordset validation, that will override any message put in by constraint components. Use sparingly.

^Top

Field Display Definition

The field definition can be ommitted, whereby all the fields in the recordset are used.

Property

Optional?

Description

FieldName

Y

The field to be included, not used if a GroupName is set

DisplayMethod

Y

The display method for the fields. See the Display Methods section for possible values for this property.

Style

Y

Selects a style for the field out of those defined in the layout. The style is not a cascasding stylesheet class - it is a whole block of HTML which should, if the layout is defined correctly, include the field. See the demos for examples, and the KTAGs KSTYLESELECT, KSTYLECASE and KSTYLEPAD.

TestExpr

Y

A test that corresponds to the KTEST tags for the field in the layout. When the test is true the KTEST tag contents are displayed - therefore KTEST tags for the field can be used to include or ommit the field itself, its captions etc. depending on the test.

StaticValue

Y

Outputs this value instead of the true field value (useful if you want to display another value as the result of a test on the field)

Caption

Y

Overrides the field's Caption as set in the recordset definition. Use sparingly.

DisplayAs

Y

Overrides the field's DisplayAs type as set in the recordset definition. Use sparingly.

ValidationDisplay

Y

Overrides the DisplayAs type for the field's validation message, if it has a validation message. Use sparingly.

ValidationMessage

Y

A message, to be displayed in the event of field validation, that will override any message put in by constraint components. Use sparingly.

GroupName

Y

Specifies a group of fields to be used, rather than just a single field. The group of fields to be used is defined in the "Groups" section

GroupFieldSeparator

Y

Specifies some separator HTML to insert between the fields listed in the group

^Top

Groups Definiton

Property

Optional?

Description

Name

N

The name of the group, as referred to by the GroupName property in the field display definition

All other properties as for the Fields definition (NB "GroupName" and "GroupFieldSeparator" are not valid properties here!)

^Top

Buttons, Messages and Tests Display Definiton

These definitions are the same as their standalone counterparts, although they appear nested in the recordset display definition. See the Buttons, Messages and Tests sections.

^Top

Row Display Definition

Property

Optional?

Description

Style

Y

Selects a style for the row out of those defined in the layout. The style is not a cascasding stylesheet class - it is a whole block of HTML which contains the row. See the demos for examples, and the KTAGs KSTYLESELECT, KSTYLECASE and KSTYLEPAD.

TestExpr

Y

A test that corresponds to the KTEST tags for the row in the layout. When the test is true the KTEST tag contents are displayed - therefore KTEST tags for the field can be used to include or ommit the row, and any other related HTML etc.

^Top

Buttons

<SYS_Display_Layout ... >
	...
 	[<Property Name="Buttons">
   		<Property Name>
			<Property><Properties ButtonName [Style] [TestExpr] /></Property>
   		</Property>
   	</Property>]

	...
</SYS_Display_Layout>

Property

Optional?

Description

Name

N

This is the name of the button group used in the layout, and is the equivalent of "RecordsetHandle" for recordsets. Common names include "RowButtons", "EndButtons" etc.

ButtonName

N

The name of a button to be included in this group

Style

Y

Selects a style for the button out of those defined in the layout. The style is not a cascasding stylesheet class - it is a whole block of HTML which should, if the layout is defined correctly, include the button. See the demos for examples, and the KTAGs KSTYLESELECT, KSTYLECASE and KSTYLEPAD.

TestExpr

Y

A test that corresponds to the KTEST tags for the button in the layout. When the test is true the KTEST tag contents are displayed - therefore KTEST tags for the field can be used to include or ommit the button itself and its surrounding HTML (e.g. <td> </td> - the table cell is not displayed either) depending on the test.

^Top

Forms

<SYS_Display_Layout ... >
	...
 	[<Property Name="Forms">
   		<Property Name Value />
	</Property>]

	...
</SYS_Display_Layout>

Property

Optional?

Description

Name

N

The handle for the form used in the layout by the KFORM tag.
If a KFORM tag exists in the layout but no value for it is specified for the handle name in the XML, the KFORM tag is ignored.

Value

N

The name of the SYS_Form component to be used.

^Top

Messages

<SYS_Display_Layout ... >
	...
 	[<Property Name="Messages">
   		<Property Name Value />
	</Property>]

	...
</SYS_Display_Layout>

Property

Optional?

Description

Name

N

The name for the message used in the layout by the KMESSAGE tag.
If a KMESSAGE tag exists in the layout but no value for it is specified for the handle name in the XML, the KMESSAGE tag is ignored.

Value

N

The message to be displayed (can include HTML).

^Top

Tests

<SYS_Display_Layout ... >
	...
 	[<Property Name="Tests">
   		<Property Name Value />
	</Property>]

	...
</SYS_Display_Layout>

Property

Optional?

Description

Name

N

The name for the test used in the layout by the KTEST tag. If the test is present in the layout, but no name and value pair set for it in the XML, SYS_Display_Layout will ignore the tag and run its contents.

Value

N

The test expression

^Top

Old Style

The old style is simply that - the way you would usually define an AutoTemplate. The reason for the change was the fact that Layouts can handle multiple recordsets, and that there was a general explosion in possible properties.

The old style assumes the layout is a one-recordset, one-form layout. Therefore the old "ComponentName" property works to define the recordset ("RecordsetName" also now works). The recordset takes on the default handle name of "MainRecordset".
Other properties that work include "PagerName", "OrderUsing" ("SorterName" also now works), "FormName" (not tied to a recordset but given the default FormHandle "MainForm") etc.

"FieldFilter" and "FieldFilterExt" are compatible. "UseRecordsetFieldFilterExt" and "FieldFilterName" also work. SYS_Display_Layout converts "RowButtons", "EndButtons" (and their "Ext" postfixed cousins) into recordset-tied new style buttons. Because they are recordset-tied, beware that an old "EndButtons" property will not work with a standalone EndButtons button group in layout definition files.

^Top


Display Methods

Value

Description

readonly

Field is displayed as text

readonlyhidden

Field is displayed as text, with a hidden form value next to it so that it is submitted in the post

hidden

Field is displayed as a hidden form value so that it is submitted in the post.

editable

Field is displayed as an input field (the type of which depends on the "DisplayAs" property of the field)

link

Field is displayed as a readonly value in a link.

The actual link is made up by a separate property of the field (i.e the SYS_Display_Layout display fields, not the recordser definition fields) called LinkExpr which accepts curly bracket syntax, eg:

  • LinkExpr="page?value={recordset.value}" -- goes to an Architecture page with the parameter
  • LinkExpr="http://{recordset.value}" -- goes to an external page specified by the recordset value
  • LinkExpr="mailto:{rstPerson.EmailAddress}"

There is also a LinkTestExpr property - an optional test as to whether the link should be displayed or not (even if the link is not displayed, the readonly value of the field still will be)

klink

Field is displayed as a readonly value in a link, with the link being of the KLINK variety (i.e. it preserves the state).

Further options to be included in the field properties (i.e the SYS_Display_Layout display fields, not the recordset definition fields) include:

  • PageName - mandatory property which sets Architecture page to go to when the link is clicked
  • URLField - if this is set, URLField will be passed in the URL as opposed to the current field
  • URLName - optional property to set a different name in the URL for the field to be passed
  • LinkTestExpr - an optional test as to whether the link should be displayed or not (even if the link is not displayed, the readonly value of the field still will be)

anchor

Field is displayed as a readonly value, as the name parameter of an anchor tag.

The output is <a name="fieldvalue"></a> thus producing an invisible anchor on the page

^Top