Componentes

Um componente 4D é um conjunto de código 4D e/ou formulários que representam uma ou mais funcionalidades que pode adicionar e usar nos seus projetos. For example, the 4D SVG component adds advanced commands and an integrated rendering engine that can be used to display SVG files.

You can develop and build your own 4D components, or download public components shared by the 4D community that can be found on GitHub.

When developing in 4D, the component files can be transparently stored in your computer or on a Github repository.

Componentes interpretados e compilados

Components can be interpreted or compiled.

• A 4D project running in interpreted mode can use either interpreted or compiled components.
• A 4D project running in compiled mode cannot use interpreted components. Por isso não pode ser usado em um componente.

Package folder

The package folder of a component (MyComponent.4dbase folder) can contain:

• for interpreted components: a standard Project folder
• for compiled components:
  • either a "Contents" folder containing a .4DZ file, a Resources folder, an Info.plist file (recommended architecture)
  • or directly a .4DZ file with other folders such as Resources.

nota

The "Contents" folder architecture is recommended for components if you want to notarize your applications on macOS.

Carregando componentes

nota

Esta página descreve como trabalhar com componentes nos ambientes 4D e 4D Server. In other environments, components are managed differently:

• in 4D in remote mode, components are loaded by the server and sent to the remote application.
• in merged applications, components are included at the build step.

Visão Geral

To load a component in your 4D project, you can either:

