@rstor/rstor-ui-library v0.0.239

Atrio UI Library

This project was generated with Angular CLI version 1.2.0. This is an application containing the Atrio UI library which can be exported using the ng-packagr. New components (and modules) can be added by using the Angular CLI and following a few simple steps. The selector prefix for the components in this library is "rui-".

HOW TO CREATE A NEW LIBRARY PACKAGE VERSION

A new package needs to be created each time you have added or modified a component.

1. Install Run nvm use to set the expected Node version. Run npm install to install all the dependencies if you haven't already.

2. (OPTIONAL) Create and test the package locally Run npm run create-dev-package from the root project folder to compile and package the TypeScript library to Angular Package Format. This will create a dist folder with a tarball called atrio-ui-library-x.x.x.tgz with the x.x.x part being the version number from the package.json file. You can use this file to test the library locally from your UI application by temporary adding "@atrio/atrio-ui-library": "file:<local_path>/atrio-ui-library/dist/atrio-ui-library-x.x.x.tgz" to the package.json.

3. Update private npm package Create a PR for master. Once it is approved (by review, CI tests and linting) and merged a new npm package will automatically be uploaded to our private npm. Please note! Do not update the package version number manually, the CI will do that on merge with master.

4. Update the atrio-ui-library reference in your UI application Depending on how you specified your version (^, ~, > etc) and if your update was major, minor or patch you might need to update the "@atrio/atrio-ui-library" dependency in your UI application's package.json to get this latest version.

HOW TO USE THE LIBRARY IN ANOTHER APP

This requires that the package has been created according to the steps above. The target app can have Angular Material installed, but it is not mandatory, since the components in the UI library come with their own material dependiencies. The UI library's Material theme however needs to be imported, see point 4.

1. Install the dependency Go to your target application run npm install --save @atrio/atrio-ui-library. This will install the latest atrio-ui-library from our private npm. Make sure the file .npmrc is present in the root of your application and contains a readonly access token to our private npm.

2. Link the assets Some assets of the library (fonts and svg icons) need to be available for the entire application, not just to the components of of the library itself. Add the following to the apps.assets array in the .angular-cli.json:

   { 
   	"glob": "**/*", 
   	"input": "../node_modules/@atrio/atrio-ui-library/src/assets", 
   	"output": "./assets/rui-assets/" 
   }

   Notice: If your app is based in Angular 6 you have to add the previous lines into angular.json file instead.

   This will make sure the UI library assets are made available as assets under the subfolder rui-assets so that they don't conflict with any other assets.

3. Configure Angular Material styles

3.1. Make sure you application is configured to use Sass (.scss) so that it works with the custom Material theming.

3.2. From you applications main style file (e.g. styles.scss) add the following line at the top
`@import '../node_modules/@atrio/atrio-ui-library/src/material-themes.scss';`. If you need to change anything in the main theme, you need to do that before importing the material-themes.scss. Here is a simple example of how it could look:    

```
@import '~@atrio/atrio-ui-library/src/_variables.scss';
$rui-color-main-nav-logo-background: $rui-color-green;
@import '~@atrio/atrio-ui-library/src/_material-themes.scss';
```    

3.3. Add the class `material-light-theme` to the HTML body in `index.html`, or use a wrapper element in a component if you want to be able to use multiple themes.

3.4. Add the class `mat-typography` to the HTML body in `index.html`.

4. Configure the icons The UI library icons are added to the Angular Material's MatIconRegistry under the namespace rui so that they don't conflict with any default Angular or application specific icons.

   4.1. Import the UI library's IconsModule to your app.module.ts using import { IconsModule } from '@atrio/atrio-ui-library';Don't forget to add the module to the imports array.

   4.2 Inject the IconsService in your apps root component (app.component.ts) by using import { IconsService } from '@atrio/atrio-ui-library'; and set the constructor like constructor(IconsService: IconsService){}

   4.3 Make sure your app imports the HttpClientModule in the root module of your application (often called app.module.ts).

   	_Please Note!_ : 

   This makes the icons available to all components of your application, including the components of the UI library which might need them. But in order to actually use the icons in your own component be sure the module of your component imports the MatIconModule. e.g. import { MatIconModule } from '@angular/material';.

5. Import and use as normal Import the modules (components) that you want to use as you would with any Angular package. E.g. import { FancyButtonModule } from '@atrio/atrio-ui-library';

6. Modified TypeScript configuration (only for Angular 6)

   Add the following into compilerOptions of the tsconfig.json file:

   "paths": {
     "@angular/*": ["node_modules/@angular/*"] 
   }

