There are two ways to go about rolling your own reusable components ( OK, three. Since components, like forms and reports, are defined in XML, they can be created using a text editor. ) , either by saving one or more objects from an existing form or report, or by designing from scratch. Since creation of forms and reports has been described in earlier chapters, the former is described first.
Creating Components from Existing Forms and ReportsAt its simplest, creating a component from a form or report is as simple as right-clicking on an object and selecting Save as component, or selecting several objects, and then using the Save as component entry in the Edit menu. In either case, you will get the dialog shown below:
The top text box is used to enter a name for the component, while the combobox selects the place to store it. This will show each server database (including the !Files entry), plus Save to file. Selecting the latter and clicking OK will bring up a standard file dialog ( This is one way to create a locally saved component. ) . The comment area can be used to enter any comment, which will actually be saved as the notes propertly of the component. This text will appear under the Description tab of the component selection dialog that appears when you paste a component.
One thing to note is that all components are categorised as either form components or report components. A component that is created from a form is categorised as the former and can only be pasted into a form, and similarly for reports. This is necessary since, although some objects (such as labels) can appear in both forms and reports, there are many (possibly most) cases where creating a component from one and pasting it into the other would not be a good idea.
When you save an object as a component, the object is positioned in the component at position (10,10) and the component is sized to be just 10 pixels wider, and 10 pixels higher, than is strictly needed. If you save mutiple objects, then they maintain their relative positions, but the top-left one is similarly moved to (10,10), and the component is made (10,10) pixels larger. There is no particular reason for these values, other than for convenience if you later edit the component.
Once you have a created a component this way, unless it was saved to a local file, it will appear under the Components tab of the main database window, just as do forms and reports. From there you can edit it further.
The advantage of creating a component from objects in an existing form or report is that they (presumably) already function in the way that you want. The one possible downside is that they might only function properly because thay are part of the form or report. Of course, it is perfectly possible to create components that will only work when used in a specific environment, but as a general principle, it is better to make components as independant of their environment as possible.
Creating and Editing ComponentsA completely new component can be created in much the same way as a form or report. Go to the Components tab of the main database window, and double click on the Create new component item. This brings up a dialog similar to that which appears when you create a new form or report (except rather simpler). The important setting is the type, either Form component or Report component. Note that this cannot be changed once set.
Once through the initial properties dialog, objects (labels, fields, etc.) can be added to the component almost exactly as they can to a form or report. The most noticable difference is that a component never has an associated query. This means that if you add a data control, such as a field, then there are no table columns shown when you come to set the display expression. If you know that you will only use the component in a situation where (for instance) a column called user_name exists and is to be displayed, then you might set the display expression to user_name, but this rather limits the places you can use the component ( You could change the display expression when you paste the component into a form or report, but in that case you might as well leave it blank in the component. ) . To help with this situation, however, you can make use of configuration properties.
When setting properties on objects, you may have noticed a property Configuration. This appears for all objects, but is mostly used in conjunction with components, where it provides a way of asking for and setting properties when the component is pasted. These are the settings that appear under the Configure tab of the component selection dialog. The screenshot below shows the properties dialog for the button which the stock first-record button provides, with the Configuration property selected. There is one configuration value, which provides the button text.
Normally, a configuration is associated with a property of the object, and the value in the configuration sets the value of the property when the component is pasted into a form or report. In the example above this provides the button text; the settings for this are:
Property | The property that this configuration value sets. | text is the property that specifies the text that the button displays. |
Legend | This is the text that appears under the Configure tab of the component selection dialog. | This should be set to some suitable prompt. |
Value | Default value to be used. | The default text for the first-record button is First. |
Type | Shows User, Required and Hidden settings; see below. | Shows U, R and/or H respectively. |
New configurations can be added by selecting a property, specifying a value and a legend, and clicking the Add button; configurations can be edited by clicking the Edit button (or by double- clicking the required entry), making changes and then clicking Add.
There are three additional settings for each configuration, User, Required and Hidden. When set, these show up as U, R and H in the Type column. If Required is set, then a value must be specified when the component is selected and pasted into a form or report. If Hidden is set, then then the configuration does not appear under the Configure tab of the component selection dialog. On its own, Hidden is not of much use, but is is useful in conjunction with the User setting, described below.
When the component is pasted into a form or report, the configuration values are used to set the corresponding properties. Then (unless User is set) the configuration values themselves are removed, and do not appear in the form or report definition.
The next screenshot shows the configuration settings for the stock search button. By default, the button initially shows the text Find. When clicked, the text changes to Go, and the user can enter search values into form fields (just as if the toolbar start-query button had been clicked). When clicked a second time, the query is executed and the button text returns to Find. To manage this, the component needs to incorporate two text values for the two button states.
In this example, the two configurations are both marked as User configurations. The immediate effect of this is that they are not removed when the component is pasted (so, if you paste the button into a form, and then look at the button properties, you will see that any User configurations are retained). Now, as they are retained in the form or report, they can be accessed by scripts. Getting a little ahead of ourselves (slots are described below), selecting the Slots property for this button, and then the blockAction slot, the dialog shown below would appear. In the script code, the bits like button.getConfig('text2') retrieve the configuration values (which are then used to set the button text).
Hence, in this example, the text configuration sets the initial button text, and then text and text2 are used as the query execution state switches back and forth.
Note that when User is set, the Property combobox is replaced by a text field, so that User configurations can be set to anything you like. In this example, the first is set to text since this is the property that sets the button text.