npm package: @getbeyond/ng-beyond-js
Description: Library built with Angular 9 for the Beyond Platform
Author: Beyond Devs
Latest version: 3.0.16
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

## Usage and builds
This package contains modules intended to be used with Angular applications.
Builds are done through a build script: `build.sh` and the results are available in `pkg/` folder to avoid conflicts with the `dist/` folder, which is the default for `ng build`.
In both cases you will need to install peer dependencies. This can be accomplished using [npm-install-peers](https://www.npmjs.com/package/npm-install-peers)
When publishing to NPM, always publish the `pkg/` folder, not the root folder.

### Development and build workflow
 - Create a branch with a fix or a new feature (you will need to install dependencies as well as peer dependencies);
 - Get it approved;
 - Bump the version in package.json;
 - Add an entry in [CHANGELOG.md](./CHANGELOG.md), possibly update this README.md too;
 - Run build.sh and make sure it builds without errors;
 - Squash merge - the commit message should have version number in the first line;
 - Add a tag using `git tag -a v#.#.#` with a message describing changes made;
 - Push the tag (`git push --tags`);
 - Run `npm publish` in the `pkg/` directory or ask someone with access to do this. It is prefered to publish from a Linux environment to avoid line break or file permission issues.

### Previewing components
Most of the components in this package can be previewed using `ng serve` after installing all peer dependencies. In order to support previewing the components dependant on Beyond API the following is needed:
- A token must be entered into the input field of the demo application
- The URL used to access the demo app must be changed to simulate accessing an account: `http://localhost:4200/accounts/####/` where `####` is the account number.

## API services
This package contains services enabling interaction with the API. They are Available in the `NgBeyondModule` module.

### [Link Utilities](./src/app/modules/ng-beyond/services/link-utils/link-utils.service.ts) Service
Provides a method for opening:
- external links
- downloadable resources (PDFs etc)
- tel and mail links (tel:, mailto:)
This service's methods should be used in place of plain links, as mobile apps need to open the above links in the system browser.
The service also includes methods for accessing the [Cordova](https://cordova.apache.org/) interface used within mobile apps.
If you are looking for a method to check being in the mobile app context, use 
[BeyondSession.getMobileAppInfo()](./src/app/modules/ng-beyond/services/session/session.service.ts).

### Route History Service
Handles route history to support back() navigation handling dependant on the navigation history context.
- `currentNavigation: NavigationEnd` - current location;
- `lastNavigation: NavigationEnd` - previous location;
- `subscribe():void` - Must be called to start tracking route history;
- `navigateBack(fallbackPath: any[], validBackUrl: RegExp | string = null):void` - Navigate back if navigation history exists and previous url matches optional `validBackUrl`, otherwise navigate to `fallbackPath`. 

---
## Beyond Angular Components
This package contains Beyond Angular components based on Material. They are available in the `BeyondComponentsModule`
Following components are included:
### Card
A wrapper of Materials ExpansionPanel, rectangular space for content with a header section. You can provide a `<mat-panel-title>` in the components content to create a custom title - this can be used in conjunction with any type, but `title` and `buttons` should remain empty in such case. Available with following properties:
- `[buttons] Array<IButton>` - An array of buttons which will be displayed in the cards header, should be empty when providing `<mat-panel-title>`;
- `[collapseWhenLoading] boolean = true` - Should the card collapse when showing the loading indicator. Defaults to true;
- ~~`[canCollapse] boolean`~~ Deprecated since 1.2.0 in favour of `[type]`;
- `[isOpen] boolean`
- `[link] string` - Convert's the card title to a link, depends on `[title]`;
- `[loading] boolean` - If true displays a loading indicator and covers content with semi-transparent layer, card is collapsed when true unless overridden by `[collapseWhenLoading]`;
- `[title] string` - Cards title displayed in the header, should be empty when providing `<mat-panel-title>`;
- `[type] string = 'simple'` A `CardType` string enum defining cards type as `simple`, `collapsible`, `dismissible` or `customHeader`;
  - Simple - Keep a header when there are buttons or title, otherwise no header;
  - Collapsible - Always show a header with a button to collapse the card;
  - Dismissible - Always show a header with a button to dismiss the card;
  - Custom Header - Always show a header and ignore `title` or `buttons` values, expected to be used with a `<mat-panel-title>` in the content. This type is mostly needed when you want a custom title and no collapsible or dismissible behaviour.
- `(closed)` - Triggered when card collapses;
- `(opened)` - Triggered when card is opened.
### Date range  
A component used for selecting date ranges. Contains a select dropdown of preset values and 1 or 
2 datepicker widgets. It can work with different date formats depending on the `DateAdapter` 
provided, more information [here](https://material.angular.io/components/datepicker/overview#choosing-a-date-implementation-and-date-format-settings). If no value is passed as from and to it's initial value will default to 'Yesterday'. 
Implements [ControlValueAccessor](https://angular.io/api/forms/ControlValueAccessor).
When using this component consider to listen for the `(ready)` event and hide it until the component is
ready. This will prevent layout displacements when loading. 
- `[disabled] boolean` - Set disabled property on component inputs, defaults to `false`. When using [FormControl](https://angular.io/api/forms/FormControl), use the [AbstractControl.disabled](https://angular.io/api/forms/AbstractControl#disabled) property instead.
- `[from] any` - From date, type depends on the `DateAdapter` used;
- `[to] any` - To date, type depends on `DateAdapter` used;
- `[formControl] FormControl` - {from:T, to:T}  // T depends on the `DateAdapter` you use;
- `[weekStartDay] int` - a number in the range of 0-6 to define the week start day. If not provided the component will query account info to check this value.  
- `(change) <{from:any, to:any}>` - Triggered when a date value changes;
- `(ready)` - Triggered when the component becomes ready. This happens instantly if `weekStartDay` is provided, or once the account info value for this property gets loaded.

![Date Range](doc_images/date-range.png)

![Date Range - Single Date](doc_images/date-range-single-date.png)

### Ellipsis Tooltip (directive)
A directive to display MatTooltip with full text content only when text content overflows. Using it does not affect the styling of the element, you need to apply styling yourself.

This attribute does not accept an input value - it will display the [textContent](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent) of the element that it is applied to.

![Ellipsis Tooltip](doc_images/ellipsis-tooltip.png)

### Info Grid
A component to display a set of values with labels organised as 2 columns based on an array of [BeyondInfoGridItem](./src/app/modules/beyond-info-grid/info-grid/info-grid.component.ts#L22) objects passed.
- `[infoItems] BeyondInfoGridItem[]` - the labels and values to display;
- `[skipEmpty] boolean = true` - should empty values be skipped.
- `[isHtml] boolean = false` - should values be parsed as HTML markup. Labels will remain plain text.

![InfoGrid](doc_images/info-grid.png)
### Location Alert
An overlay with an alert blocking activity on a given page if no location is selected.
- `[pageTitle] string` - Set the page title in the alert message.
- `[positionMessage] string` - Overrides the message with information on how to change the location. Typically _'Please select a location from the menu above.'_
### Location Autocomplete
A multiselect location picker with chips and autocomplete search, capable of handling `org_groups`.
Implements [ControlValueAccessor](https://angular.io/api/forms/ControlValueAccessor). `<mat-error>` 
tags are transcluded in this component and may be used to contain validation errors. Values assigned
are evaluated by id (group id or location id), the expected format depends on the 
`[useModelWithOrgGroups]` value and is either an array, or a `LocationsWithOrgGroups` object.
When using this component consider to listen for the `(ready)` event and hide it until the component is
ready. This will prevent layout displacements when loading.
- `[allowNoLocation] boolean` - Allows no location to be selected, if false (default) no locations means all locations are selected. This changes the value emitted. With value set to false removing the last chip does not open the locations list;
- `[disabled] boolean` - Set disabled property on component inputs, defaults to `false`. When using [FormControl](https://angular.io/api/forms/FormControl), use the [AbstractControl.disabled](https://angular.io/api/forms/AbstractControl#disabled) property instead;
- `[errorStateMatcher] `[`ErrorStateMatcher`](https://github.com/angular/material2/blob/master/src/lib/core/error/error-options.ts) - Error state matcher passed to the chip list.
- `[required] boolean` - When true an asterisk and a visual error indicator when no selection is made will be displayed;
- `[selectedLocations] Array<{id:number}>|LocationsWithOrgGroups` - Locations initially selected. Location and org group values are compared by id. Provide `LocationsWithOrgGroups` when `[useModelWithOrgGroups]` is true.  When using [FormControl](https://angular.io/api/forms/FormControl), pass the value with the form control instead. Providing no value will default to 'All locations', providing an empty array will init with empty selection if `allowNoLocation`;
- `[formControl] FormControl` - Locations initially selected;
- `[useModelWithOrgGroups] boolean = false` - Should the value emitted be a list of locations (including children of selected org groups), or a LocationsWithOrgGroups holding locations and org_groups separately. 
- `(change) <BeyondLocation[]|LocationsWithOrgGroups>` - Triggered when the location selection changes. If `[useModelWithOrgGroups]` is false, locations provided as $event contain related org_group locations and org groups are not exposed. If `[useModelWithOrgGroups]` is true a `LocationsWithOrgGroups` object is emited;
- `(ready) <BeyondLocation[]|LocationsWithOrgGroups>` - Triggered when the locations are loaded and initial value is set. If  locations provided as $event contain related org_group locations. Org groups are not exposed.;
### Message
A colored box with a message. Note that the `BeyondMessageModule` comes with a `MessageService` which allows attaching a dynamically created Message components.
- `[dismissible] string` - A key of the user preferences which holds information on this message being dismissed. A message is not dismissible if this key is not provided.
- `[type] string` - Type of the message ('alert'|'info'|'success'|'warning');
- `(ready) <boolean>` - Emitted once on dismissible messages, once the component has checked if it was dismissed or not.

![Message](doc_images/message.png)
 
### Modal
A page layout filling the whole space of a given page. Contains a header, content and footer section - it can only take these components as it's children.
- `[initializing] boolean` - Is the modal content initializing (shows spinner in place of modal content);
- `[loading] boolean` - Is the modal content loading;
- `[title] string` - A title displayed in modals header. If populated a Modal Header is created;
- `(close)` - Triggered when the close button of the modal is pressed (available in the modal header).
#### Modal Header
A modal header always has a close button that is expected to close the modal.
- `[loading] boolean` - Is the modal content loading, if not provided this value is inherited from the modal;
- `(close)` - Triggered when the close button is pressed.
#### Modal Content
- `[loading] boolean` - Is the modal content loading, if not provided this value is inherited from the modal;
#### Modal Footer
- `[loading] boolean` - Is the modal content loading, if not provided this value is inherited from the modal;
### Page
A page wrapper with assigned padding.
#### Page Header
A page header with optional buttons, displayed as a menu in mobile view. It does support transclusion.
- `[options] IButton[] | IToggle[]` - An array of button or MatSlideToggle objects representing buttons to display;
- `[title] string` - The title to display.

The type [`IToggle`](src/app/modules/beyond-components/interfaces/button.interface.ts) extends [`IButton`](src/app/modules/beyond-components/interfaces/button.interface.ts) with the fields `preLabel` and `checked`. Both types have a new member `type: 'toggle' | 'button'`.

Desktop (Beyond Search component is a transcluded element here):
![SlideToggles](doc_images/page-header.png)

Mobile (Beyond Search component is a transcluded element here):
![SlideToggles](doc_images/page-header-mobile.png)

![SlideToggles](doc_images/page-header-mobile-menu.png)

### Progress Bar
A percent progress bar displaying a percentage. This is not a loading indicator.
- `[label] string` - The label to display nex to the bar;
- `[value] number` - Progress value 0-100;
- `[showValue] boolean` - Should the percent value be displayed;
- `[showLabel]` - Should the label be displayed.
### Search
A search field with a button to expand or collapse it.
- `[disabled] boolean = false` Disable the search field;
- `[isOpen] boolean = false` Is the search drawer open (expanded);
- `[maxLength] number = 256` The [maxlength](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/maxlength) attribute of the search input;
- `[openOnInput] boolean = true` Should the rawer open when a non empty `[query]` is provided;
- `[query] string` - The query;
- `(queryChange) <string>` - Triggered when the query changes.

![SlideToggles](doc_images/search.png)

### Select
A dropdown which can be used in conjunction with an array of values or a service providing it's options. Implements [ControlValueAccessor](https://angular.io/api/forms/ControlValueAccessor). `<mat-error>` tags are transcluded in this component and may be used to contain validation errors.
- `[allLabel] string = 'All'` - The label used for displaying the 'All' option in case of multi-select mode. 
- `[compareWith] (o1: any, o2: any) => boolean` - Passed as `compareWith` [SelectControlValueAccessor property](https://angular.io/api/forms/SelectControlValueAccessor#properties) to the components select. Allows overriding the beavior of comparing values by reference.
- `[disabled] boolean` - When using [FormControl](https://angular.io/api/forms/FormControl), use the [AbstractControl.disabled](https://angular.io/api/forms/AbstractControl#disabled) property instead;
- `[errorStateMatcher] `[`ErrorStateMatcher`](https://github.com/angular/material2/blob/master/src/lib/core/error/error-options.ts) - Error state matcher passed to the select
- `[hideSearchOnSelectAll] boolean = true`- Should the search be hidden when select all option is checked in multiselect mode.
- `[isSelectAll] boolean` - Is the _All_ option selected;
- `[multiple] boolean` - Multiselect mode;
- `[noFloatLabel] boolean` - Should the label float;
- `[appearance] MatFormFieldAppearance` - allows changing mat-form-field styling;
- `[options] ISelectOption[]` - An array of available options that will populate the dropdown. If the options need to be loaded `optionsProvider` can be used;
- `[optionsProvider] `[`ISelectOptionsResource`](src/app/modules/beyond-components/interfaces/select-options-resource.interface.ts) - Pass an options provider instead of an array of options. This is intended for cases when options are loaded asynchronously. A [`SelectOptionsResourceService`](src/app/modules/beyond-components/services/select-options-resource/select-options-resource.service.ts) is available for simple cases of populating options with API object list. When using `optionsProvider` consider setting `[compareBy]` if objects can't be compared by reference. 
- `[panelClass] string | string[] | Set<string> | { [key: string]: any; } = 'beyond-select-panel'` Proxy to material select's [`panelClass`](https://v6.material.angular.io/components/select/api). 
- `[required] boolean` - When true an asterisk and a visual error indicator when no selection is made will be displayed;
- `[searchKey] string = 'name'` - The key used to display options value and to filter the options by;
- `[showSelectAll] boolean` - Should select all be displayed in case of single select mode;
- `[showSearchField] boolean = false` - Should a search field be displayed;
- `[(value)] ISelectOption[]|ISelectOption` - The option or options selected;
- `[formControl] FormControl` - The option or options selected;
- `(searchChange)` - Triggered when the select search query changes;
- `(selectAll) ISelectOption[]` - Triggered when _All_ option is selected.
---
## Beyond Admin Module

The `BeyondAdminModule` is intended for use on the admin sections of the platform. It contains the following components:

  - `AdminAuthorization` - can be used as a page, or as a component within a page. If used as a component it will only display content that it wraps when an administrator is authorized. Otherwise it will display a `AdminAuthorizationBox` component. It can take the following input:
    - `redirect any[]|false` - will redirect to given route upon authorization. You may also provide a redirect value through a `redirect` route parameter (typically if you want to use this component as a page). Setting `redirect` input to `false` will prevent any redirection happening, even when provided as a route parameter.
  - `AdminAuthorizationBox` - an input box requesting the password to authorize an administrator.
  - `EnvironmentIndicator` - a red band with a text message indicating the environment when it is not production.

The module also contains an `IsAdminGuard` guard together with an `ADMIN_AUTH_ROUTE` InjectionToken. You can use the guard to restrict access to given routes for unauthorized users. `IsAdminGuard` requires providing a string value for the `ADMIN_AUTH_ROUTE` InjectionToken which will indicate the path to an authorization page.
Example usage:

    ...
    import {AdminAuthorizationComponent, ADMIN_AUTH_ROUTE} from '@getbeyond/ng-beyond-js';
    
    const routes: Routes = [
      { path: 'restricted-component', canActivate: IsAdminGuard, component: SomeRestrictedComponent },
      { path: 'restricted-module', canLoad: [IsAdminGuard], loadChildren: '@core/modules/restricted/restricted.module#RestrctedModule' },
      { path: 'authorization', component: AdminAuthorizationComponent }
    ];
    
    @NgModule({
      imports: [RouterModule.forRoot(routes, {useHash: true})],
      exports: [RouterModule],
      providers: [{provide: ADMIN_AUTH_ROUTE, useValue: 'authorization'}]
    })
---

## Pipes
### Beyond Keep Html Pipe

Converts a string to [`SafeHtml`](https://angular.io/api/platform-browser/SafeHtml), allowing a subset of HTML markup to be used.

---
## Styling defaults
Styling is bundled into a `bundles/styles.bundle.css`. It is also available through `bundles/beyond-index.scss` where it can be altered. The easiest way to modify theme colors is to override variables in `bundles/beyond-colors.scss` or for more fine grained adjustments `bundles/beyond-theme.scss`.
The default theme color is now set in Beyond Service by getting  `color` property from `apps` endpoint. To use the default theme color in your app, you should use `var(--app-color)` whenever applicable. When you create an app, please be sure to specify it's color manually. Otherwise the default `#2E3136` will be used.
You can override the colors except the default theme color with the following setup in your styles.scss:

    /* Angular Material */
    @import '~@angular/material/theming';
    
    /* Overwrite the assets path  */
    $assets-path: 'node_modules/@getbeyond/ng-beyond-js/bundles/assets/';
    
    /* Import beyond-index */
    @import '../node_modules/@getbeyond/ng-beyond-js/bundles/beyond-index';
    
    /* Continue with any app styling below... */

There are some styling defaults provided for elements not being Beyond Components:
### Buttons
By applying a `beyond-btn` class to a `button` element a basic button style will be applied. It can be extended by adding `urgent-btn`, `subtle-btn` or `text-btn` class. Styling will also change when the button is disabled.
Buttons contained in particular components such as modal-footer, or within a container with class `beyond-text-btns` will be displayed as text only buttons.

![Buttons](doc_images/buttons.png)

### Checkboxes
Material checkboxes [`<mat-checkbox>`](https://material.angular.io/components/slide-toggle/overview) are by default styled with the blue background when checked. Adding a `beyond-checkbox` class will also make them bigger, as used in many places throughout the platform.

![Checkboxes](doc_images/checkboxes.png)

### Slide toggles
Material slide toggles [`<mat-slide-toggle>`](https://material.angular.io/components/slide-toggle/overview) have colors adjusted to match our platform defaults.

![SlideToggles](doc_images/slide-toggle.png)

### Tables
Table defaults are available with a `beyond-table` class.

### Mobile Layouts

Mobile layout is defined as `@media (max-width: 767px)`.
For mobile layouts the following css helper classes are available:

- `mobile-only` - don't display on desktop layout
- `not-mobile` - don't display on mobile layout
- `beyond-two-col-row` - organize items in a row on desktop and one under the other on mobile.