KTAGs for layouts

This topic gives general information about the properties of KTAGS, and then describes the purpose and constraints of each of the KTAGs.


A Few Notes on Tag Properties

Property Inheritance

Be aware that a KTAG inherits the properties of the KTAGs it is nested in, for brevity. Therefore a KTAG does not have to reiterate a property if the required value appears in one of its parents (there are plenty of examples of this in the standard Architecture layouts).

The only properties currently NOT inherited are:

"Unsetting" Inherited Properties

What if you do not want to supply a value for a property, yet it is being inherited from a parent? In this case you need to write Property="" to unset the inherited parent value.

The special IgnoreLoopRecordsetHandle property

A tag will first look at its RecordsetHandle property and then look to see if its inside a Recordset KLOOP in order to find out what RecordsetHandle to use. If a tag should not have a RecordsetHandle property, yet it is inside a Recordset KLOOP and will use that handle, then invoke IgnoreLoopRecordsetHandle to stop that happening.

Reserved Properties

The "Type" property is reserved for entity types, i.e. "Recordset", "RecordsetRow", "RecordsetField" and "Button". It should not be used for any other purpose. The main reason for this is to ensure that the "Type" property is correctly passed down from parent tags to their children.

Property Values

You can not nest quotes or single quotes in property values, or use < and >, but you can use their HTML special character codes, i.e. &quot; &lt; &gt; etc.

^Top


Tags

Select a tag to view:

^Top


KBUTTON

Purpose: To add a button

Constraints: Must be nested inside a KLOOP Type="Button" tag with a ButtonGroup that matches that of the KBUTTON.

Contents Ignored: Yes

See also: KLOOP

Property

Optional?

Description

ButtonGroup

N

The button group the button belongs to

^Top


KCAPTION

Purpose: To add a caption

Constraints: Must be nested inside a KLOOP Type="RecordsetField" tag with a RecordsetHandle that matches that of the KCAPTION.

Contents Ignored: Yes

See also: KDATA, KTEST

Property

Optional?

Description

RecordsetHandle

Only if not in a Recordset KLOOP

The RecordsetHandle that the caption belongs to

^Top


KDATA

Purpose: To insert data into the template, be it a field or a value.

Constraints: Must be nested inside a KLOOP Type="RecordsetField" tag with a RecordsetHandle that matches that of the KCAPTION.

Contents Ignored: Yes

See also: KCAPTION, KTEST

Property

Optional?

Description

RecordsetHandle

Only if in a Recordset KLOOP

The RecordsetHandle that the field belongs to

^Top


KFORM

Purpose: To insert a form into the template. Note that if no form is attached to the form handle in the XML, the form will not be inserted into the template - see the Forms section of "Using SYS_Display_Layout".

Constraints: None

Contents Ignored: No

See also: None

Property

Optional?

Description

FormHandle

Y

The FormHandle that identifies the form.

RecordsetHandle

Only if in a Recordset KLOOP

The RecordsetHandle that the form belongs to

^Top


KINDEX

Purpose: To insert an index for the recordset row.

Constraints: None

Contents Ignored: Yes

See also: None

Property

Optional?

Description

RecordsetHandle

Only if in a Recordset KLOOP

The RecordsetHandle to identify the recordset to add the index for

IncludeOnce

Y

