eo-client-cli
Custom Client CLI angular-cli project
Extension for
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
- Installing external library
- 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-client-cli (eo)
- @angular/cli (ng)
- webpack (webpack)
eo webpack - install latest version of webpack and webpack-cli
npm install -g eo-client-cli@latesteo clieo webpack
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-clinpm uninstall -g eo-client-clinpm cache verify#install latest version npm install -g eo-client-cli@latesteo cli
Local project package to latest version:
# to install latest version (eo-client@latest) eo update
# to install specific version (eo-client@1.0.0) eo update --@1.0.0
! BEFORE UPDATE - CLOSE ALL OPEN FOLDER / FILES INSIDE PREBUILD FOLDER + CLOSE RUNNIG PROJECT / LOCALHOST!
In case you discover errors after update, try to cleanup the project and run update again:
# remove node_modules and prebuild folder eo cleanupeo update
Usage
eo help
Generating and starting Custom client project
Basic concept of Custom client project is to combine multiple modules:
eo-custom-client
- from new Custom client projecteo-client
- from eo-client packageeo-framework
- from eo-client packageeo-framework-core
- from eo-client package
and build single application into prebuild
folder.
! DO NOT MODIFY FILES INSIDE PREBUILD FOLDER !
All changes in eo-custom-client
module are synced via webpack.
All services are running via proxy, so you need to start proxy server.
eo new PROJECT-NAMEcd PROJECT-NAME# to run prebuild application npm start# to sync eo-custom-client module with prebuild webpack --watch# to run initial commit git add -A git commit -m "initial commit"
In case you want to clone existing custom client project from git:
cd PROJECT-NAME# to create prebuild folder and files eo update# to run prebuild application npm start# to sync eo-custom-client module with prebuild webpack --watch
CODE_STYLE CONFIGURATION You should import tsscheme.xml .\node_modules\eo-client\misc\tsscheme.xml
via editor settings (Editor > Code Style > TypeScript
;press setting icon ; Import scheme > Intellij IDEA code style XML
)
Navigate to http://localhost:4222/
. 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 4201
Building and testing Custom client project
To run build process use these commands:
cd prebuildnpm run build-web
After successful build, output folder (./prebuild/output/
) is generated containing zip file.
To run local test use angular cli.
ng test
BUILD ERROR In case of unexpected error, try to run eo init
and build again.
Installing external library
AVOID BUILD ERRORS: Instead of npm install
, you have to use the eo install
| eo uninstall
command to provide new library.
eo install library-name@version#example: install maps eo install @agm/core@latest
eo uninstall library-name@version#example: uninstall maps eo uninstall @agm/core
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-componenteo 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 Samstageo g label eo.custom.state.sunday --en Sunday --de Sonntag --es Domingoeo 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-componentng 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:
ng g module new-module
to create a new module- 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