PC SOFT

ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

Home | Sign in | English EN
  • Overview
  • Definition
  • 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
  • Overview
  • Direct use of the component
  • Basic distribution
  • Distribution via a setup procedure
  • Using an external component in an application
  • Deploying an application that uses an external component
  • Overview
  • Updating components and deployed executables
  • Modifying an external component
  • Overview
  • Types of compatibility
  • Advanced component characteristics
  • Automatic documentation
  • Component element visibility
  • WDO file
WINDEV
WindowsLinuxUniversal Windows 10 AppJavaReports and QueriesUser code (UMC)
WEBDEV
WindowsLinuxPHPWEBDEV - Browser code
WINDEV Mobile
AndroidAndroid Widget iPhone/iPadIOS WidgetApple WatchMac CatalystUniversal Windows 10 App
Others
Stored procedures
13. External component in practice
Previous pageTable of contentsNext page
Overview

Definition

An external component is a set of WINDEV elements: windows, reports, analysis, etc. This set of elements performs a specific operation. For example, an external component can correspond to one of the following actions:
  • Sending faxes
  • Sending emails, etc.
Remarks:
  • To optimize the organization of your projects, you can use internal components. For more details, see Internal components 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 functionality provided by the component in their applications. 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.
  • 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: WINDEV provides multiple examples on the use of components. 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 the elements of the component are totally independent of the project in which it is integrated. The component can have its own analysis, windows, reports, data files, etc. When you create the component generation, you can specify if these elements can be handled in the WINDEV project the component will be integrated into.
The component includes three files:
<Component name>.WDKComponent 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 application that uses the component.
<Component name>.WDIComponent 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.
<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?

A component contains:
  • the elements to be distributed (windows, reports, etc.). Some of these elements may not be accessible when the component is imported into the WINDEV project.
  • a short component description.
  • a help text to reuse the component. This help is generated from the code comments.
Remark: By default, if a component uses an analysis and data files, the HFSQL WLanguage 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 the elements required for the component. Therefore, we recommend that you use a specific project to create each component.
The steps to create a component are as follows:
  1. Developing the component elements.
  2. Creating the component.
  3. Defining the advanced component options.
  4. Generating the component.
The component can then be distributed and reused.
Distributing an external component

Overview

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 component

The component is created and used on the same computer. When importing the component into a WINDEV project, select the WDI file that corresponds 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.), it is necessary to create a <Component name>.WDO file once the component has been generated. This file contains the list of external files (data files, text files, and so on) used by the component.
The files in the <Component name>.WDO file will be automatically copied to the EXE directory of the project that uses the WINDEV component.

Basic distribution

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 WINDEV project, select the WDI file that corresponds to the component in the distribution directory.
To distribute a component, you must provide:
  • The files automatically generated by WINDEV (<Component name>.WDK and <Component name>.WDI files).
  • If necessary, the specific files handled by the component (data files, initialization files, etc.) as well as the <Component name>.WDO file.
The <Component name>.WDO file contains the list of files that must be provided with the component. For more details on this file, see WDO file.

Distribution via a setup procedure

The distribution of components via a setup procedure consists in providing a setup program to the users. 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, etc.).
  • the automatic update of data files used by the component (if necessary).
  • the component uninstall process.
To provide a setup procedure for a component:
  1. Create the setup procedure of the component: on the "Project" tab, click "Setup procedure".
  2. In the different steps of the wizard, specify:
    • the setup media of the component.
    • the languages of 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 an application
A component can be reused at any time in all WINDEV applications: simply import the directory of the component into the project. The component can also be imported via the SCM.
When a new version of the component is available, you just have to install the new files in the component setup directory (depending on the setup mode used). For more details on the different modes to install a component, see Distributing an external component.
If the component was published and imported via the SCM, the available updates appear when opening the project that uses the component.
The executable (that uses the component) is created in the same way as a WINDEV application. The DLLs required for the component are automatically detected.
Deploying an application that uses an external component

Overview

An application that uses one or more components is deployed in the same way as a standard application ("Setup procedure" on the "Project" tab).
When deploying an application that contains a component, the following files are automatically installed on the user computer:
  • <Component name>.WDK,
  • <Application name>.EXE,
  • the files required for the component and the application.

Updating components and deployed executables

When updating a component and/or an executable, the following elements can be installed on the end-user computer:
  • the application executable, the component and the necessary files.
  • the executable and the files required for the application.
  • the component and any necessary files.
For more details on the compatibility between applications and components, see Compatibility between external components and deployed applications.
Two methods can be used to update a component on the end-user computers:
  1. 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 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 are not required to run the application.
Modifying an external component

Overview

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. If changes are made to the component, the applications that use the component may encounter runtime problems if they are not synchronized with it.
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 applications must be greater than or equal to the version that has already been deployed.
    This type of compatibility is automatic. If the version of the component installed with the application is earlier than the version used by the application, the application will not run.
  • 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 component characteristics

Automatic documentation

A component must be provided with a documentation so it can be used again.
WINDEV allows you to easily create this documentation via:
  • a component overview. This overview can be entered 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 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 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" tab, "Generate").
When generating the documentation:
  • the comments in the code are used to create the documentation.
  • if there are no comments, WINDEV will automatically create the documentation for the accessible elements of the component based on the expected input and output parameters of each element. The corresponding comments are automatically created in the different elements.
Remark: Each time the component is generated, you can also regenerate the component documentation ("Regenerate" button in the "Component documentation" step of the wizard).
Caution: The changes made in the generation wizard will be deleted if you click "Regenerate".
How to access the component documentation?
The component overview and the technical documentation are available:
  • when a component is included in a project: on the "Project" tab, 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 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 how the project elements are declared (classes, sets of procedures, etc.), the elements that are accessible may change.

WDO file

When generating the component, two files are automatically created in the EXE directory of the current project:
<Component name>.WDKContains all the elements to be redistributed (windows, reports, etc.) with the component.
<Component name>.WDIComponent 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 to the project EXE directory:
  • a <Component name>.WDO file: this file contains the list of external files (data files, text files, and so on) 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 <Component name>.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, etc.) used by the component and to be provided 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 the 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 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 an application.
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:
.\CEDEX.Fic
.\CEDEX.NDX
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 the component.
    In the wizard, you must:
    1. Change the list of files to be installed ("Files installed" step, "Add" button).
    2. Select the additional files to be installed.
    The WDO file will be automatically created and installed with the component.
Previous pageTable of contentsNext page
Comments
Click [Add] to post a comment