Custom Client CLI @eo-sdk/cli

Extension for angular-cli project

• CLI for Angular application (@eo-sdk/client) based on the ember-cli project.

Prerequisites

Both the CLI and generated project have dependencies that require Node 10.8.0 or higher, together with NPM 6.2.0 or higher.

Table of Contents

• Installation
• Updating Custom client CLI
• Usage
• Generating and starting Custom client project
• Building and testing Custom client project
• Generating Plugins, States, Actions, Links and Labels
• Plugins
• States
• Actions
• Links
• Generating Components, Directives, Pipes and Services
• Documentation
• License

Installation

BEFORE YOU INSTALL: please read the prerequisites

Installation of global packages is required

• @eo-sdk/cli (eo)
• @angular/cli (ng)

npm install -g @eo-sdk/cli@current
eo cli

Updating Custom client CLI

To update Custom client CLI to a new version, you must update both the global package and your project's local package.

Global package:

eo uninstall-cli
npm uninstall -g @eo-sdk/cli
npm cache verify
#install latest version 
npm install -g @eo-sdk/cli
eo cli

Local project package to latest version:

# to install current version (@eo-sdk/client@current)
eo update

# to install specific version (@eo-sdk/[email protected])
eo update [email protected]

# to install stable version (@eo-sdk/client@stable)
eo update --@stable

! BEFORE UPDATE - CLOSE RUNNING PROJECT / LOCALHOST!

In case you discover errors after update, try to cleanup the project and run update again:

# remove node_modules
rimraf node_modules
eo update
npm install

Usage

eo help

Generating and starting Custom client project

Basic concept of Custom client project is to combine multiple modules:

• EoCustomClientModule - from new Custom client project
• EoCoreModule - from @eo-sdk/core library
• EoClientModule - from @eo-sdk/client library
• EoFrameworkModule - from @eo-sdk/client library
• EoFrameworkCoreModule - from @eo-sdk/client library

and build single application into dist folder.

! DO NOT MODIFY FILES INSIDE ASSETS/_DEFAULT FOLDER !

All services are running via proxy, so you need to start proxy server.

eo new PROJECT-NAME
cd PROJECT-NAME
# to run application
npm start
# to run initial commit
git add -A 
git commit -m "initial commit"

In case you want to clone custom client project with all examples:

eo new PROJECT-NAME --#custom-client

Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.

You can configure the default HTTP host and port used by the development server with two command-line options :

# you have to change start script in package.json
npm start -- --host 0.0.0.0 --port 4222

You can configure proxy settings via custom proxy.config.json file with command-line option :

# you have to change start script in package.json
ng serve --proxy-config ./proxy.config.json

Building and testing Custom client project

To run build process use these commands:

npm run build
npm run build:prod

After successful build (./dist/), output folder (./output/) is generated containing zip file.

To run local test use angular cli.

npm run test
npm run e2e

Generating Plugins, States, Actions, Links and Labels

You can use the eo generate (or just eo g) command to generate Angular components:

eo generate plugin my-new-component
eo g plugin my-new-component # using the alias

Plugins

New plugin component can extend functionality of existing states and components. There are multiple insert points across the application (component-type.location):

• object-details-tab.favorite
• object-details-tab.inbox
• object-details-tab.notifications
• object-details-tab.object
• object-details-tab.process
• object-details-tab.result
• object-details-tab.version
• inbox-details-tab.inbox
• process-details-tab.process

You can insert plugin into a specific point or multiple points via simple configuration. Each plugin component requires properties (see EoPlugin):

• id - string representing tab ID | labelKey for translation (eo.custom.plugin.sample)
• matchType - regexp to identify insert points (/object-details-tab.*/)

All active plugins are included as EoPlugin in custom-plugins/custom-plugins.module.ts. If you want to disable any plugin, simply remove the plugin component from entryComponents array.

The application can render plugins as TabPanels inside of TabContainers.

# to generate TabPanel for each object-details component (/object-details-tab.*/)
eo g plugin plugin-name

# to generate TabPanel for each inbox-details component(regexp: /inbox-details-tab.*/)
eo g plugin plugin-name eo-inbox-details.*

# to generate TabPanel for object-details component only in favorite state (regexp: /object-details-tab.favorite/)
eo g plugin plugin-name object-details-tab.favorite

States

