- 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 uses an external component
- Updating components and deployed executables
- Modifying an external component
- Different types of compatibility
- Advanced component characteristics
- Automatic documentation
- Component element visibility
- 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 operation. 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. For more details, see Internal component in practice.
- 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 provided in the setup procedure of the application that uses 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 provided in the setup procedure of the application that uses 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 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 reused. This help is generated from the code comments.
: By default, if a component uses 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. 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 component creation is performed in several steps:
- Developing the component elements.
- Creating the component.
- Defining the advanced component options.
- Generating the component.
The component can then be distributed and reused.
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 uses 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 uses 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 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 the 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 reused 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 uses the component.
The executable (that uses the component) is created using the same method as for a WINDEV application. The DLLs required for the component to operate are automatically detected.
Deploying an application that uses an external component
An application that uses one or more components is deployed in the same way as 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 uses 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.
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 reused.
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 when the component is generated for the first time ("Project" pane, "Generate").
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: Each time you regenerate the component, you can regenerate the documentation associated with it ("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 a component is included in a project: on the "Project" pane, in the "Project" group, expand "Import" and select "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" pane) or press F2 from its code.
Component element visibility
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.
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 to the EXE directory of the 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 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.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). 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 WDO
To distribute a component that uses 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