- Plugin basics
- Introduction
- Platform overview
- Plugin guides
- First UI package
- Package registration
- First Backend package
- Portal package creation
- REST API
- REST API using
-
Request Formats
- HTTP GET: Getting a list of elements of type Entity
- HTTP GET: Getting a specific Element of the Entity Type
- HTTP PUT: Editing an Entity Type Element
- HTTP POST: Creating a new Element of Entity Types
- HTTP POST: Doing an Action for Element of Entity Types
- HTTP POST: Creating an new element Sub-Entity of Types
- HTTP DELETE: Deleting the element of Entity Types
- HTTP PATCH: Partially editing the element of Entity Types
- Handling Errors When Calling HTTP Methods
Creation of UI package "from scratch"
Prerequisites: Before getting started, you need to install nodejs and @angular/cli
This instruction is aimed for information purpose only and to understand better the principle of package developing. To save your time, efforts and to avoid usual mistakes, we kindly recommend to use the project templates source-code generator provided by the platform.
This guide provides information on building a basic plugin for the mef.dev technical preview platform. The basic plugin does not contain any business logic implementation. Its purpose is to provide the necessary structure for a plugin to work within the platform. Note: Tested with the following versions of @angular/cli: 12.2.17, 13.3.8, 14.2.11, 15.2.8, 16.0.3
1. Creation Angular project
Create a standard Angular application:
Note: You need to enable routing during project creation or add routing manually later.
ng new <app-name>
2. Adding dependencies
@natec/mef-dev-platform-connector
In the project, you can use almost any additional libraries. However, to work on the platform, you need to use @natec/mef-dev-platform-connector, which provides essential functionality for working with the platform. To add the package, run the following command:
npm i @natec/mef-dev-platform-connector@14.0.0
Note. Important:Make sure the installed version of mef-dev-platform-connector matches the version of Angular on your computer (you can check it by running the
ng v
command). You can find the version compatibility table here.
ngx-build-plus
To build the plugin, we use the resources provided by ngx-build-plus.
ng add ngx-build-plus@^14.0.0
Note. The version of ngx-build-plus should also match the installed version of Angular. You can refer to the version compatibility table below
Angular / CLI | ngx-build-plus |
---|---|
12 /12 | ngx-build-plus@^12.0.0 |
13 /13 | ngx-build-plus@^13.0.0 |
14 /14 | ngx-build-plus@^14.0.0 |
15 /15 | ngx-build-plus@^15.0.0 |
16 /16 | ngx-build-plus@^16.0.0 |
3. Changing the base selector
When generating a project using @angular/cli, a base component AppComponent
is generated with the selector app-root
. We need to replace it with the selector of our plugin. This parameter is reserved within the platform when creating a plugin and is named FrontendPluginName. In the example below, the project name from package.json
is used, but it's not mandatory. To make the change, follow these steps:
// src/app/app.component.ts
...
@Component({
selector: 'plugin-example', // 'app-root',
template: '<router-outlet></router-outlet>', // <-- також замінюємо стандартний вміст
styleUrls: ['./app.component.scss']
...
})
// src/index.html
...
<body>
<plugin-example></plugin-example> <!-- <app-root></app-root> -->
</body>
...
4. Routing changes
For proper routing functionality, ALL actual paths should be contained within the children section.
Note: Otherwise, when navigating within the plugin, the ENTIRE path will be modified (including platform navigation). This won't render the plugin inoperable, but further use of the platform will be unpredictable!
Additionally, to ensure correct navigation, the base paths should be passed through the updatePluginsRoutes(Routes) method. More details can be found here.
As a result, the declaration of paths should look as follows:
// src/app/app-routing.module.ts
import { PlatformHelper } from '@natec/mef-dev-platform-connector';
...
// const routes: Routes = [];
const routes: Routes = PlatformHelper.updatePluginsRoutes([
{
path:"",
children:[
// insert routes here
]
}
]);
...
5. Creating of first component
NOTE! Implementing the layout in AppComponent is not recommended. For further application development, it is recommended to extract all functionality into a separate component structure. Example
To achieve minimal functionality, you need to create one component:
ng g c test
After that, import it and add it to the routing configuration:
// src/app/app-routing.module.ts
import { PlatformHelper } from '@natec/mef-dev-platform-connector';
import { TestComponent } from './test/test.component';
...
// const routes: Routes = [];
const routes: Routes = PlatformHelper.updatePluginsRoutes([
{
path:"",
children:[
{
path:"",
redirectTo:"test",
pathMatch: 'full',
},
{
path:"test",
component: TestComponent
}
]
}
]);
...
6. Specification file version.json
To upload to the platform, the collection must include a specification file. It is generated by a script located at @natec/mef-dev-platform-connector.
Firstly, you need to create a src/environments
folder where the version.ts
file will be generated.
To generate the specification file, you need to execute the following command:
npm explore @natec/mef-dev-platform-connector -- npm run generate-version-file
The result of executing this command is the generation of the environments folder and its contents, which include a set of files containing information about the plugin build.
To copy the generated file into the build output, you need to add the path to the new asset in the configuration file.
// angular.json
...
"architect": {
"build": {
"options": {
...
"assets": [
"src/favicon.ico",
"src/assets",
"src/version.json" // <---
]
...
To modify the specification file before each build for publication, it is a good practice to set up npm scripts as shown in the example
The result of its operation can also be used within the application. Example.
7. Build and deploy
To build the plugin, you can use the following command:
ng build --output-hashing none --configuration production --single-bundle --output-path dist
Afterwards, you can upload the contents of the dist folder to the platform.
Useful links
The instructions for registering a plugin on the platform can be found in the following link: https://mef.dev/uk/dev_guides/upload_ui_plugin.md