- What is an external component made of?
- What elements are included in an external component?
- Creating and generating an external component
- Distributing an external component
- Direct use of the external component
- Simple distribution of external components
- Distribution via a setup procedure
- Using an external component in a site
- Deploying a site containing an external component
- Updating components and deployed sites
- Modifying an external component
- Types of compatibility
- Advanced characteristics of external components
- Automatic documentation
- Component element visibility
- 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 operation. For example, a component can correspond to one of the following features:
- Sending faxes,
- Sending emails, etc.
- To optimize the organization of your projects, you can use internal components. For more details, see Internal component.
- 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.
- which elements in the component are visible to the user. Visible elements will be accessible in the "Project explorer" pane or through programming.
- how to use the component (use mode, the parameters used to access the component functionalities, etc.). A short documentation (to be completed) is automatically generated and associated with the component.
Remark: Several examples of components are supplied with WEBDEV. These components can be accessed 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 the elements of the component are totally independent of the project in which it is integrated. 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 the elements of the component.|
This file is required to include the component in a project.
This file must also be provided in the setup procedure of the site that uses 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 provided in the setup procedure of the site that uses the component.
|<Component name>.WDO (optional file)||Optional file|
Text file containing the list of additional elements provided with the component (data files, .INI files, etc.). See WDO file.
What elements are included in an external component?
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 text to reuse the component. This help is generated from the code comments.
: By default, if a component uses an analysis, data files, etc, ... the HFSQL functions will handle these elements in an independent context. These parameters can be changed in the advanced component options. For more details, see the online help.
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 steps to create a component are as follows:
- Developing the component elements.
- Creating the component.
- Defining the advanced component options.
- Generating the component.
Then, the component can be distributed and reused.
Distributing an external component
Once the component has been created, tested and generated, it can be distributed to other developers. Multiple methods are available:
- direct use of the component
Example: the component is directly used on the computer of the developer who created it.
- basic distribution, by providing the required 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 to a network drive.
- component setup procedure (component setup procedure 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 located in the EXE directory of the component project.
Caution: If the component uses specific files (data files, text files, etc.), a <ComponentName>.WDO file must be created once the component is generated. This file contains the list of external files (data files, text files, etc.) used by the component.
These files referenced in the <ComponentName>.WDO file will be automatically copied to the EXE directory of the project that uses the WEBDEV component.
Simple distribution of external components
The basic distribution of a component consists in copying and sharing the files required for the component. The files are copied to a specific directory. This directory can be located 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 provide:
- 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 the <ComponentName>.WDO file.
The <ComponentName>.WDO file contains the list of files that must be provided with the component. For more details on this file, see What is a WDO file?.
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 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, etc.) 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 component uninstall process.
To provide a setup procedure for a component:
- Create the setup procedure of the component : on the "Project" tab, expand "Deploy site" and select "Generate and deploy site".
- In the different steps of the wizard, specify:
- the setup media of component.
- the languages proposed in the setup procedure.
- the default component setup directory.
- 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 reused 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 available updates appear when opening the project that uses the component.
If the component was distributed with a WEBDEV site, the component must be updated. For more details, see "Deploying a site containing an external component".
Deploying a site containing an external component
Sites that use one or more components are deployed in the same way as standard sites: on the "Project" tab, in the "Generation" group, expand "Deploy 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 the application.
Updating components and 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 any necessary files.
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 to the component and 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 the 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 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 can be modified at any time once it has been created and generated. Some of the changes that can be applied are as follows:
- add elements to the component.
- remove elements from the component.
- change rights on the elements of the component.
- make changes to one of the elements of the component.
In any case, the component must be regenerated to take these changes into account.
Types of compatibility
The 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 compatibility is an important step when making changes to a component. There are two types of compatibility:
- 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 type of compatibility is automatic. If the version of the component installed with the site is less than the version used by the site, the site will not operate.
- forward compatibility: a new version of the component cannot be used in projects compiled with a previous version. You need to recompile the projects to use the new version of the component.
Advanced characteristics of external components
A component must be provided with a documentation so it can be used again.
WEBDEV simplifies the creation of this documentation by proposing:
- a component overview. This general overview is typed when generating the component.
- an automatic generation of the technical documentation from the comments inserted into the code of the component elements.
Which code comments are taken into account?
The following comments are automatically taken into account to create the component documentation:
- Comments at the beginning of the WLanguage procedures
- Comments at the beginning of 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 documentation is generated when the component is generated for the first time ("Project" tab, "Generation" group, "Generate configuration").
When generating the documentation:
- the comments 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.
Remark: Whenever regenerating the component, you have the ability to regenerate the documentation associated with the component ("Regenerate" button in the "History of component" window).
Caution: The changes made in the generation wizard will be deleted if you click "Regenerate".
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" tab, in the "Project" group, expand "Import" and select "Import an external component").
- at any time, by double-clicking the icon of the component in the "Project explorer" pane, or via the "Description" option in the context menu of the component.
To get the documentation specific to a component element, double click on it ("Project explorer" tab) or press F2 from its code.
Component element visibility
When you create a component, you can define the elements of the component the end users will be able to access to.
- If the element is accessible, the user will see it in the list of project elements. The component user will be able to handle these elements through programming (like any other project element).
Remark: 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 the of the project elements (classes, sets of procedures, etc.), the accessible elements may change.
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||Component interface. This file contains:|
- a help text to use the component when it is reintegrated
- the elements required to use the component in the project (compilation information, etc.)
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, etc.) used by the component. These files must be provided 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 based on this tree structure.
What is a WDO file?
The <ComponentName>.WDO file is a TXT file that can be created and edited at any time. This file can be created and edited with Notepad, the Windows standard text editor.
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 to the EXE directory of the projects that use the component.
This ".WDO" file can contain:
- the full name of the file.
For example: C:\Components\PickerComponent\InitialStatus.INI
- the name of file. This file will be searched in the current directory of the component.
For example : InitialStatus.INI
- a file name that uses a relative path.
The possible syntaxes are:
- Directory\FileName.xxx to specify a subdirectory of the current directory
- .\FileName.xx 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 paths where the files are installed on the component development computer.
When the component is integrated, the tree structure specified in the WDO file will be kept and reproduced in the EXE directory of the project. For more details, see Using an external component in a site
Example: The "Zip Code" component uses a "Cedex" data file (Cedex.fic and Cedex.ndx files). This data file is located in the EXE directory of the component creation project.
To provide and install the component with the data file, the WDO file must be created in the EXE directory of the component creation project. This file must contain the following lines:
Distributing a component with a WDO file
To distribute a component that uses a WDO file:
- If no setup procedure is used for the component, you must provide:
- 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