mobile-angular-ui.core.sharedState is expose the homonymous service SharedState and a group of directives to access it.

SharedState allows to use elementary angular or angularish directives to create interactive components.

Ie.

<div class="nav nav-tabs" ui-shared-state='activeTab'>
  <a ui-set="{activeTab: 1}">Tab1</a>
  <a ui-set="{activeTab: 2}">Tab2</a>
  <a ui-set="{activeTab: 3}">Tab3</a>
</div>
<div class="tabs">
  <div ui-if="activeTab == 1">Tab1</div>
  <div ui-if="activeTab == 2">Tab2</div>
  <div ui-if="activeTab == 3">Tab3</div>
</div>

Using SharedState you will be able to:

  • Create interactive components without having to write javascript code
  • Have your controller free from UI logic
  • Separe ng-click triggering application logic from those having a visual effect only
  • Export state of components to urls
  • Easily make components comunicate each other

Also note that:

Data structures retaining statuses will stay outside angular scopes thus they are not evaluated against digest cycle until its necessary. Also although statuses are sort of global variables SharedState will take care of disposing them when no scopes are requiring them anymore.

A set of ui-* directives are available to interact with SharedState module and will hopefully var you spare your controllers and your time for something that is more meaningful than this:

$scope.activeTab = 1;

$scope.setActiveTab = function(n) {
  $scope.activeTab = n;
};

Usage

Declare it as a dependency to your app unless you have already included some of its super-modules.

angular.module('myApp', ['mobile-angular-ui.core.sharedState']);

Use ui-shared-state directive to require/initialize a state from the target element scope

Example. Tabs

Example. Custom components

NOTE: ui-toggle/set/turnOn/turnOff responds to click/tap without stopping propagation so you can use them along with ng-click too. You can also change events to respond to with ui-triggers attribute.

Any SharedState method is exposed through Ui object in $rootScope. So you could always do ng-click="Ui.turnOn('myVar')".

Since SharedState is a service you can initialize/set statuses through controllers too:

app.controller('myController', function($scope, SharedState){
  SharedState.initialize($scope, "activeTab", 3);
});

As well as you can use ui-default for that:

<div class="tabs" ui-shared-state="activeTab" ui-default="thisIsAnExpression(5 + 1 - 2)"></div>

Services

SharedState service

  • mobile-angular-ui.state.initialized.ID - event
  • mobile-angular-ui.state.destroyed.ID - event
  • mobile-angular-ui.state.changed.ID - event
  • initialize - method
  • setOne - method
  • setMany - method
  • set - method
  • turnOn - method
  • turnOff - method
  • toggle - method
  • get - method
  • isActive - method
  • active - method
  • isUndefined - method
  • has - method
  • referenceCount - method
  • equals - method
  • eq - method
  • values - method

A SharedState state can be considered as a global variable identified by an id.

SharedState service exposes methods to interact with statuses to create, read and update states.

It acts as a BUS between UI elements to share UI related state that is automatically disposed when all scopes requiring it are destroyed.

eg.

app.controller('controller1', function($scope, SharedState){
  SharedState.initialize($scope, 'myId');
});

app.controller('controller2', function(SharedState){
  SharedState.toggle('myId');
});

Data structures retaining statuses will stay outside angular scopes thus they are not evaluated against digest cycle until its necessary. Also although statuses are sort of global variables SharedState will take care of disposing them when no scopes are requiring them anymore.

A set of ui-* directives are available to interact with SharedState module and will hopefully var you spare your controllers and your time for something that is more meaningful than this:

$scope.activeTab = 1;

$scope.setActiveTab = function(n) {
  $scope.activeTab = n;
};

Methods in SharedState

initialize
method in SharedState

SharedState.initialize(scope, id, [options])

Initialize, or require if already intialized, a state identified by id within the provided scope, making it available to the rest of application.

A SharedState is bound to one or more scopes. Each time initialize is called for an angular scope this will be bound to the SharedState and a reference count is incremented to allow garbage collection.

Reference count is decremented once the scope is destroyed. When the counter reach 0 the state will be disposed.

ParamTypeDescription
scopescope

The scope to bound this state

idstring

The unique name of this state

[options]object

Options

[options.defaultValue]object

the initialization value, it is taken into account only if the state id is not already initialized

[options.exclusionGroup]string

Specifies an exclusion group for the state. This means that for boolean operations (ie. toggle, turnOn, turnOf) when this state is set to true, any other state that is in the same exclusionGroup will be set to false.

setOne
method in SharedState

SharedState.setOne(id, value)

Set the value of the state identified by id to the value parameter.

ParamTypeDescription
idstring

Unique identifier for state

valueany

New value for this state

setMany
method in SharedState

SharedState.setMany(object)

Set multiple statuses at once. ie.

SharedState.setMany({ activeTab: 'firstTab', sidebarIn: false });
ParamTypeDescription
objectobject

An object of the form {state1: value1, ..., stateN: valueN}

set
method in SharedState

SharedState.set(idOrMap, [value])

A shorthand for both setOne and setMany. When called with only one parameter that is an object it is the same of setMany, otherwise is the same of setOne.

ParamTypeDescription
idOrMapstring | object

A state id or a {state: value} map object.

[value]any

The value to assign in case idOrMap is a string.

turnOn
method in SharedState

SharedState.turnOn(id)

Set shared state identified by id to true. If the shared state has been initialized with exclusionGroup option it will also turn off (set to false) all other statuses from the same exclusion group.

ParamTypeDescription
idstring

The unique name of this state

turnOff
method in SharedState

SharedState.turnOff(id)

