- In this lesson you will learn the following concepts
- Large projects
- Databases accessed by multiple projects
- Processes used in multiple projects
- Distribution a feature or set of features
- Cross-platform external components
- 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.10. Re-use code via external components
In this lesson you will learn 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. Projects cannot read or change the source code. This ensures confidentiality and stability of the source code.
Creating an external component is very simple.
How to proceed? Don't change anything, create your windows, procedures and classes. Then, when you're done, create a Component configuration with all the elements needed for your component, and generate. It's that simple!
A component can contain code, windows, an analysis, data files, etc!
|Five methods can be used to share "code" in WINDEV:|
- Sets of procedures.
- Supercontrols (via a dictionary).
- External components.
- 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 accidental changes!
External components allow you to have multiple small projects as well as a central project in which the elements of the other projects are visible. External components are a lot more convenient to use than libraries (WDL files).
Databases accessed by multiple 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.
Processes used in multiple projects
Complex processes are often used in several projects. These processes can be re-used via "sets of procedures" or "classes". In this case, changes may not be applied to the different projects, which makes these elements no longer compatible with each other.
Using external components prevents such out-of-sync modifications, keeps compatibility between projects and simplifies common changes.
Furthermore, the PRIVATE keyword allows you to set the privacy of your code at all levels of the external component. When reusing the external component in another WINDEV project, you will not be able to call a PRIVATE procedure but the documentation on the use of the procedure will be displayed!
Distribution a feature or set of features
The external components allow you to develop a feature or a set of features. Other developers will be able to include these features in their own WINDEV projects. Developers who use an external component can see the elements of the component that have been made visible. However, the source code cannot be viewed or modified.
You can distribute free or paid external components!
Cross-platform external components
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 elements coming from 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. The external component will be used to immediately find the customers of a given city in another application.
During the call to the external component, you will have the ability to:
- Pass a city as parameter.
- Retrieve a string containing the customer name and the total amount of their orders.
The "WD Full Application" project contains all the necessary elements to avoid writing the code required for the component.
- Open the project you worked on in the previous lesson.
- Go to the WINDEV home page (Ctrl + <).
- On the home page, click "Tutorial", then in "Part 4 - Full application with data", double-click "Full application (Exercise)".
- A dialogue box prompts you to open the project you worked on in the previous lesson. You can open the local copy or the original project. Select "Open the local copy".
|A corrected project is available. This project contains the different elements created in this lesson. To open the corrected project, go to the home page and click "Tutorial", then in "Part 4 - Full application with data", double-click "Full application (Answers)".|
- For the component needs, the project contains:
- a "QRY_OrdersByCity" query. This is a query with parameters used to identify the customers of 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 as parameter, a string containing the customer name and the total amount of the orders.
- the "DataLocation" procedure that is used to localize the data required by the component.
- an analysis to describe the data files that store the information.
- We are now going to create our component. To do so, we will create a project configuration.
|The project configurations are used to create several "targets" from the same project:|
You can choose the desired configuration and generate all the elements for all project configurations in a single operation, at any time.
- A 32-bit application,
- A 64-bit application,
- A component,
- To create a project configuration whose type is "Component":
- On the "Project" tab, in the "Project configuration" group, expand "New configuration" and select "External component (WDK)".
- The project configuration creation wizard starts. WINDEV proposes to create a "Component" project configuration. 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 included 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 identify 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 you want to enable.|
- We will generate the component.
- On the "Project" tab, in the "Generation" group, click "Generate".
- The component generation wizard starts. Go to the next step of the wizard. 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, we will only use the "SET_Component" set of procedures:
- Go to the next step.
- You can enable the translation of the component. This feature may be useful if the component must be used in multilingual applications.
If the "Allow component translation" option is checked, the specified elements of the component can be translated from the application that uses the component.
The elements will be translated via WDMSG, an independent module that extracts and reintegrates the project messages to be translated.
In this example, don't check this option. Go to the next step.
- Choose the component languages. Our example will be in English 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.
- Enter the component information:
- 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 understand the purpose of the component. Type for example:
- Go to the next step. The wizard will automatically generate the component documentation. This documentation can be based on the source code comments.
- Go to the next step. You have the ability to modify the generated documentation. Don't do anything. Go to the next step.
- You can create a help file associated with your component (CHM format). This help file will be provided along with the component. 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 published in the SCM. Go to the next step.
- Give a physical name to the component.
- Validate ("Finish"). 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 reused.
- To do so, we will create a new project and import the component into it.
- Close the current project: on the "Home" tab, in the "General" group, expand "Close" and select "Close project".
- Close the project and save changes if necessary.
- The WINDEV home page appears.
- Create a new project: click "Create a project" in the home page.
- This project will be a Windows application.
- Name this project "CompUse" and include no analysis.
- On the "Project" tab, in the "Project" group, expand "Import" and select "An External component ... From a file".
- In the directory of the "WD Full Application" project, select the "EXE\CompoOrdersByCity" subdirectory, 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 usable component elements.
|The component description can be accessed at any time. Simply select the component in the "Project explorer" pane and select "Description" in the context menu. In this case, you can also define the component loading mode.|
- Validate ("Close" button). The component is included in your project.
- We will create a blank window to use the component.
- Create a blank window.
- Enter "Customers by city" in the title.
- The window name becomes "WIN_Customers_by_city".
- Open the WLanguage events associated with the window (select "Code" in the context menu).
- We are going to call the DataLocation function of the component in the "End of initialization" event. This function expects as parameter the path used to access the data files handled by the component. Enter the access path to the data in the "WD Full Application" example. For example:
DataLocation(...// Specify the path of YOUR data
"C:\My Projects\My examples\WD Full Application (Exercises)\Exe\")
|If the project uses another procedure named "DataLocation", the name of the component procedure must be prefixed with the name of the set of procedures used. The code becomes:|
- Close the code editor.
- Add the following controls to the window:
- A text Edit control with "City" as caption and "EDT_City" as name.
- A Table control named "TABLE_Result", populated programmatically and containing 2 columns:
- a "Name" column of type Text.
- a "Total sales" column of type Currency.
- A Button control with "Search" as caption and "BTN_Search" as name.
- You can now edit the WLanguage events associated with "BTN_Search". The search procedure in the component will be executed when the control is clicked on. This procedure:
So, the code of the "Click" event from "BTN_Search" should:
- expects the city name as 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 WLanguage code:
- call the GiveOrdersByCity procedure of the component while passing the content of the EDT_City control as parameter.
- process the returned string to add it to the Table control.
ResultList is string
// Gets the list of customers and their orders
// for the specified city
ResultList = GiveOrdersByCity(EDT_City)
// If the list is not empty
IF ResultList <> "" THEN
// Clears the Table control
// Browses the results
FOR EACH STRING ACustomer OF ResultList SEPARATED BY CR
// Adds this client to the Table control
ELSE // If the list is empty
InfoBuild("No customer found for %1", EDT_City)
- Close the code editor and save your window.
- Test the window: click in the quick access buttons. In the edit control, enter "Paris" (keep uppercase and lowercase characters) and click "Search". The list of customers is displayed.
- That's it! Very simple, isn't it?
We have seen how to create a component and re-use it in the applications. You can also use setup procedures for you components, in order to distribute them separately from your applications, for example.
Distributing an external component
There are two methods to distribute a component:
- Provide the necessary files "manually", this is a "standard" distribution.
- Create a more "professional" distribution, via the WINDEV setup editor (WDInst).
In this case, you must provide all the files required for your component. These files are created when generating the component (WDI, WDK and WDO files, images, other documents, etc.). 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 provided for a standard distribution:
- files automatically generated by WINDEV (WDK, WDI, etc.).
- dependency files.
- if the component uses dependency files, the WDO file must be provided. 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 the 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, etc.).
- the automatic update of data files used by the component (if necessary).
- the component uninstall process.
- Close the "CompoUse" project: on the "Home" tab, in the "General" group, expand "Close" and select "Close project".
- Open the "WD Full Application" project you worked on previously (go to the home page, click "Open a project" and select "WD Full Application"). If necessary, select the project configuration corresponding to the component in the "Project explorer" pane.
- To create the setup, on the "Project" tab, in the "Generation" group, click "Setup procedure".
The component setup creation wizard starts.
We won't go into details about the different setup modes of a component. Follow the steps of the wizard.