- 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 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
13. External component in practice
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,
- 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 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>.WDK | Component 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>.WDI | Component 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>.WDZ | File 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>.WDO | Optional 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.
Note: 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: - Creating the external component.
- Developing the elements of the external component.
- Defining the advanced options of the external component.
- Generating the external component.
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 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. Basic distribution 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 propose a setup procedure for an external component: - Create the setup procedure of the external component directly from the quick access buttons:
- 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 installation 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. Note: When creating the installation of an application, the necessary files are created in the "<Project name>\EXE\INSTALL" subdirectory. Using an external component in an application You can reuse components at any time in your WINDEV applications. Simply import the component directory into the project. You can also import the component via the SCM. 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. 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.
Two methods can be used to update a component on the end-user computers: - Recompiling the host project
Recompile the project that uses the component, and redistribute the application with the component. In this case, no version problem or compatibility problem will occur. Compilation 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.
- ...
- Distributing the .WDK file directly
Publish a component update (.WDK file) 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. 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 applications 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 applications must always be greater than or equal to the version currently used.
This type of compatibility is automatically managed. 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: 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 component characteristics 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: Each time the component is re-generated, it is possible to re-generate the documentation associated with the component ("Regenerate" button)..
Caution: If you use the "Regenerate" button, the documentation changes made in the generation wizard will be deleted. 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 integrating a component into a project: in the "Project" pane, in the "Project" group, pull down "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".
- On 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).
Note: The code of this element is not visible though. - If the element is not accessible, the user will not even know that it 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 external component, multiple files are automatically created in the EXE directory of the current project: | | <Component name>.WDK | Contains all the WINDEV elements to be redistributed with the component (windows, reports, etc.). | <Component name>.WDI | Component 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>.WDZ | File 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 <Nom du composant>.WDO file: This file contains a 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\ComponentSelector\InitialState.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: \RadioButtonComponent\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. Example: The "Postcode" component uses a data file named "Cedex" (Cedex.fic and Cedex.ndx files). This data file is located in the EXE directory of the project in which the component has been created. To provide and install the component with the data file, the WDO file must be created in the EXE directory of the project in which the component has been created. This file must contain the following lines: 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.
|
|
|