ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

Help / Developing an application or website / Component / External component
  • Overview
  • Creating the external component
  • Developing an external component
  • Remark
  • Advanced options of the external component
  • Defining and modifying the advanced options of the component
  • Access rights of the component on the client project
  • Style: Skin template of the component elements.
  • Generating an external component
  • Generating an external component
  • Generating an external component for Android
  • Generating an external component for iOS
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
Creating the external component
An external component can be created:
  • from an existing project, using an "External component" configuration. This configuration contains the elements of the project that are necessary for the external component to run properly.
  • from an "External component" project. By default, this project only contains an "External component" configuration.
To create an external component from an existing project:
  1. Create a project configuration for the external component: on the "Project" tab, in the "Project configuration" group, expand "New configuration" and select "External component (WDK)".
  2. The project configuration wizard starts and prompts you to define:
    • the name and description of the project configuration.
    • the compatibility options of the configuration: select the different platforms on which the external component can be used.
      Caution: depending on the selected platforms, it may be necessary to use a version of WINDEV with WEBDEV and WINDEV Mobile.
    • the compilation options: you can enable and disable compilation errors for 64-bit compatibility, Linux or compilation errors related to pre-launched sessions. Compilation errors related to pre-launched sessions are only available in Site configurations.
    • the elements to be integrated into the project configuration.
  3. Finish the wizard. The description of the "External component" project configuration is completed.
  4. You can select the "Component" project configuration in the "Project explorer" pane and start developing the external component.
To create an external component from a "Component" project:
  1. Click in the quick access buttons. In the window that appears, click "Project". The project creation wizard opens.
  2. Choose the type of project generation: "Component". Go to the next step.
  3. Specify:
    • the different platforms on which the external component can be used.
      Caution: depending on the selected platforms, it may be necessary to use a version of WINDEV with WEBDEV and WINDEV Mobile.
    • the compilation options: you can enable and disable compilation errors for 64-bit compatibility, Linux or compilation errors related to pre-launched sessions (this option is only available when generating a Site configuration).
  4. Go to the next step.
  5. Specify the different options of the project:
    • The name and location. These options cannot be modified. In WINDEV, the project corresponds to a ".WDP" file. This file can be opened by WEBDEV and WINDEV Mobile. For more details, see Common project.
      All the objects associated with the project will be created in the specified directory.
    • The description that summarizes the purpose of the project. This description is used in the project documentation.
  6. Go to the next step. The steps that appear next are the different steps to create a WINDEV, WEBDEV or WINDEV Mobile project.
  7. The project is created. This project contains a single project configuration. This project configuration is of type "Component".
Developing an external component
External components are developed just like any other WINDEV, WEBDEV or WINDEV Mobile project.
The following points must be taken into account when developing the different elements of an external component:
  1. Elements of the external component:
    For each element of your project, specify if it is associated with the "Component" project configuration.
    1. Select the element (window, report, etc.) in the "Project explorer" pane.
    2. Right-click to open the context menu and select "Configurations".
      In the menu that appears:
      • the checked configurations are those that are associated with the element.
      • the unchecked configurations are those that are not associated with the element.
      • "All" associates the element with all the configurations.
      • "None" dissociates the element from a configuration.
      • "Multiple" allows you to choose the configurations you want to associate the element with.
  2. Developing an external iOS or Android component
    You can create an Android or iOS component:
    • from a WINDEV Mobile version integrated into WINDEV,
    • from WINDEV Mobile.
    New windows will always be of type Windows. To create an Android or iOS window:
    • Create an Android or iOS configuration.
    • Create the window in this configuration. If the window already exists in the project, make sure it is associated with an iOS or Android configuration.
    • Associate the window with the component configuration.
  3. Code comments
    When developing the elements of the external component, don't forget to insert comments in your code. These comments will be used to create the component documentation. These comments will provide help to the users of your components. For more details, see Automatic documentation of components.
    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.
    For example:
    Description of input/output parameters of 'Window1':
    Parameters:
    Param1: <specify the role of Param1>
    Return value:
    None
  4. Declaration and visibility of the elements
    The user of the external component will have more or less access to the elements (classes, procedures, sets of procedures, etc.) depending on how they are declared. For more details, see Visibility of an element in an external component.
    Remark: If an external component uses an analysis and data files, the HFSQL functions will handle these elements in an independent HFSQL context. This operating mode can be modified in the advanced options of the component.
  5. To execute a procedure of the project that hosts the external component, use ExecuteProcess with the trtProjectProcedure constant.

Remark

An external component can include classes in its interface. You can derive these classes in the host project, override virtual methods and achieve polymorphism. The inheritance is available between several levels of external components.
Advanced options of the external component
The advanced options of the external component are used to define:
  • the access rights of the component on the elements of the application that use the component.
  • the management mode of skin templates on the component elements.

Defining and modifying the advanced options of the component

To modify the advanced options of the component:
  1. Open the description window of the "Component" configuration:
    • If the component configuration is currently open: on the "Project" tab, in the "Project configuration" group, click "Current configuration".
    • In the "Project explorer" pane, open the context menu of the component configuration and select "Description".
  2. Select the component.
  3. In the window that appears, in the "General" tab, click "Component options".