Set shared state identified by id to false.

ParamTypeDescription
idstring

The unique name of this state

toggle
method in SharedState

SharedState.toggle(id)

If current value for shared state identified by id evaluates to true it calls turnOff on it otherwise calls turnOn. Be aware that it will take into account exclusionGroup option. See #turnOn and #initialize for more.

ParamTypeDescription
idstring

The unique name of this state

get
method in SharedState

SharedState.get(id) ⟶ any

Returns the current value of the state identified by id.

ParamTypeDescription
idstring

The unique name of this state

isActive
method in SharedState

SharedState.isActive(id) ⟶ bool

Return true if the boolean conversion of #get(id) evaluates to true.

ParamTypeDescription
idstring

The unique name of this state

active
method in SharedState

SharedState.active(id) ⟶ bool

Alias for #isActive.

ParamTypeDescription
idstring

The unique name of this state

isUndefined
method in SharedState

SharedState.isUndefined(id) ⟶ bool

Return true if state identified by id is not defined.

ParamTypeDescription
idstring

The unique name of this state

has
method in SharedState

SharedState.has(id) ⟶ bool

Returns true if state identified by id exsists.

ParamTypeDescription
idstring

The unique name of this state

referenceCount
method in SharedState

SharedState.referenceCount(id) ⟶ integer

Returns the number of references of a status.

ParamTypeDescription
idstring

The unique name of this state

equals
method in SharedState

SharedState.equals(id, value) ⟶ bool

Returns true if #get(id) is exactly equal (===) to value param.

ParamTypeDescription
idstring

The unique name of this state

valueany

The value for comparison

eq
method in SharedState

SharedState.eq(id, value) ⟶ bool

Alias for #equals

ParamTypeDescription
idstring

The unique name of this state

valueany

The value for comparison

values
method in SharedState

SharedState.values() ⟶ object

Returns an object with all the status values currently stored. It has the form of {statusId: statusValue}.

Bear in mind that in order to spare resources it currently returns just the internal object retaining statuses values. Thus it is not intended to be modified and direct changes to it will be not tracked or notified.

Just clone before apply any change to it.

Events in SharedState

mobile-angular-ui.state.initialized.ID
event in SharedState

Broadcasted on $rootScope when #initialize is called for a new state not referenced by any scope currently.

ParamTypeDescription
currentValueany

The value with which this state has been initialized

mobile-angular-ui.state.destroyed.ID
event in SharedState

Broadcasted on $rootScope when a state is destroyed.

mobile-angular-ui.state.changed.ID
event in SharedState

Broadcasted on $rootScope the value of a state changes.

$scope.$on('mobile-angular-ui.state.changed.uiSidebarLeft', function(e, newVal, oldVal) {
  if (newVal === true) {
    console.log('sidebar opened');
  } else {
    console.log('sidebar closed');
  }
});
ParamTypeDescription
newValueany
oldValueany

Directives

uiSharedState directive

    Calls SharedState#initialize on the scope relative to the element using it.

    ParamTypeDescription
    uiStatestring

    The shared state id

    [uiDefault]expression

    the default value

    uiState directive

      Alias for uiSharedState. Deprecated since it clashes with UI-Router uiState directive.

      ParamTypeDescription
      uiStatestring

      The shared state id

      [uiDefault]expression

      the default value

      uiToggle directive

        Calls SharedState#toggle when triggering events happens on the element using it.

        ParamTypeDescription
        uiTogglestring

        the target shared state

        uiDefaultexpression

        the default value

        uiTurnOn directive

          Calls SharedState#turnOn when triggering events happens on the element using it.

          ParamTypeDescription
          uiTurnOnstring

          the target shared state

          uiDefaultexpression

          the default value

          uiTurnOff directive

            Calls SharedState#turnOff when triggering events happens on the element using it.

            ParamTypeDescription
            uiTurnOffstring

            the target shared state

            [uiTriggers='click tap']string

            the event triggering the call.

            uiSet directive

              Calls SharedState#set when triggering events happens on the element using it.

              ParamTypeDescription
              uiSetobject

              The object to pass to SharedState#set

              [uiTriggers='click tap']string

              the event triggering the call.

              uiIf directive

                Same as ngIf but evaluates condition against SharedState statuses too

                ParamTypeDescription
                uiIfexpression

                A condition to decide wether to attach the element to the dom

                [uiScopeContext]list

                A list scopeVar[ as aliasName] [, ...] specifing one of more scope variables to take into account when evaluating condition.

                uiHide directive

                  Same as ngHide but evaluates condition against SharedState statuses

                  ParamTypeDescription
                  uiShowexpression

                  A condition to decide wether to hide the element

                  [uiScopeContext]list

                  A list scopeVar[ as aliasName] [, ...] specifing one of more scope variables to take into account when evaluating condition.

                  uiShow directive

                    Same as ngShow but evaluates condition against SharedState statuses

                    ParamTypeDescription
                    uiShowexpression

                    A condition to decide wether to show the element

                    [uiScopeContext]list

                    A list scopeVar[ as aliasName] [, ...] specifing one of more scope variables to take into account when evaluating condition.

                    uiClass directive

                      A simplified version of ngClass that evaluates in context of SharedState, it only suppors the {'className': expr} syntax.

                      ParamTypeDescription
                      uiClassexpression

                      An expression that has to evaluate to an object of the form {'className': expr}, where expr decides wether the class should appear to element's class list.

                      [uiScopeContext]list

                      A list scopeVar[ as aliasName] [, ...] specifing one of more scope variables to take into account when evaluating condition.

                      comments powered by Disqus