- 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 component
- Simple distribution of component
- Distribution via a setup procedure
- Using an external component in an application
- Deploying an application that is using an external component
- Updating components and deployed executables
- Modifying an external component
- The different types of compatibility
- Advanced component characteristics
- Automatic documentation
- Visibility of component element
- The WDO file
13. External component in practice
An external component is a set of WINDEV elements: windows, reports, analysis, ... This set of elements performs a specific feature. For example, an external 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 in practice for more details.
- In this chapter, we will refer to "external component" as "component".
An external component can be distributed to other WINDEV developers (freely or not). These developers will be able to easily include the feature proposed by the component in their application. The component will be included in the application and distributed with the application.
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. Visible elements will be accessible in the "Project explorer" pane 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.
Remark: Several examples of components are supplied with WINDEV. These components are accessible from the WINDEV home page ("Open an example" option).
What is an external component made of?
A component is defined and generated from an existing WINDEV project. Then, it can be included in other WINDEV projects.
All component elements are independent of the project in which the component is included. The component can have its own analysis, windows, reports, data files, ... When creating the component generation, all you have to do is specify whether these elements can be handled (or not) in the WINDEV 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 application that is using the component.
|<ComponentName>.WDI||Component description (when developing applications only).|
This file is required to include the component in a project.
This file must not be supplied in the setup procedure of the application that is using the component.
(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?
A component contains:
- the different elements to distribute (windows, reports, ...). These elements can be accessible (or not) when importing the component into a WINDEV 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 WLanguage functions for HFSQL management 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 component
The component is created and used on the same computer.
When importing the component into a WINDEV 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 WINDEV component.
Simple distribution of 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 WINDEV 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 WINDEV (<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 The 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 WINDEV 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, click "Setup procedure".
- In the different steps of the wizard, 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 an application
A component can be re-used at any time in any WINDEV application: you just have to know the directory of component files and import it into the project. The component can also be imported via the SCM.
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). See Distributing an external component
for more details.
If the component was published and imported via the SCM, the updates are proposed when opening the project that is using the component.
The method for creating the executable that is using the component is the same as the method for creating the executable for a WINDEV application. The DLLs required for the component to operate are automatically detected.
Deploying an application that is using an external component
The method for deploying an application that is using one or more components is the same as the method for deploying a standard application ("Setup procedure" on the "Project" pane).
When deploying an application that contains a component, the following files are automatically installed on the user computer:
- the files required for the component and for the application to operate.
Updating components and deployed executables
When updating a component and/or a deployed executable, you have the ability to install on the end-user computer:
- the application executable, the component and the files required for them to operate.
- the application executable and the files required for the application 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:
- Recompiling the host project
Recompile the application that is using the component and redistribute the application 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.
- 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 into the component but they are not required to run the application.
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 applications 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 applications 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 application is less than the version used by the application, the application 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 component characteristics
A component must be supplied with a documentation in order to be re-used.
WINDEV simplifies the creation of this documentation by proposing:
- a general overview of component. This general overview is typed when generating the component. When the component is used in a WINDEV application, this overview will be visible when choosing the component to import into the project .
- 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:
- Comments at the beginning of WLanguage procedures
- Comments at the beginning of the following WLanguage events/processes:
- "Global declarations" event of windows,
- "Opening" event of reports,
- "Declaration" event of classes,
- "Declaration" event of sets of procedures.
When is the documentation generated?
The component documentation is generated during the first component generation ("Generate" option on the "Project" pane).
When generating the documentation:
- the comments found in the code are used to create the documentation.
- if no comment exists, WINDEV 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 re-generating the component, you have the ability to re-generate 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 a component is included 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" pane) 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).
Remark: 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 component, two files are automatically created in the EXE directory of current project:
|<ComponentName>.WDK||Contains all elements that will be redistributed (windows, 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, .etc.) 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 this 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, etc.) used by the component and that must be supplied and installed with the component. These files must be copied into the EXE directory of projects that use 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.xxx to specify 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.
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:
The WDO file will be automatically created and installed with the component.
- Ask to modify the files to install ("Modify the list of files to install" in the "Additional modules").
- Select the additional files to install.
Click [Add] to post a comment