extension guide and example (#623)

* extension guide and example

* code and guide fixes

* update dependencies
This commit is contained in:
Denys Vuika
2018-09-11 21:30:26 +01:00
committed by GitHub
parent c06b6e317b
commit c166f255b5
22 changed files with 616 additions and 65 deletions

View File

@@ -1567,3 +1567,229 @@ node: 10
You have successfully created a new menu button that invokes your custom action
and redirects you to the extra application route.
## Redistributable libraries
Extension libraries are based on the standard Angular libraries and definition files in the JSON format.
<p class="tip">
Please read more details in the following article: [Library support in Angular CLI 6](https://github.com/angular/angular-cli/wiki/stories-create-library#library-support-in-angular-cli-6)
</p>
### Creating extension library
First, generate a new project within the workspace:
```sh
ng generate library my-extension
```
You will get a new project in the `projects/my-extensions` folder.
By default, the project contains at least the following content:
* Example component `my-extension.component.ts`
* Example service `my-extension.service.ts`
* Angular Module example `my-extension.module.ts`
Next, build the project with the following command:
```sh
ng build my-extension
```
Angular CLI automatically configures Typescript path mappings for the project,
so that you do not need any additional steps to link the library.
#### Register dynamic components
Update `my-extension.module.ts` and put all the content you plan to use at runtime dynamically to the `entryComponents` section of the module.
```typescript
@NgModule({
imports: [],
declarations: [MyExtensionComponent],
exports: [MyExtensionComponent],
entryComponents: [MyExtensionComponent]
})
export class MyExtensionModule { }
```
Let's now register `MyExtensionComponent` as an extension component.
Update the code as in the next example:
```typescript
import { ExtensionService } from '@alfresco/adf-extensions';
@NgModule({...})
export class MyExtensionModule {
constructor(extensions: ExtensionService) {
extensions.setComponents({
'my-extension.main.component': MyExtensionComponent,
});
}
}
```
Now you can use `my-extension.main.component` identifier in the JSON definitions
if you want to reference the `MyExtensionComponent`.
#### Plugin definition file
Create a new `assets/my-extension.json` file in the library project root folder with the following content:
```json
{
"$schema": "../../../extension.schema.json",
"$version": "1.0.0",
"$name": "plugin1",
"$description": "demo plugin",
"routes": [
{
"id": "my.extension.route",
"path": "ext/my/route",
"component": "my-extension.main.component"
}
],
"features": {
"navbar": [
{
"id": "my.extension.nav",
"items": [
{
"id": "my.extension.main",
"icon": "extension",
"title": "My Extension",
"route": "my.extension.route"
}
]
}
]
}
}
```
Update the root `package.json` file and append the following entry to the `scripts` section:
```json
{
"scripts": {
...,
"build:my-extension":
"ng build my-extension && cpr projects/my-extension/assets dist/my-extension/assets --deleteFirst"
}
}
```
You can now use that script to build the library and copy assets to the output folder.
<p class="tip">
It is a good practice to provide installation instructions for your library in the `README.md` file.
Be sure to mention that developers should have a build rule to copy your plugin definition file to the `assets/plugins` folder of the main application.
</p>
### Publishing library to NPM
You should rebuild the library every time before publishing:
```sh
npm run build:my-extension
```
Go to the output folder and run the publish command.
```sh
cd dist/my-extension
npm publish
```
Note that requires for you have a valid [NPM](https://www.npmjs.com/) account.
<p class="tip">
See more details in the [Publishing your library](https://github.com/angular/angular-cli/wiki/stories-create-library#publishing-your-library) article.
</p>
### Consuming extension library
Assuming that you have published your extension library to NPM,
you can install it using the standard command:
```sh
npm install my-extension
```
That should install the library and all its dependencies.
<p class="warning">
You do not need installing library in the original workspace as the application is
already configured to use the local version from the `dist` folder.
</p>
#### Copy assets
Edit `angular.json` configuration file and add the following rule if you develop and test extension library in the same workspace
```json
{
"glob": "**/*.json",
"input": "dist/my-extension/assets",
"output": "/assets/plugins"
}
```
Use the following rule in case you are installing extension from NPM:
```json
{
"glob": "**/*.json",
"input": "node_modules/my-extension/assets",
"output": "/assets/plugins"
}
```
#### Register module
In the main application, edit the `src/app/extensions.module.ts` file and append the module declaration as in the next example:
```typescript
...
import { MyExtensionModule } from 'my-extension';
@NgModule({
...
imports: [
...,
MyExtensionModule
]
})
export class AppExtensionsModule {}
```
#### Register plugin
Finally, update the `assets/app.extensions.json` file and add a reference to the new plugin:
```json
{
"$references": [
...,
"my-extension.json"
]
}
```
### Testing library
Run the application and ensure you have an extra navigation sidebar entry:
```sh
npm start
```
Click the `My Extension` link and in the main content area you should see the extension component coming from your library.
<p class="warning">
Depending on the application setup, you may need enabling external plugins via the `Settings` dialog available for `admin` users (clicking the application profile button).
</p>