ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

Help / WEBDEV concepts / Part 3 - Development environment
  • Overview
  • Definition
  • What is an external component composed of?
  • What elements are included in an external component?
  • Creating and generating an external component
  • Distributing an external component
  • Overview
  • Direct use of the external component
  • Standard distribution of external components
  • Distribution via a setup procedure
  • Using an external component in a website
  • Deploying a site containing an external component
  • Overview
  • Updating components and deployed websites
  • Modifying an external component
  • Overview
  • Types of compatibility
  • Advanced characteristics of external components
  • Automatic documentation
  • Component element visibility
  • WDO file
  • What is a 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
12. External component in practice
Previous pageTable of contentsNext page
Overview

Definition

An external component is a set of WINDEV, WEBDEV or WINDEV Mobile elements: windows, pages, reports, analysis, etc. This set of elements performs a specific operation. For example, a component can correspond to one of the following features:
  • Sending faxes,
  • Sending emails,
  • ...
Remarks:
  • 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 redistributed to other WINDEV, WEBDEV or WINDEV Mobile developers (free of charge or not). These developers will be able to easily integrate the feature included in the component into their application (or site). The component will therefore be integrated into and distributed with the application (or site).
When creating the external component, the author specifies:
  • which elements in the component are visible to the user. Visible elements will be accessible programmatically, or via the "Project explorer" pane.
  • 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.

What is an external component composed of?

An external component can be:
  • defined and generated from an existing WINDEV, WEBDEV or WINDEV Mobile project. A "Component" project configuration will allow you to select the elements of the existing project to be integrated into the component.
  • created from an "External component" project. By default, this project is composed of an "External component" platform which will contain the elements required to create and generate the component.
This external component can then be integrated into other WINDEV, WEBDEV or WINDEV Mobile projects.
All the elements of the component are totally independent of the project in which it is integrated. The external component can have its own analysis, windows, reports, data files, etc.
When generating the external component, simply specify if the project that uses the component will access these elements. The project will not be able to read or manipulate elements that are not accessible.
The external component consists of several files:
<Component name>.WDKComponent file. Contains all the elements of the external component.
This file is required to include the external component in a project.
This file must also be provided in the client version of the application that uses the external component.
<Component name>.WDIComponent description (when developing applications only).
This file is required to include the external component in a project.
This file must not be provided in the client version of the application that uses the external component.
<Component name>.WDZFile with the dependencies of the WDK file (only for WEBDEV and WINDEV Mobile components)
File containing the dependencies of the WDK file. This information is extracted in the project in which the component is integrated.
  • For a WEBDEV component, this file contains the generated WEBDEV pages, images, etc.
  • For a Mobile component (iOS or Android), this file contains the Android generation files, for example.
<Component name>.WDOOptional file
Text file containing the list of the additional elements provided with the external component (data files, .INI files, etc.). This file can be created manually or generated automatically from the items specified in the "Other" folder of the "Project explorer" pane. For more details, see WDO file.

What elements are included in an external component?

An external component contains:
  • the elements to be distributed (windows, reports, etc.). These elements can be accessible (or not) when importing the component into a WINDEV, WEBDEV or WINDEV Mobile project. These elements cannot be modified from the project that uses the component.
  • a short description of the component.
  • a help text to reuse the component. This help is generated from the code comments.
Remark: By default, if an external component uses an analysis and data files, the HFSQL functions will handle these elements in an independent HFSQL context. These parameters can be changed in the advanced options of the component. For more details, see Advanced options of an external component.
Creating and generating an external component
Below are the steps to create an external component:
  1. Creating the external component.
  2. Developing the elements of the external component.
  3. Defining the advanced options of the external component.
  4. Generating the external component.
The external component can be distributed and reused. For more details, see Distributing an external component and Using an external component in an application.
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 external component
    Example: the external component is directly used on the computer of the developer who created it.
  • Standard distribution, providing the necessary files.
    Example: the external 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.
  • Distribution via the SCM: This distribution mode allows all projects in the SCM to directly use a component published in the SCM. For more details, see SCM and components.
    Example: A company shares several projects via the SCM. The projects used to create the external components and the projects that use the components share the same SCM.
  • Distribution via a setup program (with a setup procedure of the component similar to the one used for the applications).
    Example: This distribution mode is recommended if the external component is intended to be sold or distributed on a large scale, with regular updates.