Access rights of the component on the client project

There are three options:
  • The component will not access the data files, windows, pages and reports of the client project.
    The component and its host application use independent contexts (default option). The component cannot handle the data files or the elements of the host project.
    You also have the ability to define the execution context of the component in the host project. The runtime context can be:
    • global. In this case, the same context will be used if the external component is loaded by the project and by another external component of the project.
    • isolated (by default). In this case, if the same component is loaded by the project and by a project component, each component will use a specific context.
    If this option is selected, the "Initialization" event of the component project will be called when the component is loaded by the host project.
  • The component will access the data files of the client project.
    The component is allowed to handle only the data files of the host application. In this case, the HFSQL contexts will be identical.
    If this option is selected, the "Initialization" event of the component project will be called when the component is loaded by the host project.
  • The component will access the data files, windows, pages and reports of the client project.
    The component is allowed to handle the data files of the host application as well as its elements (windows, reports, etc.). In this case, the execution contexts will be identical.
    If this option is selected, the "Initialization" event of the component project will not be called when the component is loaded by the host project.
When should the component be allowed to handle the data files of the host application?
When the final application consists of a main application and options provided as components. In this case, the components handle the data files of the main application.
Remark: If the component is allowed to handle the data files and if it has its own analysis, the component analysis will be ignored. The component will use the analysis of the host project.
In this example, the component can be associated with the analysis of the main application. Therefore, there is no need to use the external declarations to handle the data files. Furthermore, auto-completion suggestions will appear in the code editor.
For more details on HFSQL contexts, see HFSQL context.

Style: Skin template of the component elements.

By default, the skin template of the host project can be applied to the different elements of the external component. For more details on skin templates, see Skin templates.
Remarks:
  • You can allow or prevent the client project from applying the skin template. Go to the "Style" tab of the advanced options of the external component.
  • To avoid applying the skin template of the client project to a window of the external component:
    1. Open the component description window.
    2. In the "Style" tab, in "Skin templates", check "Always keep the initial style/skin template".
    3. Confirm.
Generating an external component
Once generated, an external component can be distributed and reused. All the files required to distribute the external component are generated along with the component. This generation can be done at any time from the component project configuration:
  • on the "Project" tab, in the "Generation" group, click "Generate".
  • in the quick access buttons, click the component generation icon: Generate a component
Remark: If the external component has been modified, it must be regenerated before it can be distributed again. For more details, see Modifying an external component.

Generating an external component

To generate an external component:
  1. Open the project configuration of the component to be generated, then go to the "Project" tab, "Generation" group and click "Generate".
  2. The external component generation wizard starts.
  3. Check "Recompile project before generating the component" (if necessary). Go to the next step.
  4. Select the elements of the external component that can be accessed from the project that uses it. Developers will be able to use accessible elements like any other element of the project. For more details, see Visibility of an element in an external component.
    Remark: The list of accessible elements corresponds to the elements associated with the project configuration of the current component.
    Go to the next step.
  5. Specify whether the external component can be translated. If the "Allow component translation" option is checked, you can select which elements of the component can be translated. Unchecked elements will not be available for translation.
    For more details, see Translating an external component.
    Go to the next step.
  6. If the project contains components, they can be included in the component that is being generated ("nested components" for example).
    Go to the next step.
  7. Specify whether the version number of the external component must be changed (when the external component is modified). For more details on how to manage the different versions of an external component, see Modifying an external component.
    Go to the next step.
  8. Specify the information about the external component: Owner, title, copyright, etc. This information will be displayed:
    • when the external component is integrated into a WINDEV, WEBDEV or WINDEV Mobile project.
    • in the properties of the WDI and WDK files in the Windows explorer ("PC SOFT" tab).
    Go to the next step.
  9. Select the image of the external component. This image will be used in the Windows explorer.
    Go to the next step.
  10. Type the general overview of the external component.
    This general overview will be automatically included in the external component description.
    Go to the next step.
  11. The generation wizard automatically presents the technical documentation associated with the external component.
    For more details on the rules for creating comments, see Automatic documentation of components.
    Go to the next step.
  12. Specify whether a help system (in CHM format) must be generated. This help system will be copied along with the component. The help system contains the technical documentation of the external component.
    Go to the next step.
  13. Indicate if the external component should be published in an SCM directory. This option is used to make the external component available to the projects of the SCM. For more details, see external component and SCM.
  14. If the generated component can be used by an Android platform, the Android component generation wizard opens. This wizard allows you to configure the Android-specific features of the component. For more details on the different steps, see Generating a component for Android.
  15. If the generated component can be used by an iOS platform, the iOS component generation wizard opens. This wizard allows you to configure the iOS-specific features of the component. For more details on the different steps, see Generating a component for iOS.
  16. Specify the physical name of the external component. This name will be assigned to the files corresponding to the external component.
  17. Confirm. The external component is generated.
The following files are created in the generation directory of the project configuration:
<Component name>.WDKThis file contains all the elements to be distributed (windows, reports, etc.).
This file is required when deploying applications that use the external component.
<Component name>.WDIInterface of the external component. This file contains:
  • a help text on how to use the external component when it is reintegrated.
  • the elements required to use the external component in the project (compilation information, etc.).