New states can be created as part of existing application.

Each state component requires properties (see EoLinkPlugin):

• id - string representing state ID | labelKey for translation (eo.custom.state.sample)
• path - string representing url (custom/sample)
• matchType - regexp to identify specific insert point/points for link (/sidebar-navigation/)

and optional property:

• queryParams - object representing query ({debug: true}); to generate link 'custom/sample?debug=true'

All active states are included as Route & EoLink in custom-states/custom-states.module.ts. If you want to disable any state, simply remove the state component from routes and links array.

# to generate state with specific path
# link in sidebar navigation is automaticaly included
eo g state state-name state-path

Actions

New actions can extend functionality of existing actions menu.

Each action component requires properties based on interface :

• SimpleAction
• LinkAction
• ListAction
• ComponentAction
• ExternalComponentAction

and based on action target:

• DmsObjectTarget
• InboxItemTarget
• ProcessItemTarget
• PreparedItemTarget
• WorkItemTarget
• StoredQueryTarget

All active actions are included as BaseAction in custom-actions/custom-actions.module.ts. If you want to disable any action, simply remove the action component from entryComponents array.

# to generate action
eo g action action-name

Links

New link can extend functionality of existing sidebar container.

There are multiple insert points in the application bar:

• sidebar-navigation (navigation menu on the left)
• sidebar-profile (profile menu on the right)

Each link object requires properties (see EoLinkPlugin):

• id - string representing link ID | labelKey for translation (eo.custom.state.sample)
• path - string representing url (custom/sample)
• matchType - regexp to identify specific insert point/points for link (/sidebar-navigation/)

and optional property:

• queryParams - object representing query ({debug: true}); to generate link 'custom/sample?debug=true'

All active links/states are included as EoLinkPlugin in custom-states/custom-states.module.ts. If you want to disable any link, simply remove the reference from links array.

# to generate custom link (/sidebar-navigation/)
eo g link link-path link-id

# to generate custom link in profile menu (/sidebar-profile/)
eo g link link-path link-id sidebar-profile

Labels

New labels can extend existing language files inside i18n folder.

Basic version contains multiple language files (assets/i18n/*.json):

• en.json (default)
• de.json

Application provides support for international languages. (en, de, ar, es, pt, fr, zh, lv, ru, it, uk, ja, ko, hi, bn)

# to generate label for specific key/id (eo.custom.state.sample)
eo g label label-key --language translation

# examples
eo g label eo.custom.state.saturday --en Saturday --de Samstag
eo g label eo.custom.state.sunday --en Sunday --de Sonntag --es Domingo
eo g label eo.custom.state.sunday.time --en "Sunday {{time}}" --de "Sonntag {{time}}"

NEW LANGUAGE: You can add new language via main configuration (/assets/config/main.json) and creating specific file inside i18n folder.

Before you add labels/keys to a language file (assets/i18n/*.json) make sure the language file already exists.

Generating Components, Directives, Pipes and Services

In case that command does not exist inside Custom client CLI (eo), Angular CLI (ng) is used as fallback. You can use the eo generate (or just eo g) or ng generate (or just ng g) command to generate Angular components:

ng generate component my-new-component
ng g component my-new-component # using the alias

# components support relative path generation
# if in the directory src/app/feature/ and you run
ng g component new-cmp
# your component will be generated in src/app/feature/new-cmp
# but if you were to run
ng g component ../newer-cmp
# your component will be generated in src/app/newer-cmp
# if in the directory src/app you can also run
ng g component feature/new-cmp
# and your component will be generated in src/app/feature/new-cmp

You can find all possible blueprints in the table below:

Scaffold | Usage --- | --- Component | ng g component my-new-component Directive | ng g directive my-new-directive Pipe | ng g pipe my-new-pipe Service | ng g service my-new-service Class | ng g class my-new-class Guard | ng g guard my-new-guard Interface | ng g interface my-new-interface Enum | ng g enum my-new-enum Module | ng g module my-module

angular-cli will add reference to components, directives and pipes automatically in the app.module.ts. If you need to add this references to another custom module, follow this steps:

1. ng g module new-module to create a new module
2. call ng g component new-module/new-component

This should add the new component, directive or pipe reference to the new-module you've created.

Documentation

The documentation for the developers.

The documentation for the Angular CLI is located in this repo's wiki.

License

MIT