Developing components

Home

4D v16.3

Since a component comes in the form of a 4D database, developing a component is similar to developing a functionality in a database. There are nevertheless certain restrictions and specific rules related to the nature of components.

Usable and unusable objects

A component can call on most of the objects of 4D: project methods, project forms, menu bars, choice lists, pictures from the library, and so on.

Only the following objects cannot be used by a component:

Standard 4D tables and fields (but you can create and use tables and fields using external databases),
Table forms and their associated form methods (on the other hand, a component can call a table form of the host database),
User forms,
Database methods and triggers.

It is not necessary to remove these elements if they exist in the matrix databases. When an “unusable” object is present, it is simply ignored once the component is installed.

Note: Users and groups as well as any access rights that may have been set in the matrix database are ignored in the host database.

Only project methods that are “shared” by the component are visible and can be selected in the host database in Design mode. On the other hand, project methods that are “shared” by the host database can be called by the component. For more information about this, refer to Sharing of project methods.

On forms that are "published" by the component are visible and can be integrated as subforms into forms of the host database. For more information about this, refer to Sharing of forms.

Other component objects (non-published project forms, choice lists, menus and so on) can be used by the component but will not be accessible as structure objects from the host database. Note that certain objects are partitioned and others are shared between the host database and the component(s). For more information about this, refer to Shared and unshared objects.

A component can use the plug-ins installed in the 4D application or in the host database. It is not possible to install plug-ins in the component folder.

The database methods and generic parameters of matrix databases (Web folder, Preferences, and so on) are never taken into account.

Unusable commands

The following commands are not compatible for use within a component because they modify the structure file — which is open in read-only. Their execution in a component will generate the error -10511, “The CommandName command cannot be called from a component”:

ON EVENT CALL
Method called on event
SET PICTURE TO LIBRARY
REMOVE PICTURE FROM LIBRARY
SAVE LIST
ARRAY TO LIST
EDIT FORM
CREATE USER FORM
DELETE USER FORM
CHANGE PASSWORD
EDIT ACCESS
Set group properties
Set user properties
DELETE USER
CHANGE LICENSES
BLOB TO USERS
SET PLUGIN ACCESS

Notes:

The Current form table command returns Nil when it is called in the context of a project form. Consequently, it cannot be used in a component.
Obviously, SQL data definition language commands (CREATE TABLE, DROP TABLE, etc.) cannot be used in the framework of components.

Error handling

An error-handling method installed by the ON ERR CALL command only applies to the running database. In the case of an error generated by a component, the ON ERR CALL error-handling method of the host database is not called, and vice versa.

Use of forms

Only “project forms” (forms that are not associated with any specific table) can be used in a component. Any project forms present in the matrix database can be used by the component.

A component can call table forms of the host database. Note that in this case it is necessary to use pointers rather than table names between brackets [] to specify the forms in the code of the component.
Note: If a component uses the ADD RECORD command, the current Input form of the host database will be displayed, in the context of the host database. Consequently, if the form includes variables, the component will not have access to it (see Interaction between components and host databases).

You can publish component forms as subforms in the host databases. This means that you can, more particularly, develop components offering graphic objects. For example, Widgets provided by 4D are based on the use of subforms in components. This is described in Sharing of forms.

Use of tables and fields

A component cannot use the tables and fields defined in the 4D structure of the matrix database. However, you can create and use external databases, and then use their tables and fields according to your needs. You can create and manage external databases using SQL. An external database is a 4D database that is independent from the main 4D database, but that you can work with from the main 4D database. Using an external database means temporarily designating this database as the current database, in other words, as the target database for the SQL queries executed by 4D. You create external databases using the SQL CREATE DATABASE command.

For more information about external databases, refer to About external databases.

Example

The following code is included in a component and performs three basic actions with an external database:

creates the external database if it does not already exist,
adds data to the external database,
reads data from the external database.

Creating the external database:

 <>MyDatabase:=Get 4D folder+"\MyDB" // (Windows) stores the data in an authorized directory

 Begin SQL

        CREATE DATABASE IF NOT EXISTS DATAFILE :[<>MyDatabase];

        USE DATABASE DATAFILE :[<>MyDatabase];

        CREATE TABLE IF NOT EXISTS KEEPIT

        (

        ID INT32 PRIMARY KEY,

        kind VARCHAR,

        name VARCHAR,

        code TEXT,

        sort_order INT32

        );

 

        CREATE UNIQUE INDEX id_index ON KEEPIT (ID);

 

        USE DATABASE SQL_INTERNAL;

 

 End SQL

Writing in the external database:

 $Ptr_1:=$2 // retrieves data from the host database through pointers

 $Ptr_2:=$3

 $Ptr_3:=$4

 $Ptr_4:=$5

 $Ptr_5:=$6

 Begin SQL

 

        USE DATABASE DATAFILE :[<>MyDatabase];

 

        INSERT INTO KEEPIT

        (ID, kind, name, code, sort_order)

        VALUES

        (:[$Ptr_1], :[$Ptr_2], :[$Ptr_3], :[$Ptr_4], :[$Ptr_5]);

 

        USE DATABASE SQL_INTERNAL;

 

 End SQL

Reading from an external database:

 $Ptr_1:=$2 // accesses data of the host database through pointers

 $Ptr_2:=$3

 $Ptr_3:=$4

 $Ptr_4:=$5

 $Ptr_5:=$6

 

 Begin SQL

 

    USE DATABASE DATAFILE :[<>MyDatabase];

 

    SELECT ALL ID, kind, name, code, sort_order

    FROM KEEPIT

    INTO :$Ptr_1, :$Ptr_2, :$Ptr_3, :$Ptr_4, :$Ptr_5;

 

    USE DATABASE SQL_INTERNAL;

 

 End SQL

Use of resources

Components can use resources (“conventional” Mac OS resources or XLIFF type files).

In conformity with the resource management principle (see Database Architecture), the resource files of components must be placed in a Resources folder, located next to the .4db or .4dc file of the component. If the component is of the .4dbase architecture (recommended architecture), the Resources folder must be placed inside this folder.

Automatic mechanisms are operational: the XLIFF files found in the Resources folder of a component will be loaded by this component. A component will also automatically use the “conventional” Mac OS resources located in the .rsr file next to the .4db or .4dc file. “Conventional” resource files located in the Resources folder must be explicitly loaded into the component using the commands of the “Resources” theme.

In a host database containing one or more components, each component as well as the host databases has its own “resources string.” Resources are partitioned between the different databases: it is not possible to access the resources of component A from component B or the host database (see Shared and unshared objects).

On-line help for components

A specific mechanism has been implemented in order to allow developers to add on-line help to their components. The principle is the same as that provided for 4D databases (see Appendix A: Assigning a custom help file):

The component help must be provided as a file suffixed .htm, .html or (Windows only) .chm,
The help file must be put next to the structure file of the component and have the same name as the structure file,
This file is then automatically loaded into the Help menu of the application with the title “Help for...” followed by the name of the help file.