Frontend Development
Since the new oms-central-frontend some changes to the frontend development workflow have been made. I will try on this page to gather all relevant information about how frontend development works now, highlighting the new changes.
Purpose
The central does several things
- Checking which microservices currently are registered and which dependencies they have based on their getModules.json
- npm install all dependencies and concatenate them into optimized vendor.js and vendor.css files.
- Download and concatenate all css and js files from the microservices into optimized main.js and main.css files.
- Create the html basis of the page, which includes the menu and some other things which are common to the whole frontend.
- Serve everything on /
All of this is just done once on application startup, so when something in the system changes this will not be reflected in the frontend immediately
CLI Usage
You will want to interact with the central frontend when developing. In general, a rebuild of the frontend can be performed by running bash oms.sh run oms-central-frontend gulp. This will rebuild the frontend to reflect the current status of the services as returned by the serviceregistry.
- If you just did a couple of small changes in a file that was already included, a
gulprebuild in the oms-central-frontend container might be what you want to do (bash oms.sh run oms-central-frontend gulp) - If you intend to do several changes but not add or remove files, you will not want to run a frontend rebuild every time you change something. For this, the central frontend offers to build the frontend in dev-mode, which turns off most of the code optimisations including concatenating the files into one, and will include your sources directly. To turn on dev mode, change the boolean devMode in
oms-central-frontend/lib/config.jsonto true and rungulpin the oms-central-frontend container. - If you added new frontend files or dependencies, you will atm have to restart oms-serviceregistry and rerun the gulp task. A
bash oms.sh down && bash oms.sh up -dwill do the same thing, but if you don't want to recreate the whole ecosystem you might want to write a script for this.
New getModules.json Format
Also, the getModules.json plays a more important role. This is the file that holds all the information about the frontend files, dependencies and menu items of the microservice. It will be fetched by the serviceregistry on the location that the `registry.modules` label indicates and then cached by the serviceregistry. If you do changes to that file, you will have to restart the serviceregistry and oms-central-frontend at the moment, in the future I hope to implement a change watcher in the serviceregistry that triggers a frontend rebuild on change to make this step obsolete. The new getModules.json format is compatible to the old one, but holds some more possibilities
| Parameter | Required | Description |
|---|---|---|
| name | yes | Module friendly name, will be displayed above the menu items of that service (no limitations, can be changed in time example: "OMS Events module") |
| code | yes | Module internal name - This will be the entry for the service in the baseUrlRepository (see below) (no spaces, all lowercase |
| pages | yes | JSON array containing frontend pages data Each entity inside the array should contain the following attributes: |
| pages[].name | yes | Frontend friendly name (example: "List events"), will be the name of the menu item |
| pages[].code | yes | Frontend internal name (example: "applications") - This one should be the same with the AngularJS module name defined in the module |
| pages[].module_link | no | relative (to your service) path to the module controller JS file, instead you can also use the js array below |
| menu_position | no | An integer indicating the position in the left menu, if not specified defaults to the end of the list. |
| css | no | JSON array containing relative (to your service) paths to css files that you want to include |
| js | no | JSON array containing relative (to your service) paths to js files that you want to include |
| modules | no | JSON array containing angular module names that should be added in addition to the ones from the pages array |
| deps | no | JSON array with dependencies of your service. Each dependency must be installable via npm and will end up in the vendor.js and vendor.css files. You can also add an angular module to be loaded for the dependency. In case another service already registered a dependency with the same npm name, your dependency will be skipped. |
| deps[].npm | yes | Name of the npm module that can be passed to npm install <name>. It is recommended to add a major version number to the npm name, so future breaking updates don't get installed while security updates and new features will be installed automatically (example "bootstrap@3") |
| deps[].css | no | JSON array or string containing the css files this dependency brings |
| deps[].js | no | JSON array or string containing the js files this dependency brings (example "node_modules/bootstrap/dist/js/bootstrap.js") |
| deps[].module | no | Name of the angular module this dependency brings. Make sure this is correct as otherwise it will break the frontend. |
Future Ideas
I have some ideas to improve the central frontend in the future.
- At first clean up the dependencies and move them into the frontend that they belong to.
- Include automated frontend testing into the central frontend, generating test-cases and optionally including more test-cases into a local test suite.
- Also it would be nice to automatically blacklist modules with failing test, so it is impossible to accidentally include a microservice which breaks the rest of the frontend.