• copie os arquivos de componentes na pasta [Components do seu projeto] (architecture.md#components),
• or, declare the component in the dependencies.json file of your project; this is done automatically for local files when you add a dependency using the Dependency manager interface.

Os componentes declarados no arquivo dependencies.json podem ser armazenados em locais diferentes:

• at the same level as your 4D project's package folder: this is the default location,
• em qualquer lugar de sua máquina: o caminho do componente deve ser declarado no arquivo environment4d.json
• em um repositório GitHub: o caminho do componente pode ser declarado no arquivo dependencies.json ou no arquivo environment4d.json, ou em ambos os arquivos.

Se o mesmo componente for instalado em locais diferentes, uma ordem de prioridade é aplicada.

dependencies.json e environment4d.json

dependencies.json

O arquivo dependencies.json faz referência a todos os componentes necessários em seu projeto 4D. Esse arquivo deve estar localizado na pasta Sources da pasta do projeto 4D, por exemplo:

	/MyProjectRoot/Project/Sources/dependencies.json

Pode conter:

• names of components stored locally (default path or path defined in an environment4d.json file),
• names of components stored on GitHub repositories (their path can be defined in this file or in an environment4d.json file).

environment4d.json

O arquivo environment4d.json é opcional. Ele permite que você defina caminhos personalizados para alguns ou todos os componentes declarados no arquivo dependencies.json. This file can be stored in your project package folder or in one of its parent folders, at any level (up to the root).

The main benefits of this architecture are the following:

• you can store the environment4d.json file in a parent folder of your projects and decide not to commit it, allowing you to have your local component organization.
• se quiser usar o mesmo repositório GitHub para vários projetos, você poderá fazer referência a ele no arquivo environment4d.json e declará-lo no arquivo dependencies.json.

Prioridade

Since components can be installed in different ways, a priority order is applied when the same component is referenced at several locations:

Prioridade mais alta

1. Componentes armazenados na pasta Components do projeto.
2. Components declared in the dependencies.json file (the environment4d.json declared path overrides the dependencies.json path to configure a local environment).
3. Internal User 4D components (e.g. 4D NetKit, 4D SVG...)

Prioridade mais baixa

When a component cannot be loaded because of another instance of the same component located at a higher priority level, both get a specific status: the non-loaded component is given the Overloaded status, while the loaded component has the Overloading status.

Componentes locais

Você declara um componente local no arquivo dependencies.json da seguinte maneira:

{
    "dependencies": {
        "myComponent1" : {},
        "myComponent2" : {}
    }
}

... where "myComponent1" and "myComponent2" are the name of the components to be loaded.

By default, if "myComponent1" and "myComponent2" are not declared in an environment4d.json file, 4D will look for the component's package folder (i.e. the project root folder of the component) at the same level as your 4D project's package folder, e.g.:

	/MyProjectRoot/
	/MyProjectComponentRoot/

Graças a essa arquitetura, você pode simplesmente copiar todos os seus componentes no mesmo nível dos seus projetos e fazer referência a eles nos arquivos dependencies.json.

nota

If you do not want to use the dependencies.json architecture, you can install local components by copying their files in the Components folder of your project.

Personalizando caminhos dos componentes

If you want to customize the location of local components, you declare the paths for the dependencies that are not stored at the same level as the project folder in the environment4d.json file.

Você pode usar caminhos relativos ou absolutos (veja abaixo).

Exemplos:

{
	"dependencies": {
		"myComponent1" : "MyComponent1",
		"myComponent2" : "../MyComponent2",
    "myComponent3" : "file:///Users/jean/MyComponent3"
    }
}

nota

If a component path declared in the environment4d.json file is not found when the project is started, the component is not loaded and gets the Not found status, even if a version of the component exists next to the project's package folder.

Caminhos relativos versus caminhos absolutos

Os caminhos são expressos na sintaxe POSIX, conforme descrito em este parágrafo.

Os caminhos relativos são relativos ao arquivo environment4d.json. Absolute paths are linked to the user's machine.

Using relative paths is recommended in most cases, since they provide flexibility and portability of the components architecture, especially if the project is hosted in a source control tool.

Absolute paths should only be used for components that are specific to one machine and one user.

Componentes armazenados no GitHub

4D components available as GitHub releases can be referenced and automatically loaded and updated in your 4D projects.

nota

Regarding components stored on GitHub, both dependencies.json and environment4d.json files support the same contents.

Configurando o repositório GitHub

To be able to directly reference and use a 4D component stored on GitHub, you need to configure the GitHub component's repository:

• Compacte os arquivos de componentes no formato ZIP.
• Name this archive with the same name as the GitHub repository.
• Integrate the archive into a GitHub release of the repository.

These steps can easily be automated, with 4D code or using GitHub Actions, for example.

Declarando caminhos

Você declara um componente armazenado no GitHub no arquivo dependencies.json da seguinte maneira:

{
	"dependencies": {
		"myGitHubComponent1": {
			"github" : "JohnSmith/myGitHubComponent1"
		},
		"myGitHubComponent2": {}
	}
}

... where "myGitHubComponent1" is referenced and declared for the project, although "myGitHubComponent2" is only referenced. Você precisa declará-lo no arquivo [environment4d.json] (#environment4djson):

{
	"dependencies": {
		"myGitHubComponent2": {
			"github" : "JohnSmith/myGitHubComponent2"
		}
	}
}

"myGitHubComponent2" can be used by several projects.

Tags and versions

When a release is created in GitHub, it is associated to a tag and a version. The Dependency manager uses these information to handle automatic availability of components.

• Etiquetas são textos que fazem referência exclusiva a uma versão. Etiquetas são textos que fazem referência exclusiva a uma versão. In the dependencies.json file and environment4d.json files, you can indicate the release tag you want to use in your project. Por exemplo :

{
	"dependencies": {
		"myFirstGitHubComponent": {
			"github": "JohnSmith/myFirstGitHubComponent",
			"tag": "beta2"
		}
	}
}

• Uma versão também é identificada por uma versão. The versioning system used is based on the Semantic Versioning concept, which is the most commonly used. Each version number is identified as follows: majorNumber.minorNumber.pathNumber. In the same way as for tags, you can indicate the version of the component you wish to use in your project, as in this example:

{
	"dependencies": {
		"myFirstGitHubComponent": {
			"github": "JohnSmith/myFirstGitHubComponent",
			"version": "2.1.3"
		}
	}
}

A range is defined by two semantic versions, a min and a max, with operators '< | > | >= | <= | ='. O * pode ser usado como um espaço reservado para todas as versões. ~ and ^ prefixes define versions starting at a number, and up to respectively the next major and minor version.

Eis alguns exemplos:

• "latest": a versão com o selo "latest" nas versões GitHub.
• "*": a versão mais recente lançada.
• "1.*": todas as versões da versão principal 1.
• "1.2.*": todos os patches da versão menor 1.2.
• ">=1.2.3": the latest version, starting with the 1.2.3 version.
• ">1.2.3": the latest version, starting with the version just after the 1.2.3.
• "^1.2.3": the latest version 1, starting with the 1.2.3 version and strictly lower than version 2.
• "~1.2.3": the latest version 1.2, starting with the 1.2.3 version and strictly lower than version 1.3.
• "<=1.2.3": a versão mais recente até a 1.2.3.
• "1.0.0 - 1.2.3" ou ">=1.0.0 <=1.2.3": versão entre 1.0.0 e 1.2.3.
• "<1.2.3 || >=2": versão que não está entre 1.2.3 e 2.0.0.

If you do not specify a tag or a version, 4D automatically retrieves the "latest" version.

The Dependency manager checks periodically if component updates are available on Github. If a new version is available for a component, an update indicator is then displayed for the component in the dependency list, depending on your settings.

Repositórios privados

If you want to integrate a component located in a private repository, you need to tell 4D to use a connection token to access it.

Para fazer isso, em sua conta GitHub, crie um token classic com direitos de acesso a repo.

nota

For more information, please refer to the GitHub token interface.

You then need to provide your connection token to the Dependency manager.

Cache local para dependências

Referenced GitHub components are downloaded in a local cache folder then loaded in your environment. The local cache folder is stored at the following location:

• en macOs: $HOME/Library/Caches/<app name>/Dependencies
• no Windows: C:\Users\<username>\AppData\Local\<app name>\Dependencies

...onde <app name> pode ser "4D", "4D Server" ou "tool4D".

dependency-lock.json

A dependency-lock.json file is created in the userPreferences folder of your project.

This file logs information such as the state of dependencies, paths, urls, loading errors, as well as other information. It could be useful for component loading management or troubleshooting.

Monitoramento das dependências do projeto

In an opened project, you can add, remove, update, and get information about dependencies and their current loading status in the Dependencies panel.

Para exibir o painel Dependências:

• with 4D, select the Design/Project Dependencies menu item (Development environment),
  

• with 4D Server, select the Window/Project Dependencies menu item.
  

The Dependencies panel is then displayed. Dependencies are sorted by name in alphabetical order:

The Dependencies panel interface allows you to manage dependencies (on 4D single-user and 4D Server).

Filtering dependencies

By default, all dependencies identified by the Dependency manager are listed, whatever their status. You can filter the displayed dependencies according to their status by selecting the appropriate tab at the top of the Dependencies panel:

• Ativo: dependências carregadas e podem ser usadas no projeto. Isso inclui dependências overloading, que são de fato carregadas. Overloaded dependencies are listed in the Conflicts panel, along with all conflicting dependencies.
• Inativo: dependências que não estão carregadas no projeto e não estão disponíveis. There are many possible reasons for this status: missing files, version incompatibility...
• Conflito: dependências carregadas, mas que sobrecarregam pelo menos outra dependência em um nível de prioridade inferior. Overloaded dependencies are also displayed so that you can check the origin of the conflict and take appropriate actions.

Dependency status

Dependencies requiring the developer's attention are indicated by a status label at the right side of the line and a specific background color:

Estão disponíveis as seguintes etiquetas de status:

• Overloaded: a dependência não é carregada porque está sobrecarregada por outra dependência com o mesmo nome em um [nível de prioridade] mais alto (#prioridade).
• Overloading: a dependência está carregada e está sobrecarregando uma ou mais dependências com o mesmo nome em um [nível de prioridade] inferior (#prioridade).
• Not found: a dependência está declarada no arquivo dependencies.json, mas não foi encontrada.
• Inactive: a dependência não é carregada porque não é compatível com o projeto (por exemplo, o componente não é compilado para a plataforma atual).
• Duplicated: The dependency is not loaded because another dependency with the same name exists at the same location (and is loaded).
• Available after restart: The dependency reference has just been added or updated using the interface, it will be loaded once the application restarts.
• Unloaded after restart: The dependency reference has just been removed using the interface, it will be unloaded once the application restarts.
• Update available <version>: A new version of the GitHub dependency matching your component version configuration has been detected.
• Refreshed after restart: The component version configuration of the GitHub dependency has been modified, it will be adjusted the next startup.
• Recent update: A new version of the GitHub dependency has been loaded at startup.

A tooltip is displayed when you hover over the dependency line, provding additional information about the status:

Dependency origin

The Dependencies panel lists all project dependencies, whatever their origin, i.e. wherever they come from. The dependency origin is provided by the tag under its name:

As seguintes origens são possíveis:

Origin tag	Descrição
Componente 4D	Componente 4D incorporado, armazenado na pasta Components da aplicação 4D
dependencies.json	Component declared in the dependencies.json file
Environment	Componente declarado no arquivo environnement4d.json
Componente do projeto	Componente localizado na pasta Components

Clique com o botão direito do mouse em uma linha de dependência e selecione Mostrar no disco para revelar o local de uma dependência:

nota

This item is not displayed if the dependency is inactive because its files are not found.

Component icon and location logo provide additional information:

• The component logo indicates if it is provided by 4D or a third-party developer.
• Local components can be differentiated from GitHub components by a small icon.

Adding a local dependency

To add a local dependency, click on the + button in the footer area of the panel. A caixa de diálogo abaixo é mostrada:

Certifique-se de que a aba Local esteja selecionada e clique no botão .... A standard Open file dialog box is displayed, allowing you to select the component to add. You can select a .4DZ or a .4DProject file.

If the selected item is valid, its name and location are displayed in the dialog box.

If the selected item is not valid, an error message is displayed.

Clique em Adicionar para adicionar a dependência ao projeto.

• If you select a component located next to the project package folder (default location), it is declared in the dependencies.json file.
• If you select a component that is not located next to the project package folder, it is declared in the dependencies.json file and its path is declared in the environment4d.json file (see note). The Dependencies panel asks if you want to save a relative or absolute path.

nota

If no environment4d.json file is already defined for the project at this step, it is automatically created in the project package folder (default location).

The dependency is added to the inactive dependency list with the Available after restart status. It will be loaded once the application restarts.

Adding a GitHub dependency

Para adicionar uma dependência GitHub, clique no botão + na área de rodapé do painel e selecione a aba GitHub.

Enter the path of the GitHub repository of the dependency. It could be a repository URL or a github-account/repository-name string, for example:

Once the connection is established, the GitHub icon is displayed on the right side of the entry area. You can click on this icon to open the repository in your default browser.

nota

If the component is stored on a private GitHub repository and your personal token is missing, an error message is displayed and a Add a personal access token... button is displayed (see Providing your GitHub access token).

Define the dependency version range to use for this project. By defaut, "Latest" is selected, which means that the lastest version will be automatically used.

Clique no botão Adicionar para adicionar a dependência ao projeto.

The GitHub dependency declared in the dependencies.json file and added to the inactive dependency list with the Available at restart status. It will be loaded once the application restarts.

Defining a GitHub dependency version range

Você pode definir a opção tag ou versão para uma dependência:

• Latest: Selected by default and allows to download the release that is tagged as the latest (stable) version.
• Up to Next Major Version: Define a semantic version range to restrict updates to the next major version.
• Up to Next Minor Version: Similarly, restrict updates to the next minor version.
• Exact Version (Tag): Select or manually enter a specific tag from the available list.

The current GitHub dependency version is displayed on the right side of the dependency item:

Modifying the GitHub dependency version range

You can modify the version setting for a listed GitHub dependency: select the dependency to modify and select Modify the dependency... from the contextual menu. In the "Modify the dependency" dialog box, edit the Dependency Rule menu and click Apply.

Modifying the version range is useful for example if you use the automatic update feature and want to lock a dependency to a specific version number.

Updating GitHub dependencies

The Dependency manager provides an integrated handling of updates on GitHub. The following features are supported:

• Automatic and manual checking of available versions
• Automatic and manual updating of components

Manual operations can be done per dependency or for all dependencies.

Checking for new versions

Dependencies are regularly checked for updates on GitHub. This checking is done transparently in background.

nota

If you provide an access token, checks are performed more frequently, as GitHub then allows a higher frequency of requests to repositories.

In addition, you can check for updates at any moment, for a single dependency or for all dependencies:

• To check for updates of a single dependency, right-click on the dependency and select Check for updates in the contextual menu.

• To check for updates of all dependencies, click on the options menu at the bottom of the Dependency manager window and select Check for updates.

If a new component version matching your component versioning configuration is detected on GitHub, a specific dependency status is displayed:

You can decide to update the component or not.

If you do not want to use a component update (for example you want to stay with a specific version), just let the current status (make sure the Automatic update feature is not checked).

Updating dependencies

Updating a dependency means downloading a new version of the dependency from GitHub and keeping it ready to be loaded the next time the project is started.

You can update dependencies at any moment, for a single dependency or for all dependencies:

• To update a single dependency, right-click on the dependency and select Update <component name> on next startup in the contextual menu or in the options menu at the bottom of the Dependency manager window:

• To update all dependencies at once, click on the options menu at the bottom of the Dependency manager window and select Update all remote dependencies on next startup:

In any cases, whatever the current dependency status, an automatic checking is done on GitHub before updating the dependency, to make sure the most recent version is retrieved, according to your component versioning configuration.

When you select an update command:

• a dialog box is displayed and proposes to restart the project, so that the updated dependencies are immediately available. It is usually recommended to restart the project to evaluate updated dependencies.
• if you click Later, the update command is no longer available in the menu, meaning the action has been planned for the next startup.

Automatic update

The Automatic update option is available in the options menu at the bottom of the Dependency manager window.

When this option is checked (default), new GitHub component versions matching your component versioning configuration are automatically updated for the next project startup. This option facilitates the day-to-day management of dependency updates, by eliminating the need to manually select updates.

When this option is unchecked, a new component version matching your component versioning configuration is only indicated as available and will require a manual updating. Unselect the Automatic update option if you want to monitor dependency updates precisely.

Providing your GitHub access token

Registering your personal access token in the Dependency manager is:

• mandatory if the component is stored on a private GitHub repository,
• recommended for a more frequent checking of dependency updates.

To provide your GitHub access token, you can either:

• click on Add a personal access token... button that is displayed in the "Add a dependency" dialog box after you entered a private GitHub repository path.
• or, select Add a GitHub personal access token... in the Dependency manager menu at any moment.

You can then enter your personal access token:

You can only enter one personal access token. Once a token has been entered, you can edit it.

The provided token is stored in a github.json file in the active 4D folder.

Removing a dependency

To remove a dependency from the Dependencies panel, select the dependency to remove and click on the - button of the panel or select Remove the dependency... from the contextual menu. You can select several dependencies, in which case the action is applied to all selected dependencies.

nota

Somente as dependências declaradas no arquivo dependencies.json podem ser removidas usando o painel Dependencies. If a selected dependency cannot be removed, the - button is disabled and the Remove the dependency... menu item is hidden.

É exibida uma caixa de diálogo de confirmação. Se a dependência foi declarada no arquivo environment4d.json, uma opção permite que você a remova:

If you confirm the dialog box, the removed dependency status is automatically flagged "Unload after restart". It will be unloaded once the application restarts.