Direct use of the external component

The external component is created and used on the same computer.
When the external component is imported into a project, all you have to do is select the WDI file corresponding to the component. This file can be found in the EXE directory of the component project.
The generation directory is the directory associated with the "External component" project configuration.
Caution: The files in the <Component name>.WDO file will be automatically copied to the EXE directory of the project that uses the component.
If the external component uses specific files (data files, text files, etc.), a <Component name>.WDO file must be created (or completed) once the component is generated. This file contains the list of external files (data files, text files, etc.) used by the component. For more details, see WDO file.

Standard distribution of external components

The standard distribution of an external component consists in copying the files required by the component to a given location. The files are copied to a specific directory. This directory can be located on a network server, for example.
When the external component is imported into a project, all you have to do is select the WDI file corresponding to the component in the distribution directory.
To distribute an external component, you must provide:
  • The files automatically generated by WINDEV or WEBDEV (<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 Distributing an advanced component: WDO file.

Distribution via a setup procedure

The distribution of external components using a setup procedure requires providing a setup program to the users. This program installs all the files required for the external component in the directory specified by the user.
This installation mode allows you to automatically manage:
  • the WDO file and the installation of specific files (data files, etc.) used by the external component.
  • the installation of specific tools (MDAC, ODBC driver for HFSQL, etc.).
  • the automatic update of data files used by the external component (if necessary).
  • the uninstallation of the external component.
To create a setup procedure for an external component:
  1. Create the setup procedure of the external component directly from the quick access buttons:
  2. In the different steps of the wizard, specify:
    • the name of the external component.
    • the languages of the setup procedure.
    • the title of the main window of the setup program. You can configure the interface of the installer via the "Advanced" button.
    • the files installed. You can add specific files on top of the default component files. The WDO file will be automatically created from this list.
    • the default component setup directory. You can configure the changes to be made to the system via the "Advanced" button.
    • the optional modules to install.
    • the installation media, security options and advanced parameters.
    • ...
By default, the files required to install an external component are created in the "<Project name>\EXE\INSTALL_COMPO<Component name>" subdirectory.
Reminder: When creating the installation of an application, the necessary files are created in the "<Project name>\EXE\INSTALL" subdirectory.
Using an external component in a website
An external component can be reused at any time in any WEBDEV website: you just need to know the directory that contains the component files.
When a new version of the component is available, you just have to install the new files in the installation directory of the component (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.
If the component was distributed with a WEBDEV website, the component must be updated. For more details, see "Deploying a site containing an external component".
Deploying a site containing an external component

Overview

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:
  • <Component name>.WDK,
  • the files required for the component and the application.

Updating components and deployed websites

When updating a component and/or a deployed site, the following elements can be installed on the deployment computer of the site:
  • the site, the component and the necessary files.
  • the site and the files required for the site.
  • the component and any necessary files.
For more details on the compatibility between sites 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 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 new and earlier versions of the component.
  • ...
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 to run the site.
Modifying an external component

Overview

A component can be modified at any time once it has been created and generated. These are some of the changes that can be applied:
  • 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

Compatibility is linked to the versions of the component. If changes are made to the component, the sites that use the component may encounter runtime problems if they are not synchronized with it.
Compatibility is an important step when making changes to a component. There are two types of compatibility:
  • backward compatibility: the version of the component (.WDK file) used to compile the sites must always be greater than or equal to the version that has already been deployed.
    This type of compatibility is automatically managed. If the version of the component installed with the site is earlier than the version used by the site, the site will not run.
  • forward compatibility: you can prevent the use of a new version of a component with a project compiled using a previous version. You need to recompile the projects to use the new version of the component.
Advanced characteristics of external components

Automatic documentation

External components must include a technical documentation.
WINDEV, WEBDEV and WINDEV Mobile help you create this documentation via the following options:
  • A general overview of the component. This overview can be entered when generating the component.
  • A technical documentation generated automatically from the comments in 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 events:
    • Initialization code of windows or pages,
    • Initialization code of reports,
    • Initialization code of classes,
    • Initialization code of sets of procedures.
When is the documentation generated?
The documentation of the component is created the first time the component is generated ( in the quick access buttons).
When generating the documentation:
  • the comments in the code are used to create the documentation.
  • if there are no comments in your code, the expected input and output parameters of each accessible element of the component will be automatically included in the documentation. The corresponding comments are automatically created in the different elements.
Remark: The component documentation can be regenerated each time the component is generated ("Regenerate" button).

Caution: If you use the "Regenerate" option, the changes made to the documentation in the generation wizard will be lost.
How to access the component documentation?
The general component overview is automatically displayed in the component description window.
The technical documentation of the component is available:
  • when a component is included in a project: on the "Project" tab, in the "Project" group, expand "Import" and select "An External component".
  • in the description of the components included in the project.
    In the "Project explorer" pane:
    • In the "External components" folder, select the desired external component.
    • Right-click to open the context menu and select "Description".
    • In the "Details" tab, you can get the details of the generated documentation.
The documentation specific to an element of the component (window, etc.) can be viewed:
  • by double-clicking the desired element in the Project explorer pane or by pressing F2 in the code of the element.
  • from the "Project explorer" pane:
    • Select the "External components" folder.
    • Right-click to open the context menu.
    • Select "List of external components imported into the project".

Component element visibility

When you create a component, you can define which elements of the component will be accessible to end users.
  • If an element is accessible, the user will see it in the list of project elements. Users will be able to handle these elements programmatically (like any other element in the project).
    Remark: The code of this element is not visible.
  • If the element is not accessible, the user will not even know that it exists.
Caution: Depending on the declaration mode the of the project elements (classes, sets of procedures, etc.), the accessible elements may change.

WDO file

When generating the external component, multiple files are automatically created in the EXE directory of the current project:
<Component name>.WDKContains all the WINDEV elements to be redistributed with the component (windows, reports, etc.).
<Component name>.WDIComponent interface. This file contains:
  • a help text on how to use the component when it is reintegrated,
  • the elements required to use the component in the project (compilation information, etc.).
<Component name>.WDZFile with the dependencies of the WDK file (only for WEBDEV and WINDEV Mobile components)
File containing the dependencies of the WDK file. This information is extracted in the project in which the component is integrated.
  • For a WEBDEV component, this file contains the generated WEBDEV pages, images, etc.
  • For a Mobile component (iOS or Android), this file contains the Android generation files, for example.

These files must be distributed along with the component.
If the external component uses additional elements (data files, for example), the following files must be added in the project EXE directory:
  • a <Component name>.WDO file: This file contains the list of external files (data files, text files, etc.) used by the external component. These files must be provided and installed with the external component.
  • the files that must be distributed with the external component. These files can be in a specific subtree. In this case, the code of the external component 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 external component. These are also the files that must be provided and installed with the external component. These files must be copied to the EXE directory of the projects that use the external component.
This ".WDO" file can contain:
  • the full name of the file.
    For example: C:\ComponentsWD\PickerComponent\InitialStatus.INI
  • the file name. This file will be searched in the current directory of the external component.
    For example: InitialStatus.INI
  • a file name that uses a relative path. The available syntaxes are as follows:
    - Directory\FileName.xxx to specify a subdirectory of the current directory.
    - .\FileName.xxx to specify the current directory.
    - .\FileName.xx to specify the parent directory.
    For example: \PickerComponent\InitialStatus.INI
This file will be used when including the external component in the project. The paths specified in the WDO file must correspond to the paths where the files are installed on the development computer of the external component.
When including the external component, 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, you need to provide:
  • the WDK file (if necessary)
  • the WDI file
  • the WDO file
  • all the necessary files referenced in the WDO file.
Previous pageTable of contentsNext page
Comments
Click [Add] to post a comment

Last update: 02/15/2024

Send a report | Local help