Messages

Some heitml components can be remote controlled. When linking to a page with such a component, a message for the component can be included. This message requests the component to perform a certain action.

For example possible messages for a dbform are empty to clear the form or display to display a certain record in the form. Display gets a record key as parameter.

A message is always addressed to a specific component, identified by the oid parameter of the component. The message contains a message kind of and possibly some parameters.

heitml contains components that accept messages, Receivers and components that send messages, Senders.

Message Transmission

There are two ways to transmit a message. A very common one is to pass on a message as URL parameters. This works fine but always bears the risk that the parameters are changed in an unintended way by unauthorized person.

Suppose you have a simple application listing certain database records and linking to them. The link sends a message to a dbform to display a certain record, including the key of the record as URL parameters. It is no problem for anybody using your application to change the URL to point to another database record. So in this setup anybody can explore all your data, not only the records that are listed ! This might not be a problem for a public database but if there are records that should not be public, used heitmls secure message mechanism.

The secure message transmission stores the message itself in the session memory and only uses a number to identify the message in the URL. Use the secure sender components to send secure messages.

Per default heitml components accept secure messages only. Using the msgallowed parameter you can allow a component to listen for messages as URL parameters. Remember to do so if you really want to use URL based messages.

Receivers

Components like dbform, dbscroller, dbcontainer and dbdisplay accept messages. The documentation below and the component reference list all messages accepted.

Senders

There are various sender components. msglink creates a link. When clicked on it sends the message. dlink must be used on a panel. It works like msglink but includes field values from the panel as parameters. So a dlink can be used to link to another related database record. dbselectlink is similar but is used as a column of a dbdisplay.

For all these messages there are secure counterparts: iamsglink, iadlink, iadbselectlink. Additionally there dbquerybutton. Use it on a sesform to send all the form fields as message. This is very useful to create search forms.

Reference

Receivers

The following components accept messages. The following documentation explains what messages are accepted and what actions they perform.

Component:dbformDetails

Messages

Kind	Description
empty	Displays an empty form. Any field values included in the message are takes as default values of the form.
display	Displays a database record in a disabled form. Requires a key of the record as parameter. The key must consist of one or more fields. All field names provided must be legal column names found in the database.
modify	Displays a database record in an enabled form. Parameters are the same as with display.
searchdisplay	Works like display but performs an automatic query search. The key fields of the messages are compared with the fields of the same name contained in the database. Default comparison operator is a substring match (like "%...%"). Other operators can be selected using dbfieldoperator in a search form.
searchmodify	Works like modify but performs an automatic query search. The key fields of the messages are compared with the fields of the same name contained in the database. Default comparison operator is a substring match (like "%...%"). Other operators can be selected using dbfieldoperator in a search form.
copy	Displays a copy of a database record in an enabled form. Parameters are the same as with modify.

Component:dbscrollerDetails

Messages

Kind	Description
search	Automatic query search. The key fields of the messages are compared with the fields of the same name contained in the database. Default comparison operator is like "%...%". Other operators can be selected using dbfieldoperator.
query	Query search. The query can use dbqueryfield to compare key fields with database fields.
display	Query search. The key fields of the message must be equal to the fields in the database with the same name.
clear	Clears the scrollers content.

Component:dbcontainerDetails

Messages

Kind	Description
clear	Clears the container and displays nothing.
display	Displays a database record. The key must consist of one or more fields. All field names provided must be legal column names found in the database.
search	Works as display, but fields are compared using like or a user specified operator (see dbfieldoperator).

Component:dbdisplayDetails

Senders

Component:msglinkDetails
Link sending a message when pressed. This is often used to trigger a dbform to show a certain database record. You may add key fields using the AddProp function of the Component Editor (see Inspector Mode select box).

