@getbeyond/ng-beyond-js v3.0.16

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 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, 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 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 interface used within mobile apps. If you are looking for a method to check being in the mobile app context, use BeyondSession.getMobileAppInfo().

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. If no value is passed as from and to it's initial value will default to 'Yesterday'. Implements 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, use the 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.

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 of the element that it is applied to.

Info Grid

A component to display a set of values with labels organised as 2 columns based on an array of BeyondInfoGridItem 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.

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. <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, use the AbstractControl.disabled property instead;
• [errorStateMatcher]ErrorStateMatcher - 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, 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.

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 extends IButton with the fields preLabel and checked. Both types have a new member type: 'toggle' | 'button'.

Desktop (Beyond Search component is a transcluded element here):

Mobile (Beyond Search component is a transcluded element here):

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 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.

Select

A dropdown which can be used in conjunction with an array of values or a service providing it's options. Implements 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 to the components select. Allows overriding the beavior of comparing values by reference.
• [disabled] boolean - When using FormControl, use the AbstractControl.disabled property instead;
• [errorStateMatcher]ErrorStateMatcher - 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 - Pass an options provider instead of an array of options. This is intended for cases when options are loaded asynchronously. A SelectOptionsResourceService 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.
• [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, 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.

Checkboxes

Material checkboxes <mat-checkbox> 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.

Slide toggles

Material slide toggles <mat-slide-toggle> have colors adjusted to match our platform defaults.

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.