- This lesson will teach you the following concepts
- The huge projects
- The databases accessed by several projects
- The processes used in several projects
- The ability to distribute a feature or set of features
- Multi-product external component
- Step by step
- Step 1 : Creating an external component
- Step 2 : Using the external component
- Distributing an external component
- Standard distribution
- Professional distribution
Lesson 4.11. Re-use code via the external components
This lesson will teach you the following concepts
- What is an external component?
- Creating an external component, step by step.
- Distributing an external component.
Estimated time: 40 mn
An external component is a building block that can be re-used in an unlimited number of projects (and therefore executables).
An external component allows you to have an identical process with a single source code to perform a given operation even if this process must be performed by several projects.
The projects that use an external component have access in the WINDEV editor to the name of objects, procedures or methods made visible by the component creator. The projects cannot see or modify the source code. This ensures confidentiality and stability of source code.
Creating an external component is child's play.
How to proceed? Don't change anything, create your windows, procedures, classes. Then, instead of choosing the option for creating the executable, choose the option for creating a component!
A component can contain code, windows, an analysis, data files, etc!
|Five methods can be used to share "code" in WINDEV:|
- The sets of procedures.
- The classes.
- The supercontrols (via a dictionary).
- The external components.
- The internal components.
Let's present some cases in which the external components can be useful.
A developer creates and maintains an external component that is made available to other developers. No risk of modifications "made by mistake"!
The huge projects
The external components allow you to have several small projects as well as a central project in which the elements found in the other projects are visible. The external components are a lot more convenient to use than the libraries (WDL files).
The databases accessed by several projects
When the same database is accessed by several projects, you often find inconsistencies in the database caused by modified or old source code. By grouping the operations used to access the database (at least in write mode) in an external component, a single source code must be checked and maintained ; therefore, the risks of database inconsistency are reduced.
Furthermore, using a component avoids recompiling the application when the analysis is modified.
The processes used in several projects
Complex processes are often used in several projects. These processes can be re-used via "sets of procedures" or "classes". In this case, the modifications may not be applied to the different projects, making these elements no longer compatible between themselves.
Using external components prevents such out-of-sync modifications, preserves the compatibility between projects and simplifies the common modifications.
Furthermore, the PRIVATE keyword allows you to ensure the confidentiality of your code at all levels of external component. When re-using your external component in another WINDEV project, the call to a PRIVATE procedure will not be allowed but the documentation regarding the use of procedure will be displayed!
The ability to distribute a feature or set of features
The external components allow you to develop a feature or a set of features. Other WINDEV developers will be able to include these features in their own projects. The developers who are using an external component can see the component elements that are made visible. However, the source code cannot be viewed or modified.
Your external components can be distributed (free of charge or not)!
Multi-product external component
An external component can be intended to operate in:
- a WINDEV application,
- a WEBDEV application,
- a WINDEV Mobile application,
- the three types of applications.
In this last case, WINDEV allows you to:
- include the elements coming from different products (WEBDEV and/or WINDEV Mobile) in the same external component.
- specify the corresponding WLanguage code for each runtime platform (for example, a window is displayed by Open in WINDEV and a page is displayed by PageDisplay in WEBDEV).
Step 1 : Creating an external component
We are going to create an external component from the "WD Full Application" project. This project is used to manage orders, products and customers. This external component will be used to immediately find out in another application the customers corresponding to a given city.
During the call to the external component, you will have the ability to:
- Pass a city in parameter.
- Retrieve a string containing the customer name and the total amount of his orders.
To avoid having to develop the code required for the component to operate, the "WD Full Application" project contains all necessary elements.
|If you did not create the windows in the previous lessons, you can follow this lesson by opening a corrected project: in the WINDEV home page (Ctrl + <), click "Tutorial" and select "Full application (With windows)".|
A full corrected application project is also available: in the WINDEV home page (Ctrl + <), click "Tutorial" and select "Full application (Answer)".
- For the component needs, the project contains:
- a "QRY_OrdersByCity" query. This query is a query with parameters used to find out the customers corresponding to a given city as well the total amount of their orders.
- a set of procedures "SET_Component". This set of procedures contains:
- the "GiveOrdersByCity" procedure that returns, for the city passed in parameter, a string containing the customer name and the total amount of his orders.
- the "DataLocation" procedure that is used to locate the data required by the component.
- an analysis used to described the data files for storing information.
- We are now going to create our component. To do so, a project configuration must be created.
|The project configurations are used to create several "targets" from the same project:|
You have the ability to choose the requested configuration at any time and to generate in a single operation all elements for all project configurations.
- A 32-bit application,
- A 64-bit application,
- A component,
- To create a project configuration whose type is "Component":
- On the "Project" pane, in the "Project configuration" group, expand "New configuration" and select "External component (WDK)".
- The wizard for creating a project configuration starts. WINDEV proposes to create a project configuration whose type is "Component". Go to the next step.
- Give a name to your project configuration: "CompoOrdersByCity" for example. Go to the next step.
- Keep the default options. Go to the next step.
- Select the elements that will be included in the project configuration. In this example, these elements will also be found in the component.
- Click the "None" button.
- Select the "QRY_OrdersByCity" and "SET_Component" elements.
- Go to the next step and validate the configuration creation.
- The new configuration automatically becomes the current configuration.
|To find out and modify the current configuration, use the "Project explorer" pane. The configuration in bold corresponds to the current configuration.
To change the current configuration, double-click the name of the configuration to enable.|
- We are now going to generate our component.
- On the "Project" pane, in the "Generation" group, click "Generate".
- The wizard for generating the component starts. Go to the next wizard step. WINDEV lists the elements that will be included in the component (elements specified in the configuration and analysis).
- Select all elements ("All" button) and go to the next step.
- The wizard asks you to select the component elements that will be accessible from the client application. In our example, only the set of procedures "SET_Component" will be used:
- Go to the next step.
- WINDEV proposes to allow the translation of component. This feature is interesting if your component must be used by multilingual applications.
If the option "Allow the component to be translated" is checked, the specified component elements can be translated from the application that is using the component.
This translation will be performed via WDMSG, independent module used to check out and check in the project messages to translate.
In this example, don't check this option. Go to the next step.
- Choose the component languages. Our example will contain the English language only. Go to the next step.
- The wizard proposes to manage the different component versions. In our example, the component was just created.
Keep the default options. Go to the next step.
- Type the information regarding the component:
- Caption, Copyright, ...
- Go to the next step.
- You have the ability to associate an image with your component. Go to the next step.
- Specify the main component overview. This overview will allow the user to find out the component purpose. Type for example:
- Go to the next step. The wizard will automatically generate the documentation about the component. This documentation can be based on the comments inserted into your source code.
- Go to the next step. You have the ability to modify the generated documentation. Don't do anything. Go to the next step.
- You have the ability to create a help file associated with your component (CHM format). This help file will be supplied along with the component. The users will be able to access it by pressing F1 from the component code.
We will generate no help file. Go to the next step.
- The component will not be saved in the SCM. Go to the next step.
- All we have to do now is give a physical name to our component.
- Validate. A message indicates that the component was generated. Click "End" to validate the message.
- Well done, you've just created your first ready-to-use component!
Step 2 : Using the external component
Once created, your component can be used in any other WINDEV project. Let's now see how this component can be re-used.
- To do so, we are going to create a new project and import our component into this project.
- Close the current project: on the "Home" pane, in the "General" group, expand "Close" and select "Close the project".
- Validate the closing of project and save the modifications if necessary.
- The WINDEV home page is displayed.
- Create a new project: click "Create a project" in the home page.
- This project is a Windows application.
- This project is named "CompUse" and it has no analysis.
- On the "Project" pane, in the "Project" group, expand "Import" and select "An external component .. From a file".
- In the directory of "WD Full Application" project, select the "EXE\CompoOrdersByCity" sub-directory, then the "CompoOrdersByCity.wdi" file.
|If the component was created from: |
- the "WD Full Application (Exercise)" example, select the "My Projects\My Examples\WD Full Application (Exercise)\EXE\CompoOrdersByCity" sub-directory, then the "CompoOrdersByCity.wdi" file.
- the "WD Full Application (with windows)" example, select the "My Projects\My Examples\WD Full Application (With windows) (Exercise)\EXE\CompoOrdersByCity" sub-directory, then the "CompoOrdersByCity.wdi" file.
- Click "Open", the description of our component is displayed. This description contains:
- On the "General" tab, the elements typed when creating the external component as well as its location.
- On the "Details" tab, the component description as well as the help that was automatically generated. This allows you to identify the re-usable component elements.
|The component description can be accessed at any time. All you have to do is select the component in the project explorer and select "Description" from the popup menu. In this case, you also have the ability to define the load mode of component.|
- Validate ("Close" button). The component is included in your project.
- We are now going to create a blank window to use the component.
- Create a blank window.
- The window title is "Customers by city".
- The window name is "WIN_Customers_by_city".
- Display the code associated with the window ("Code" from the popup menu).
- We are going to call the DataLocation function of component in the "End of initialization" event. This function expects in parameter the path used to access the data files handled by the component. Type the access path to the data found in the "WD Full Application" example. For example:
DataLocation(...// Specify the path of YOUR data
"WD Full Application\Exe")
|If your project is using another procedure named "DataLocation", the name of component procedure must be prefixed by the name of the set of procedures used. The code becomes:|
- Close the code editor.
- Add the following controls into the window:
- A text Edit control whose caption is "City" and whose name is "EDT_City".
- A Table control named "TABLE_Result", filled by programming and that includes 2 columns:
- a "Name" column of Text type.
- a "Total sales" column of Currency type.
- A button whose caption is "Search" and whose name is "BTN_Search".
- Edit the code of "BTN_Search" button. During a click on this button, we are going to run the search procedure found in the component. This procedure:
The code of "BTN_Search" button must:
- expects the city name in parameter
- returns a string in the following format:
Name of customer 1 + TAB + Total sales 1 + CR +
Name of customer 2 + TAB + Total sales 2 + ...
Write the following code:
- call the GiveOrdersByCity procedure of component while passing the content of EDT_City control in parameter.
- process the returned string in order to add it into the table.
sResultList is string
// Gets the list of customers and their orders
// for the specified city
sResultList = GiveOrdersByCity(EDT_City)
// If the list is not empty
IF sResultList <> "" THEN
// Clears the table
// Browses the results
FOR EACH STRING sACustomer OF sResultList SEPARATED BY CR
// Adds this customer to the table
ELSE // If the list is empty
InfoBuild("No customer found for %1", ...
- Run the window test by clicking the "GO" button found among the quick access buttons. In the edit control, type "Paris" (while respecting the case) and click the "Search" button. The list of customers is displayed.
- That's it! Child's play isn't it?
You know how to create a component and how to re-use it in your applications. You also have the ability to manage the setup procedures of your components, in order to distribute them separately from your applications for example.
Distributing an external component
Two methods can be used to distribute a component:
- Provide the necessary files "manually", this is a "standard" distribution.
- Create a more "professional" distribution, via the setup editor of WINDEV (WDInst).
In this case, you must supply all the files required for your component to operate. These files are created when generating the component (WDI, WDK and WDO files, images, other documents, ...). These files will be manually copied from their source directory to the destination directory. The WINDEV projects that use this component will find the dependent files in this destination directory.
List of files that must be supplied for a standard distribution:
- the files automatically generated by WINDEV (WDK, WDI, ...).
- the dependency files.
- the WDO file must be supplied if the component is using dependency files. This file contains the references to the external files used in the component.
The distribution of components via a setup procedure consists in providing 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 additional files used by the component.
- the automatic setup of necessary tools (MDAC, ODBC driver for HFSQL, ...).
- the automatic update of data files used by the component (if necessary).
- the uninstall program of component.
- Close the "CompoUse" project: on the "Home" pane, in the "General" group, expand "Close" and select "Close the project".
- Open the "WD Full Application" project that was used beforehand (for example, display the home page and select the "WD Full Application" project found in the recent projects). Select (if necessary) the project configuration corresponding to the component in the project explorer.
- To create the setup, go to the "Project" pane, "Generation" group, and click on "Setup procedure".
The wizard for creating the component setup starts.
We won't go into details about the different setup modes of a component. Follow the instructions given by the wizard.
See Distributing an external component
for more details.