If in a KLOOP Type="RecordsetField", this option when set to true (if you leave it out it's false) puts in the index in first time around the loop only [just for Rob ;)]

 

^Top


KLAYOUT

Purpose: To run sub components (be they more Layouts or AutoTemplates) to output further HTML into the template

Constraints: None

Contents Ignored: Yes

See also: None

Property

Optional?

Description

Name

N

The Components Collection name, set in the properties of SYS_Display_Layout, that contains the sub components to be run

^Top


KLOOP

Purpose: To denote that a collection of items (specified by the "Type" property) must be iterated through until each item has been output into the template.

Constraints: None

Contents Ignored: No

See also: KCAPTION, KDATA, KBUTTON

Property

Optional?

Description

Type

N

One of:

  • "Button" - iterates through all the buttons for a button group in the layout.
    KLOOP MUST also have a "ButtonGroup" property set.
    The buttons iterated through are those set in the properties XML of SYS_Display_Layout

  • "Recordset" - iterates through all the recordsets in the layout

  • "RecordsetRow" - iterates through all the rows for a recordset
    KLOOP MUST also have a "RecordsetHandle" property set

  • "RecordsetField" - iterates through all the fields for a recordset (those defined in the "Fields" section of the recordset, and if none defined, all the fields for the recordset)
    KLOOP MUST also have a "RecordsetHandle" property set. The fields iterated through can be set in the "Fields" property for the recordset in the SYS_Display_Layout XML, whose handle in the XML matches the handle for this tag.

^Top


KMESSAGE

Purpose: To insert a HTML message into the template. Note that if a value for the message is found in the XML. then nothing will be inserted into the template - see the Messages section of "Using SYS_Display_Layout".

Constraints: None

Contents Ignored: Yes

See also: None

Property

Optional?

Description

RecordsetHandle

Y (if not set RecordsetHandle is effectively set if inside a Recordset KLOOP)

 

 

The RecordsetHandle that the message is associated with (i.e. the message value appears as part of the "Recordsets" properties for the SYS_Display_Layout XML).

If Name is also set, the message value comes from the "Messages" properties in the recordset display definition.

Name

Y

The name of the message (i.e. the message value appears against this name in the "Messsages" properties for the SYS_Display_Layout XML).

If RecordsetHandle is also set, the message value comes from the "Messages" properties in the recordset display definition.

^Top


KPAGER

Purpose: To insert a display part of a pager. Note that if no pager is attached to the recordset in the XML. nothing will be inserted into the template for the tag.

Constraints: None

Contents Ignored: Yes

See also: KSORTER

Property

Optional?

Description

RecordsetHandle

Only if in a Recordset KLOOP

The RecordsetHandle of that the pager is attached to

Display

N

The part of the pager to be displayed - one of:

  • "PageList"
  • "PrevPageImage"
  • "NextPageImage"

^Top


KRECORDCOUNT

Purpose: To insert the number of records for a recordset into the template. This is a convenience tag - the same effect can be achieved by a KMESSSAGE with "{rstRecordset..recordcount}" as the value.

Constraints: None

Contents Ignored: Yes

See also: KMESSAGE

Property

Optional?

Description

RecordsetHandle

Only if in a Recordset KLOOP

The RecordsetHandle of the recordset whose records to count.

^Top


KSORTER

Purpose: To insert a display part of a sorter. Note that if no sorter is attached to the recordset in the XML, nothing will be inserted into the template - with the exception of "Link", where only the tag contents will be inserted.

Constraints: None

Contents Ignored: If Display="Link", no, otherwise, yes.

See also: KPAGER

Property

Optional?

Description

RecordsetHandle

Only if in a Recordset KLOOP

The RecordsetHandle of that the sorter is attached to

Display

N

The part of the sorter to be displayed - one of:

  • "Link"
  • "AscImage"
  • "DescImage"

^Top


KSTYLE_CASE

Purpose: Used to define a style - the contents of the tag are used if the Style property of the tag matches the style set for the entity under consideration (e.g. a particular field, button etc.). One KSTYLE_CASE in a KSTYLE_SELECT can be nominated as the default should no style be set for the entity.

Constraints: Must be inside a KSTYLE_SELECT tag. No more than one KSTYLE_CASE should have the Default set to "1" - if so, the last one will be used as the default.

Contents Ignored: No

See also: KSTYLE_SELECT, KSTYLE_PAD.

Property

Optional?

Description

Name

N

The name of this style

Default

Y

If set to true ("1" or "True"), the contents of this particular case are used as the style if the user has not specified a style for the entity in the XML. The default for Default is false.

DefaultOn

Y

The default to use given the value of the loop counter that the KSTYLE_SELECT is enclosed in.

NB: this property will not work for RecordsetRow KSTYLEs, since there is no way of knowing at template generation time how many rows will be in the recordset.

Current valid values are "First", "Second", "Third", "Last", "LastButOne", "LastButTwo". These can be combined using AND and OR syntax eg "First | Second", "First & Last".

For ease of coding in SYS_Display_Layout, the current rules must be observed:

  • You can't use | and & together in the same value of DefaultOn.

  • If an entity (e.g. a field) fits into more than one style, say there are styles for "First & Last" and "First", the latter style will always be used. So if a field really is the first and the last, in the example just given, the "First" style is used if it is defined after "First & Last".

^Top


KSTYLE_PAD

Purpose: If the recordset is out of data, or the style of the current entity (button, field etc.) does not match any of the KSTYLE_CASEs, then the contents of KSTYLE_PAD are run.

Constraints:

Contents Ignored: No

See also: KSTYLE_SELECT, KSTYLE_CASE.

KSTYLE_PAD has no properties.

^Top


KSTYLE_SELECT

Purpose: To enclose KSTYLECASE and KSTYLEPAD tags to select a style for a recordset row, field or button. (Could be called KSTYLESWITCH, except it doesn't work like a switch!)

Constraints:

Contents Ignored: No

See also: KSTYLE_CASE, KSTYLE_PAD

Property

Optional?

Description

Type

N

One of:

  • "Button" - KSTYLE_SELECT MUST also have a "ButtonGroup" property set.

  • "Recordset"

  • "RecordsetRow" - KSTYLE_SELECT MUST also have a "RecordsetHandle" property set

  • "RecordsetField" - KSTYLE_SELECT MUST also have a "RecordsetHandle" property set.

 

^Top


KTEMP

Purpose: KTEMP and its contents are completely ignored - this makes it useful for comments, and inserting design-time HTML, e.g. a stylesheet, that you would not want carried forward into the template.

Constraints: None

Contents Ignored: Yes.

See also: None

KTEMP has no properties.

^Top


KTEST

Purpose: To add tests to the AutoTemplate section

Constraints: If of type "RecordsetField" or "Button" should be inside a KLOOP of that nature.

Contents Ignored: No

See also: None

Property

Optional?

Description

Name

At least one

Uses a named test set in the "Tests" property of SYS_Display_Layout.

There are also a few built-in named tests for convenience (these names can not be used for "named" tests). These also require a RecordsetHandle property to be set, if not inside a KLOOP Type="Recordset"

  • "AnyRecords"
  • "NoRecords"
  • "AnyPages" - requires a Pager to be set for the RecordsetHandle in the XML to do anything
  • "OrderedBy" - Determines if the current field is the one being sorted on. Requires a Sorter to be set for the RecordsetHandle in the XML to do anything, also needs to be inside a KLOOP Type="RecordsetField"

If Type="Recordset" is also set, a named test is looked up under the "Tests" properties of the Recordset display definiton for the RecordsetHandle.

Type

One of:

  • "Recordset"
  • "RecordsetRow"
  • "RecordsetField"
  • "Button"

A further "RecordsetHandle" property may be required to identify the recordset, if required. This will look up the test expression set in the XML properties of that entity. ("RecordsetHandle" will effectively already be set if inside a Recordset KLOOP).

If "Name" is also set, a named test is looked up under the "Tests" properties of the Recordset display definiton for the RecordsetHandle (if one is given).

Case

Y

Adds a result clause onto the test. The default is "True".

^Top


KVALIDATION

Purpose: To insert a validation message for a field or recordset.

Constraints: Should be inside a KLOOP Type="RecordsetField" if a validation message for a field, otherwise the recordset version will be assumed

Contents Ignored: Yes

See also: None

Property

Optional?

Description

Type

N

One of:

  • "Recordset"
  • "RecordsetField"

Display

Y

One of:

  • "validation"
  • "novalidation"
  • "anyvalidation"
  • "validationwithbreak"

If none given, "validation" is assumed.

Message

Y

A message that will ALWAYS be displayed in the event of failing validation. If this is left blank the message content is left to the Constraint components

^Top