Vien Portal Template

overview

back to development notes

The OPENDMS portal is based in the vien angular admin template library from Colored Strategies. We have heavily customized the template to suite our needs and the notes on how we have used this template and any changes we’ve made are found here.

We decided to strip the template back to it’s bear bones and build on the structure of the template to include our specific functionality and this document is broken into a number of sections including;

  • template structure – discussing the file structure, naming conventions and module/component methodology employed by the authors of the template;
  • customization – discussing the changes, modifications and additions we’ve made to the core template to adapt it to our requirements; and,
  • specific functionality – we we highlight the functionality we’ve added to the template to facilitate our requirements.

The section on specific functionality will be an overview for the most part as other pages in the development notes will address the sub-systems supported by the portal and how they work and what they do.

This page is specifically a go-to section on the angular template and its functionality.

template structure

back to development notes | overview

This section discusses the vien angular admin template structure and discusses the base “out of the box” offering as well as the changes we’ve made to the template to meet our requirements.

The template follows acceptable angular standards with logical use of module and component grouping, module routing and lazy loading. It comes embedded with a language management system that we’ve left active although we are only working with English in the first instance.

base structure

back to development notes | overview | top

The vien angular admin template adopts a reasonably acceptable angular project structure and the following diagram shows the folder structure under the project root. In this case the project root is opendms and the portal folder is the base of the angular SPA is structured as follows;

opendms/portal
├── .editorconfig
├── .gitignore
├── angular.json
├── browserslist
├── karma.conf.js
├── package.json
├── package-lock.json
├── README.md
├── tsconfig.app.json
├── tsconfig.json
├── tsconfig.spec.json
├── tslint.json
├── yarn.lock
├── e2e
│   ├── src
│   ├── protractor.conf.js
│   └── tsconfig.json
└── src
    ├── assets
    ├── environments
    ├── lang
    ├── favicon.ico
    ├── index.html
    ├── main.ts
    ├── polyfills.ts
    ├── test.ts
    ├── typings.d.ts
    └── app
        ├── components
        ├── constants
        ├── containers
        ├── data
        ├── shared
        ├── views
        ├── app.component.html
        ├── app.component.ts
        ├── app.module.ts
        └── app.routing.ts

The src folder is the base of the development containing the various project level resources and configurations (assets, enviroments, language) and the app folder is the project source.

These folders are at the application root and, where necessary 

Language Management

back to development notes | overview | top

The vien angular admin template’s translation and language requirements are provided via @ngx-translate. Language entry files are located at src/lang folder and the app.component.ts file uses the init function of shared/lang.service.ts file and provides it language options and default language.

Default language of the project is also set from the shared/lang.service.ts file with the defaultLanguage variable. This variable should be the code value of one of the items from the supportedLanguages array.

Module Import
import { TranslateModule } from '@ngx-translate/core';
@NgModule({
  ...
  imports: [
    TranslateModule,
  ],
  ...
})
Usage in Html
< h1 >{{ 'user.email' | translate }}< /h1 >
Usage in Ts
import { TranslateService } from '@ngx-translate/core';
constructor(private translate: TranslateService) {
  console.log(this.translate.instant('alert.success-alert'));
}

Pruning of the language files

The template comes bundled with two language files;

  • en-US.json – providing English translations for the terms and phrases; and,
  • es-ES.json – providing Spanish translations.

These files are populated with the complete vocabulary of the vien angular admin template; many of which we are not going to use. As mentioned we are going to strip the template back to a walking skeleton and, during this process will group all the terms we need as a part of the translation service. Once the walking skeleton is complete we will remove all groups and terms we don’t need and this reduced set will be the core or our portals translation service.

Language File Structure

The language files are json data structures and use collections of name value pairs to resolve the translated labels. For example, a pages collection might have three pages (home, system and user). The language file for this simple translation would be;

{
  "pages": {
    "home": "Home Page",
    "system": "System Page",
    "user": "User Page"
  }
}

When the label for the pages.home element of the pages connection is required angular uses the various methods shown above to add the label. For example a home page title in a template would be as follows;

< h1 >{{ 'pages.home' | translate }}< /h1 >

The translator will take care of this at runtime and place “Home Page” in the template. Once we have the walking skeleton working we’ll start keeping a single en-US.json file and only ever use translated labels. That we, when we need to handle another language we can use the en-US.json as the dictionary.

Identifying our labels

In each collection in en-US.json we will add a CURRENT VALUES IN TEMPLATE element at the end of each collection and add the terms we are using below this line.

{
  "pages": {
    "videos": "Videos",
    "vien": "Vien",
    "visible": "Visible",
    "wizard": "Wizard",
    "--": "----- CURRENT VALUES IN TEMPLATE",
    "home": "Home",
    "terms": "Terms & Conditions",
    "privacy": "Privacy"
  }
}

When the walking skeleton is complete we will visit the en-US.json file and remove any collections not used and, if a collection is used, all the elements above and including the CURRENT VALUES IN TEMPLATE line.

This will then become our starting dictionary. The JSON ABC  web site will be used to sort the file into alphabetical order.

How does the Template Handle an Unknown Element?

If the name/value pair pages.invoice does not exist in the en-US.json pages collection, the language sub-system will simply display pages.invoice in the label and the missing element can be added to the collection.

Customization

back to development notes | overview

This section highlights the customizations we have made to the vien angular admin template. It assumes that the walking skeleton has been used as a starting point and we identify the various changes made to get the template to the walking skeleton starting point.

Language Service

back to development notes | overview | top

The walking skeleton has been throttled back to a single language (en-US) and the en-US.json file has been cleared of all extraneous groups and name-value pairs accordingly.

The shared\lang.service.ts file has been refactored to include just one language file.

import en from '../../lang/en-US.json';

We added a public property to the service to provide a constant reference to the language type.

  LANG_EN_US = 'en-US';

And replaced the hard-coded references to ‘en-US’ to LANG_EN_US in the service accordingly.

  supportedLanguages: Language[] = [
    { code: this.LANG_EN_US, direction: 'ltr', label: 'English', shorthand: 'en' }
  ];
The reason for this modification was to support any pages that had a static block of copy (e.g. Privacy Policy, Terms & Conditions etc.) that went beyond the simple translation services and might rely on a structural directive (e.g *ngIf) to resolve the correct language to display the content in.