<Component name>.WDZThis file contains the dependencies of the WDK file (only for WEBDEV and WINDEV Mobile components). 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.

Caution: The generation of the external component may be quite long if the external component contains several accessible elements.

Generating an external component for Android

If the generated component can be used by an Android platform, the wizard will display the following additional steps:
  1. The Android SDK and Gradle are required to generate the Android component. You can:
    • Download and install these tools automatically. In this case, WINDEV Mobile downloads and installs all the necessary tools with the desired options. Only an Internet connection is required.
      This method is recommended. Caution: The first download can be quite long.
    • Use the tools automatically installed. This option is available if the tools have been downloaded and installed during a previous generation.
    • Use the tools already installed on your computer. In this case, you just need to specify the installation paths of Gradle and the Android SDK. For more details, see Installing the Android SDK.
    If you are using a proxy to access Internet, click the "Proxy" button to configure or check the Proxy management. For more details, see General options of WINDEV, WEBDEV and WINDEV Mobile.
  2. Go to the next step.
  3. Indicate the name of the package corresponding to the component. This name identifies the component. By default, it is composed of the company name (or its domain name in reverse order) followed by the name of the component. The name of the component will be in the default language of the project.
  4. Go to the next step.
  5. The component is generated for a fleet of devices. You can limit the size of the application by selecting a specific processor architecture.
    Note: If a device is connected to the PC, use the "Detect hardware automatically" option. Thus, next time an application is generated, this device will be automatically selected.
  6. Go to the next step.
  7. The list of files integrated into the component is displayed. This list is built from the files in the "Other" folder of the "Project explorer" pane. For example, you can integrate:
    • specific resources: images, ...
    • HFSQL data files used by the application, ...
    By default, the files included in the component are read-only ("Read" option checked). They can:
    • be used directly in the component in read-only mode.
      For example, if a read-only image is included in the Android component, it can be directly assigned to a control by specifying its name. For example:
      IMG_Image = image1
    • be programmatically extracted from the archive (fExtractResource). In this case, the file can be modified later.
    You can specify the destination directory in the APK file. The "Automatic" option is selected by default: the file is automatically placed in the right directory according to its type. You can also choose a specific directory.
    Remark: The "Asset" directory is also proposed. If the "Write" option is checked:
    • the file is automatically extracted when the application is started (before the project initialization code is executed).
    • you have the ability to specify an extraction directory. By default, the data files are extracted into the database directory (<DB Directory>)
      Caution: if the files in "Write" mode already exist on the mobile device, they will not be re-extracted.
  8. Go to the next step.
  9. Indicate if there are libraries to be integrated into the Android component. You can include:
    • specific Java libraries (*.jar or *.aar files).
    • native libraries (SO files).
    • the HFSQL library.
      This library is required if your component uses HFSQL data files.
  10. Go to the next step.
  11. The wizard prompts you to integrate remote dependencies (e.g., JCenter) into the Android component.
    It is also possible to specify additional repositories (other than JCenter and Google).
  12. Go to the next step.
  13. Select the permissions the component needs to work properly. The component must indicate to Android which services it needs to access in order to work properly (Internet, camera, etc.). WINDEV Mobile automatically adds the necessary permissions according to the statements used in the component.
    Remarks:
    • If you used procedures written in native Java code, you need to add the corresponding permissions.
    • Starting with Android 6, the permission is requested the first time the feature is used (before this version, all permission requests were added during the installation).
  14. Go to the next step.
  15. If the application that will use the component is available on Google Play, you can make the component available only for devices that support the features used by the application. For example, if your component uses inertial scrolling, you can make it available only for devices that support this feature.
    You can add or remove specific features.
  16. Go to the next step.
  17. Specify the configuration parameters.
  18. The component is compiled and generated.

Generating an external component for iOS

If the generated component can be used by an iOS platform, the wizard will display the following additional steps:
  1. Indicate if there are files to be included in the component.
    The list of files integrated into the component is displayed. Selected files are highlighted in blue. These files can be found in the "Other" folder of the "Project explorer" pane. For example, you can integrate:
    • specific resources.
    • specific images.
    • data files.
  2. Specify the options of the files:
    • If the "Write" option is checked for the files, they will be automatically extracted (e.g., files that must be modified by the application). In this case, specify the application directory in which each file must be extracted ("Documents" or "Library").
    • If the "Write" option is unchecked for the files, they can be:
      • used directly (files that will only be read, for example: sound files, image files, etc.). These files are included in the application and will not be extracted. fResourceDir is used to access these files in read-only mode.
      • extracted programmatically with fExtractResource.
        Caution: the iOS system is case-sensitive.
  3. Go to the next step.
  4. If you publish the iOS application that contains the component to the App Store, you must include a short description for each feature used. The first time the end user uses any of these features, an authorization window will display this description.
  5. Finish the wizard. The component is compiled and generated.
Minimum version required
  • Version 9
This page is also available for…
Comments
Click [Add] to post a comment

Last update: 02/28/2024

Send a report | Local help