- What is an external component made of?
- What is an external component made of?
- Creating and generating an external component
- Distributing an external component
- Direct use of the external component
- Simple distribution of external component
- Distribution via a setup procedure
- Using an external component in a site
- Deploying a site containing an external component
- Updating the components and the deployed sites
- Modifying an external component
- The different types of compatibility
- Advanced characteristics of external component
- Automatic documentation
- Visibility of component element
- The WDO file
- What is a WDO file?
12. External component in practice
An external component is a set of WEBDEV elements: pages, reports, analysis, ... This set of elements performs a specific feature. For example, a component can correspond to one of the following features:
- Sending faxes,
- Sending emails, ...
- To optimize the organization of your projects, you have the ability to use internal components. See Internal component for more details.
- In this chapter, we will refer to "external component" as "component".
An external component can be distributed to other WEBDEV developers (free of charge or not). These developers will be able to easily include the feature proposed by the component in their site. The component will be included in the site and distributed along with the site.
When creating the component, the author specifies:
- the origin of the component elements. The developer can build a component from a WINDEV project linked to a WEBDEV project and/or to a WINDEV Mobile project.
- the component elements visible (or not) to the component user. The visible elements will be accessible via the project explorer or by programming.
- the mode for using the component (how to use the component, the parameters used to access the component features, ...). A short documentation (to be completed) is automatically generated and associated with the component.
Note: Several examples of components are supplied with WEBDEV. These components are accessible from the home window.
What is an external component made of?
A component is defined and generated from an existing WEBDEV project. Then, it can be included in other WEBDEV projects.
All component elements are independent of the project in which the component is included. The component can have its own analysis, pages, reports, data files, etc, ... When creating the component generation, all you have to do is specify whether these elements can be handled (or not) in the WEBDEV project that includes this component.
The component includes three files:
|<ComponentName>.WDK||Component file. Contains all component elements.|
This file is required to include the component in a project.
This file must also be supplied in the setup procedure of the site that is using the component.
|<ComponentName>.WDI||Description of the component (when developing sites only).|
This file is required to include the component in a project.
This file must not be supplied in the setup procedure of the site that is using the component.
|<Component name>.WDO (optional file)||Optional file|
File in text format containing the list of additional elements supplied with the component (data files, .INI files, ...). See The WDO file.
What is an external component made of?
An external component contains:
- the different elements to distribute (pages, reports, ...). These elements can be accessible (or not) when the component is imported into a WEBDEV project.
- a short component description.
- a help allowing this component to be re-used. This help is generated from the code comments.
: By default, if a component is using an analysis, data files, ... the HFSQL functions will handle these elements in an independent context. These parameters can be modified in the advanced component options. See the online help for more details.
Creating and generating an external component
A component must be created from a project containing all elements required for the component to operate. Therefore, we recommend that you use a specific project to create each component
The component creation is performed in several steps:
- Developing the component elements.
- Creating the component.
- Defining the advanced component options.
- Generating the component.
Then, the component can be distributed and re-used.
Distributing an external component
Once the component was created, checked and generated, it can be made available to the developers. Several methods are available:
- direct use of the component
Example: the component is directly used on the computer of the developer who created it.
- simple distribution, by providing the necessary files.
Example: the component is intended to be used within the same company, by several developers. In this case, the necessary files can be copied onto a network drive.
- setup procedure of component (with a setup procedure of component identical to the one used for the applications).
Example: this distribution mode is recommended if the component is intended to be sold or distributed on a large scale, with regular updates.
Direct use of the external component
The component is created and used on the same computer.
When the component is imported into a WEBDEV project, all you have to do is select the WDI file corresponding to the component. This file is found in the EXE directory of component project.
Caution: If the component is using specific files (data files, text files, ...), a <ComponentName>.WDO file must be created once the component is generated. This file contains the list of external files (data files, text files, ...) used by the component.
These files referenced in <ComponentName>.WDO will be automatically copied into the EXE directory of the project that is using the WEBDEV component.
Simple distribution of external component
The simple distribution of a component consists in providing via simple copy the files required for the component to operate. The files are copied into a specific directory. This directory can be found on a network server for example.
When importing the component into a WEBDEV project, all you have to do is select the WDI file corresponding to the component in the distribution directory.
To distribute a component, you must supply:
- The files automatically generated by WEBDEV (<ComponentName>.WDK file and <ComponentName>.WDI file).
- If necessary, the specific files handled by the component (data files, initialization files, etc.) as well as <ComponentName>.WDO.
The <ComponentName>.WDO file contains the list of files that must be supplied with the component. See What is a WDO file? for more details.
Distribution via a setup procedure
The distribution of components via a setup procedure consists in supplying a setup program to the users of WEBDEV component. This program installs all the files required for using the component in the directory specified by the user.
This setup mode is used to automatically manage:
- the WDO file and the setup of specific files (data files, ...) used by the component.
- the setup of specific tools (MDAC, ODBC driver for HFSQL, ...).
- the automatic update of data files used by the component (if necessary).
- the uninstall program of component.
To propose a setup procedure for a component:
- Create the setup procedure of component : on the "Project" pane, expand "Deploy the site" and select "Deploy via physical media".
- In the wizard planes, specify:
- the setup media of component.
- the languages proposed in the setup procedure.
- the default setup directory of component.
- the optional modules to install. You have the ability to modify the list of files that will be distributed with the component. The WDO file will be automatically created from this list.
By default, the files required for installing a component are created in the INSTALL COMPO subdirectory of the project.
Reminder: When creating the setup program of an application, the necessary files are created in the INSTALL directory of the project.
Using an external component in a site
An external component can be re-used at any time in any WEBDEV site: all you have to do is identify the directory of component files.
When a new version of a component is available, all you have to do is install the new files of this update in the setup directory of component (according to the setup mode used).
If the component was published and imported via the SCM, the updates are proposed when opening the project that is using the component.
If the component was distributed with a WEBDEV site, the component must be updated. See "Deploying a site containing an external component" for more details.
Deploying a site containing an external component
The method for deploying a site that is using one or more components is the same as the method for deploying a standard site: on the "Project" pane, in the "Generation" group, expand "Deploy the site".
When deploying a site that uses a component, the following files are automatically installed on the server:
- the files required for the component and for the application to operate.
Updating the components and the deployed sites
When updating a component and/or a deployed site, you have the ability to install on the deployment computer of the site:
- the site, the component and the files required for them to operate.
- the site and the files required for the site to operate.
- the component and the files required for the component to operate.
Two methods can be used to update a component on the end-user computers:
1. Recompiling the host project
Recompile the project that uses the component and redistribute the site with the component. In this case, no version problem or compatibility problem will occur. The recompilation is required in the following cases:
- New features have been added into the component and they must be taken into account.
- The parameters of some procedures have been modified.
- Incompatibility between the new version and the earlier component versions.
2. Distributing the .WDK file directly
Provide an upgraded version of component (.WDK file) to the end users without recompiling the project.
In most cases, this possibility applies when:
- The new version is used to correct the problems of an earlier version.
- New features have been added to the component but they are not required for the site to operate.
Modifying an external component
A component that was created and generated can be modified at any time. This modification can correspond to:
- the addition of elements into the component.
- the deletion of elements from the component.
- the modification of rights on the component elements.
- the modification of one of the component elements.
In any case, after this modification, the component must be regenerated in order to take the modifications into account.
The different types of compatibility
The management of compatibility is linked to the component versions. Indeed, if modifications have been made to the component, the sites that use the component in deployment may encounter runtime problems if they are not synchronized with this component.
The management of compatibility is an important step in the modification of a component. Two types of compatibility are available:
- the backward compatibility: the component version (.WDK file) used to compile the sites that use this component must always be greater than or equal to the version currently used in deployment.
This compatibility is automatically supported. If the version of the component installed with the site is less than the version used by the site, the site will not operate.
- the forward compatibility: using a new component version with the projects compiled with an earlier version may not be allowed. Therefore, the projects must be recompiled in order to use the new component version.
Advanced characteristics of external component
A component must be supplied with a documentation in order to be re-used.
WEBDEV simplifies the creation of this documentation by proposing:
- a general overview of component. This general overview is typed when generating the component.
- an automatic generation of technical documentation from the comments inserted into the code of component elements.
Which code comments are taken into account?
The following comments are automatically taken into account for the component documentation:
- The comments found at the beginning of WLanguage procedures
- The comments found at the beginning of the following processes:
- Initialization code of pages,
- Initialization code of reports,
- Initialization code of classes,
- Initialization code of sets of procedures.
When is the documentation generated?
The component documentation is generated during the first generation of component ("Generate the configuration" option on the "Project" pane, in the "Generation" group).
When generating the documentation:
- the comments found in the code are used to create the documentation.
- if no comment is found, WEBDEV will automatically document the accessible elements of the component by specifying the input/output parameters expected by each element. The corresponding comments are automatically created in the different elements.
Note: Whenever re-generating the component, you have the ability to regenerate the documentation associated with the component ("Regenerate" button in the "History of component" window).
Caution: The modifications performed in the generation wizard will be deleted if you click the "Regenerate" button.
How to access the component documentation?
The general component overview and the technical component documentation are available:
- when including a component in a project (on the "Project" pane, in the "Project" group, expand "Import" and select "Import an external component").
- when double-clicking the component icon found in the "Project explorer" pane or when selecting "Description" from the popup menu of component.
To get the documentation specific to a component element, double click on it ("Project explorer" tab) or press F2 from its code.
Visibility of component element
When creating a component, you have the ability to define the component elements that will be accessible (or not) by the component user.
- If the element is accessible, the component user will see this element in the list of project elements. The component user will be able to handle these elements by programming (like any other project element).
Note: However, the code of this element is not visible.
- If the element is not accessible, the user will not even know that this element exists.
Caution: Depending on the declaration mode of project elements (class, set of procedures, ...), the accessible elements may change.
The WDO file
When generating the external component, two files are automatically created in the EXE directory of the current project:
|<ComponentName>.WDK||Contains all the elements that must be redistributed (pages, reports, ...) with the component|
|<ComponentName>.WDI||Interface of component. This file contains:|
- a help for using the component when it is checked back in
- the elements required for using the component in the project (compilation information, ...)
These two files must be distributed along with the component.
If the component uses additional elements (data files, etc.), the following elements must be added into the project EXE directory:
- a <ComponentName>.WDO file: this file contains the list of external files (data files, text files, ...) used by the component. These files must be supplied and installed with the component.
- the files that must be distributed with the component. These files can be placed in a specific tree structure. In this case, the component code must manage the access to these files in this tree structure.
What is a WDO file?
The <ComponentName>.WDO file is a file in TXT format that can be created and modified at any time. This file can be created and modified with Notepad, the standard text editor of Windows.
This file contains the list of external files (data files, text files, ...) used by the component and that must be supplied and installed with the component. These files must be copied into the EXE directory of the projects that is using the component.
This ".WDO" file can contain:
- the full name of file.
For example: C:\Components\PickerComponent\InitialStatus.INI
- the name of file. This file will be sought in the current directory of component.
For example : InitialStatus.INI
- a file name that is using a relative path.
The possible syntaxes are:
- Directory\FileName.xxx to specify a subdirectory of the current directory
- .\FileName.xxx to specify the current directory
- ..FileName.xx to indicate the parent directory
For example : \PickerComponent\InitialStatus.INI
This file will be used when the component is included in the project. The paths specified in the WDO file must correspond to the path where the files are installed on the development computer of component.
When including the component, the tree structure specified in the WDO file will be stored and reproduced in the EXE directory of project. See Using an external component in a site
for more details.
Example: The "Zip Code" component uses a "Cedex" data file (Cedex.fic and Cedex.ndx files). In the project for component creation, this data file is found in the EXE directory of project.
In order for the component to be supplied and installed with the data file, the WDO file must be created in the EXE directory of project for component creation. This file must contain the following lines:
Distributing a component with WDO
To distribute a component that is using a WDO file:
- If no setup procedure is used for the component, you must supply:
- the WDK file,
- the WDI file,
- the WDO file,
- all the necessary files referenced in the WDO file.
- If you are using a setup procedure for the component, the WDO file will be automatically created when creating the setup procedure of component.
In the wizard, you must:
- Ask to modify the files to install ("Modify the list of files to install" in the "Additional modules").
- Select the additional files to install.
The WDO file will be automatically created and installed with the component.
Click [Add] to post a comment