widget_services

Factory for the services that are available to the controller of a widget, regardless of the underlying view framework.

Contents

Module Members

Types

Module Members

axAreaHelper AxAreaHelper

Allows to manage the widget's areas.

axAssets AxAssets

Provides access to the widget's assets.

axConfiguration Configuration

Interface to the full configuration the application was bootstrapped with.

axContext AxContext

Combines essential widget services with some instance information to be passed around en bloc.

axControls ControlLoader

Provides access to implementation modules of the controls used by the widget.

axDebugEventBus AxEventBus

Provides access to a super-global EventBus shared by Laxar instances.

axEventBus AxEventBus

Event bus instance specifically enriched for the widget instance.

axFeatures Object

The features the widget was configured with. Its structure depends on the schema defined in the widget descriptor (widget.json).

axFlowService FlowService

Allows to generate URLs based on navigation targets or place IDs, in order to create links.

axGlobalEventBus EventBus

The global event bus instance of the application.

The widget-specific axEventBus should always be prefered over this, since subscriptions to the global event bus will not be cleaned up automatically as clients are destroyed, which can lead to severe memory leaks. A valid use case could be an activity that needs to add an inspector to the event bus in order to provide debuggig information about application events, or to log specific events without stopping on page navigation.

axGlobalLog Logger

Allows to log messages, taking into account the configured log level.

axGlobalStorage StorageFactory

The global storage factory allows to share storage items across widgets.

axHeartbeat Heartbeat

The heartbeat instance allows to perform actions such as dirty checking after each event bus cycle.

axI18n AxI18n

I18n API that allows to localize values depending on the locale configured for the widget.

axId( localUniqueId )

A function that generates page-wide unique IDs based on IDs that are unique within the scope of a widget.

A common use case is the connection of a label HTML element and an input element via for and id attributes. To avoid collisions, IDs should always be generated using this service.

Example:

// ... inject `axId`, get reference to `widgetDom` (depends on integration technology) ...
widgetDom.querySelector( 'label' ).setAttribute( 'for', axId( 'myField' ) );
widgetDom.querySelector( 'input' ).setAttribute( 'id', axId( 'myField' ) );
Parameters
Property Type Description
localUniqueId String an identifier that is unique within a widget
Returns
Type Description
String an identifier that is unique for the current page

axLog Logger

The widget logger instance. Similar to #axGlobalLog, but adds the name of the widget as prefix and the widget ID as suffix to every log message.

axStorage AxStorage

Preconfigured storage API for a widget: all keys are namespaced using the widget ID, in order to limit item visibility to this specific instance.

axTooling AxTooling

Access to the tooling provider API.

axVisibility AxVisibility

Visibility services for a widget instance.

Types

AxContext

This object encapsulates widget context information and provides access to the most important widget specific service instances. Most commonly this is used when working with LaxarJS Patterns.

AxContext.eventBus AxEventBus

The event bus instance of the widget. This is the same as #axEventBus.

AxContext.features Object

The configured features of the widget. This is the same as #axFeatures.

AxContext.id()

The unique id generator function. This is the same as #axId.

AxContext.log AxLog

The widget local log instance. This is the same as #axLog.

AxContext.widget Object

Some information regarding the widget instance.

The following fields are available:

  • area: full name of the area the widget is located in
  • id: the unique id of the widget on the page
  • path: path of the widget that was used to reference it in the according page or composition. This is not the actual path on the file system, but most probably an alias known by the used module loader.

AxAreaHelper

AxAreaHelper.isVisible( fullAreaName )

Query if a given widget area is currently visible by accessing the underlying area status through the page controller. Can be used to determine the current visibility state of an area without having to constantly observe visibility events.

Parameters
Property Type Description
fullAreaName String the global name of the area
Returns
Type Description
Boolean the current visibility state of the given area

AxAreaHelper.fullName( localAreaName )

Looks up the global name of a widget area within a widget, as generated by LaxarJS. This is the reverse of #AxAreaHelper.localName().

Parameters
Property Type Description
localAreaName String the widget-local name of the area
Returns
Type Description
String the globally valid name of the area

AxAreaHelper.localName( fullAreaName )

Returns the local part of a global area name. This is the reverse of #AxAreaHelper.fullName().

Parameters
Property Type Description
fullAreaName String the global name of the area
Returns
Type Description
String the name of the area as it is known to the widget

AxAreaHelper.register( localAreaName, element )

Registers a DOM element as area of a widget with the area helper.

Parameters
Property Type Description
localAreaName String the widget-local name of the area
element HTMLElement the element to register as widget area

AxAssets

Note: This service is a function with the #AxAssets.url(), #AxAssets.forTheme() and #AxAssets.urlForTheme() functions as properties.

Resolves an asset located directly in the widget folder or a subfolder of it. Valid assets are all non-binary files like JSON or text files. For binary files there exists the #AxAssets.url function.

Example:

// ... inject `axAssets` ...
axAssets( 'data.json' ).then( fileContent => { ... } );
Parameters
Property Type Description
name String name of the asset to resolve
Returns
Type Description
Promise promise for the asset

AxAssets.url( name )

Resolves the absolute url to the given asset located directly in the widget folder or a subfolder of it. This can then be safely used in e.g. video or img tags.

Example:

// ... inject `axAssets`, find `img` in DOM ...
axAssets.url( 'tux.jpg' ).then( url => { img.src = url; } );
Parameters
Property Type Description
name String name of the asset the url should be returned of
Returns
Type Description
Promise promise for the url

AxAssets.forTheme( name )

Resolves an asset from one of the *.theme subfolders of the widget. The folder from which the asset is taken, depends on the selected theme and the availability of the file within that theme (See here for further information on theme asset lookup). Valid assets are all non-binary files like JSON or text files. For binary files there exists the #AxAssets.urlForTheme function.

Example:

// ... inject `axAssets` ...
axAssets.forTheme( 'some-template.html' ).then( template => { ... } );
Parameters
Property Type Description
name String name of the asset to resolve
Returns
Type Description
Promise promise for the asset

AxAssets.urlForTheme( name )

Resolves the absolute url to the given asset from one of the *.theme subfolders of the widget. This can then be safely used in e.g. video or img tags. The folder from which the asset is taken, depends on the selected theme and the availability of the file within that theme (See here for further information on theme asset lookup).

Example:

// ... inject `axAssets`, find `img` in DOM ...
axAssets.urlForTheme( 'icon.jpg' ).then( url => { img.src = url; } );
Parameters
Property Type Description
name String name of the asset the url should be returned of
Returns
Type Description
Promise promise for the url

AxStorage

Ready to use storage API for a single widget instance. All keys are namespaced by the widget id to limit visibility to this specific instance.

AxStorage.local StorageApi

An instance of the storage api using the persistent window.localStorage.

AxStorage.session StorageApi

An instance of the storage api using the non-persistent window.sessionStorage.

AxEventBus

This is an extension of the global EventBus by widget specific information and tasks. For example a combination of the widget's name and its id is always used as subscriber and sender id. Hence for example EventBus.publishAndGatherReplies works without passing in any options.

Additionally all subscriptions of a widget are removed as soon as the widget itself is destroyed. So in practice a widget will receive no further events after the endLifecycleRequest event processing has finished.

The documentation for the events bus api can be found here.