Property	Kind	Description
Href	String(60)	Destination URL
Action	String(60)	Action to be performed by the dbform
Receiver	String(60)	Destination Component
Urlpar	String(20)	Parameters appended to the URL. (The ? part of the URL excluding th e #).
Target	String(10)	Target parameter for the link.

Component:dlinkDetails
Link to another component to display the current record.

Property	Kind	Description
Href	String(60)	Destination URL
Action	modify, display, empty, modifyemp, copy	Action to be performed by the dbform
Receiver	String(60)	Destination Component
Key	String(10)	Key field used to identify the record
Urlpar	String(20)	Parameters appended to the URL. (The ? part of the URL excluding the #).
Target	String(10)	Target parameter for the link.

Component:dbselectlinkDetails
Link to another component to handle the current record. dbselectlink must be used inside the automatic format of a dbdisplay or dbscroller. It adds a new column containing an HTML-link. When the link is clicked the component specified by receiver on the page specified by href gets a message. Typically this is a dbform or dbcontainer to display the record or another dbdisplay or dbscroller.

Property	Kind	Description
Href	String(60)	Destination URL
Action	String(60)	Action to be performed by the receiver
Receiver	String(60)	Destination Component
Key	String(20)	Key field used to identify the record. Key can also be a comma separated list of key field names. Field names can be preceded by 'targetname=' id the receiver uses different key field names.
Title	String(20)	Title of the Link column
Width	Integer %	Width of the link column
Bgcolor	String(60)	Table field parameters
Align	Left, Middle, Right
Valign	Top, Middle, Bottom
Nowrap	Checkbox
Urlpar	String(20)	Parameters appended to the URL. (The ? part of the URL excluding the #).

Component:iamsglinkDetails
Link sending a message when pressed. This is often used to trigger a dbform to show a certain database record. You may add key fields using the AddProp function of the Component Editor (see Inspector Mode select box).

Property	Kind	Description
Href	String(60)	Destination URL.
Action	String(60)	Action to be performed by the dbform.
Receiver	String(60)	Destination Component.

Component:iadlinkDetails
Link to another component to display the current record.

Property	Kind	Description
Href	String(60)	Destination URL.
Action	modify, display, empty, modifyemp, copy	Action to be performed by the dbform.
Receiver	String(60)	Destination Component.
Key	String(10)	Key field used to identify the record.

Component:iadbselectlinkDetails
Secure link to another component to handle the current record. dbselectlink must be used inside the automatic format of a dbdisplay or dbscroller. It adds a new column containing an HTML-link. When the link is clicked the component specified by receiver on the page specified by href gets a message. Typically this is a dbform or dbcontainer to display the record or another dbdisplay or dbscroller.

Property	Kind	Description
Href	String(60)	Destination URL.
Action	modify, display, empty, modifyemp, copy	Action to be performed by the dbform.
Receiver	String(60)	Destination Component.
Key	String(20)	Key field used to identify the record. Key can also be a comma separated list of key field names. Field names can be preceded by 'targetname=' id the receiver uses different key field names.
Title	String(20)	Title of the Link column.
Width	Integer %	Width of the link column.

Component:dbquerybuttonDetails
The querybutton can be used on a sesform to send a message to a dbscroller, dbcontainer, or dbdisplay. The receiving component then searches the database for matching records and displays them.

Normally all non-empty form fields are compared to the field in the database with the same name. Only records that contain the same field value match.

If type=search is selected however, fields are compared using a substring match, i.e. the content of the form field must occur as a substring of the corresponding database field.

Using the dbfieldoperator component the compare operator can be specified for each field separately.

Property	Kind	Description
Receiver	String(60)	Component to send the message
Name	String(20)	Button Name inside the form, must be unique.
Layout	String(60)	Input is a standard HTML submit button, image shows an image on the button, link creates a link (needs JavaScript), compatlink a link or button depending on the browser, button an HTML4.0 button (must occur just once at end of form), mbutton an HTML 4.0 button (needs JavaScript), and compatbutton an HTML 4.0 button or normal button depending on the browser; more
Type	String(60)	Action to take by the receiver.
Value	String(20)	Label on the Button
Src	String(20)	Image Url, only used for layout=image
Border	Integer	Border Size, only used for layout=image