7. RxJS Compatibility (only for Angular 6)

Since this library was implemented under Angular 5 it's necessary to install rxjs-compat package to get backwards compatibility with RxJS previous versions.

npm install --save rxjs-compat

HOW TO USE THE LIBRARY IN ANOTHER APP - LINK MODE

This section will explain the steps to use the library without installation. To link it, follow this steps:

• Create package and link it using this command npm run create-package-and-link. (You have to run this command every time you want to have changes linked to you main app)
• In your Angular App with atrio ui lib dependence*:
  • Go to your app node_modules folder and run npm link @atrio/atrio-ui-library
  • Run the app adding the flag --preserve-symlinks.
  • To restore library, go to node_modules folder an run npm unlink @atrio/atrio-ui-library and run npm install @atrio/atrio-ui-library.

*If you are using this library in Marinara project, you have some scripts to do the link and unlink process, please read marinara readme file.

HOW TO ADD COMPONENTS

This section assumes that the reader is somewhat familiar with Angular 4.X and the Angular CLI. Lets examplify with a new component called fancy-button.

1. Install If not already done, run npm install in the atrio-ui-library folder.

2. Start the development server Run ng serve. Navigate to http://localhost:4300/.

3. Create a component with its own module. We use one module per component. Each component/module should have its own folder which should be a subfolder of the app/modules folder. E.g. generate the module in a folder with the same name using ng generate module modules/fancy-button then generate the component in the same folder using ng generate component modules/fancy-button. If you need to use colors, use the avilable CSS properties for dynamic colors that should follow current theme (e.g. var(--rui-color-primary) and SASS variables for colors that never change (e.g. $rui-color-blue).

4. Create the wiring 4.1 Export the FancyButtonComponent in the fancy-button.module.ts. 4.2 Import the appropriate demo module, e.g. demo-components.module.ts. 4.3 Then add your component to the demo component, e.g. demo-components.component.html so that you can try it out and so that others can see it working. Add a small descrition on how to use it. In the future we probabley want to make this demo a bit more sophisticated.

5. Export your module from the public_api.ts E.g. add the line export * from './src/app/modules/fancy-button/fancy-button.module'; to the file.

6. Add any external dependencies If you are using new any external libraries they should be added to the file ng-package.json under lib:externals.

7. Create the library package See instructions above. (The lastest-package distribution folder of the UI library is part of the git repo for easy setup.)

HOW CREATE A CUSTOM THEME (BRANDING)

Please note that this information is for POC and client specific theming. All Atrio apps will by default use the same blue based theme, only the color of the logo background in the main navigion will be different.

The atrio-ui-library can be easily themed for clients and demos by simply changing some of the SCSS variables that the look and feel is based on. For simple theme changes you can add any of the "theme variables" below in your consuming application's global styles.scss before it imports the _material-themes.scss. You can also adjust the theme by changing these variables in the library itself.

The theme variables are defined in src/app/scss/_variables.scss. Common steps for theming include:

1. If needed replace the logo src/assets/rui-assets/images/logo.png with the logo of the client.
2. Set $rui-custom-theme-display to initial. This will enable the "Powered by Atrio" image in the footer.
3. Set $rui-show-company-name to none if you don't want to show the company name in the footer.
4. Adjust the height of the $rui-toolbar-height if needed.
5. Adjust the following variables to match your color needs
   • $rui-color-primary -> Changes things like buttons, header, progress bar and the primary-attribute color etc.
   • $rui-color-accent -> Changes checkboxes, radiobuttons, sliders and possily other components that use the accent color somehow.
   • $rui-color-background -> Changes the background color of the app.
   • $rui-color-panel-background -> Changes the background color of panels and the footer.
   • $rui-color-foreground -> Changes the default color of headers, paragraphs, input texts, input labels etc.
   • $rui-color-main-nav-background -> Background for the header and the sub-header components.
   • $rui-color-links -> Color for links ( tags).
   • $rui-color-links-focus -> Color for focused links.
   • $rui-color-icon-primary -> multi colored icon color.
   • $rui-color-icon-secondary -> multi colored icon color.
   • $rui-color-icon-base -> multi colored icon color.

HOW TO ADD ICONS

The atrio-ui-library contains two types of icons, multi and singel colored. Multi colored icons are the more complex ones with 3 colors, representing specific atrio concepts or file types. Single colored icons are simple icons, like close and back icons that come in only one color. The icons should be in the SVG format.

1. Make sure the file is correctly named. The name of the file should also be the name of the icon, e.g. the bucket icon file is named bucket.svg. Separate multiple words with dash.
2. Add the svg file to assets/rui-assets/svg-icons
3. Add the icon name to the icons or the fileTypesIcons arrays in the icons.service.ts.
4. Open the svg file and make sure the title tag is the name of the icon.
5. Make sure there are no ID attributes in the SVG elements, delete if there are any.
6. For single colored icons, make sure the fill attribute is set to currentColor. For multi colored you probably need to override (but not replace) both the fill and stroke attributes with corresponding CSS classes. Our default icons currently use the colors #4390BC, #DCEFFE and FFFFFF (aka FFF or simply white) and they correspond to our variables $rui-color-icon-primary, $rui-color-icon-secondary and $rui-color-icon-base. Since there are 3 colors and 2 possible ways of using them in the SVG file we have 6 icon color classes to choose from:
   • .rui-color-icon-primary-fill (#4390BC)
   • .rui-color-icon-primary-stroke (#4390BC)
   • .rui-color-icon-secondary-fill (#DCEFFE)
   • .rui-color-icon-secondary-stroke (#DCEFFE)
   • .rui-color-icon-base-fill (#FFFFFF)
   • .rui-color-icon-base-stroke (#FFFFFF)

As an example the following fictive paths

<path d="..." fill="#4390BC" fill-rule="nonzero"></path>
<path d="..." stroke="#DCEFFE" fill-rule="nonzero"></path>
<path d="..." stroke="#FFFFFF" fill="white" fill-rule="nonzero"></path>

Should be changed into

<path d="..." fill="#4390BC" class="rui-color-icon-primary-fill" fill-rule="nonzero"></path>
<path d="..." stroke="#DCEFFE" class="rui-color-icon-secondary-stroke" fill-rule="nonzero"></path>
<path d="..." stroke="#FFFFFF" class="rui-color-icon-base-fill rui-color-icon-base-stroke" fill-rule="nonzero"></path>

We keep the original fill and stroke so that the image still can be correctly viewed again in an SVG editor.

More info on theming, colors and variables

For "constants" like our standard blue color (e.g. '$rui-color-blue') you should use the SASS variables and for colors that might change depending on theming you should use the CSS properties (e.g. 'var(--rui-color-primary)')

If your app uses the atrio-ui-library it will get its colors in two ways. First, Material components like buttons, get their colors from the theme definition in _material-themes.scss. That theme definition in turn uses the atrio specific _variables.scss. Second, library specific elements use the static colors in _variables.scss and the dynamic CSS properties in _default-theme.scss.

Since all SASS code in the atrio-ui-library is compiled when we create the package all SASS variables are lost for the atrio components that get their inline HTML/STYLE replaced with the actual HEX colors or CSS properties (variables). Hence, in order to control the color and other theme attributes of our in-house components from outside the library we need to use CSS properties in our components. These CSS properties are declared in the root context in _default-theme.scss and if they are overwritten by the consuming application, the components will reflect that change. But since the Angular Material SASS theme creation functions require SASS variables we need to work with both CSS properties and SASS variables.

Therefor the consuming application will get a copy of these SASS files (added to the package via an npm script) so that it can reuse the SASS variables and easily create a Material theme itself. The theme class is added to the body of the consuming application which decides how the material components will look. By simply declaring new values for the SASS variables in your consuming app you can in one go change both the Material theme and the CSS properties that controls the atrio-ui-library inhouse components. This is how it works in your consuming apps main styles.css.

// Import the variables to get access to statics colors etc.
// All themable variables are declared as "default" so they will only get its 
// value from this file unless they aren't delared anywhere else, before OR after this import.
@import '~@atrio/atrio-ui-library/src/_variables.scss';

// Here you can declare or override any library specific SASS variables.
$rui-color-main-nav-logo-background: $rui-color-green;

// By importing this file two important things happen. First, it will in turn import a default theme.css 
// that will set CSS properties based on the corresponding current values of the SASS variables. 
// That means that the CSS properties and SASS variables are now in sync even if SASS variables were overwritten. 
// Second, it will generate the Angular Material theme based on the current SASS variables.
@import '~@atrio/atrio-ui-library/src/_material-themes.scss';

Code scaffolding

Run ng generate component component-name to generate a new component. You can also use ng generate directive|pipe|service|class|module.

Running unit tests

Run ng test to execute the unit tests via Karma.