Permalink
Fetching contributors…
Cannot retrieve contributors at this time
723 lines (401 sloc) 15.9 KB

wing.angular.js

A suite of AngularJS Wing utilities.

NOTE: This is deprecated. Use wing.vue.js instead. Documentation in WingVue.

SYNOPSIS

<script src="//ajax.googleapis.com/ajax/libs/angularjs/1.3.8/angular.min.js"></script>
<script src="/wing.js"></script>
<script src="/wing.angular.js"></script>

myApp = angular.module('MyApp',['wing']);

myApp.controller('MyCtrl', function($scope, $http, objectListManager) {
  $scope.users = new objectListManager({
      fetch_options : {
          _include_options: 1,
          _include_relationships: 1, // required
      },
      list_api : '/api/user',
      create_api : '/api/user',
      on_create : function(properties, index) {
          wing.success(properties.username + ' created.');
      },
      on_update : function(properties, index) {
          wing.success(properties.username + ' saved.');
      },
      on_delete : function(properties, index) {
          wing.success('Deleted' + object.name +'.');
      },
  });
});

<!-- in html -->
<div ng-controller="MyCtrl">
  <div ng-repeat="user in users.objects">{{user.properties.username}} <button ng-click="user.delete()">Delete</button></div>
</div>

Filters

datetime

Converts a wing datetime field into a human readable string that is parsable by AngularJS.

{{some_object.some_date | datetime:'mediumDate'}}

timeago

Converts a wing datetime field into a human readable string like 3 minutes ago.

{{some_object.some_date | timeago}}

Factories

confirmations

Enables and disables confirmations in objectManager and objectListManager.

myApp.controller('MyCtrl', function($scope, $http, confirmations) {
 $scope.confirmations = confirmations;
});

enabled()

Returns true if confirmations are enabled.

disabled()

Returns true if confirmations are disabled.

toggle()

Sets confirmations equal to true if they are currently false and false if they are currently true. If they are currently true then the user will be asked to confirm whether they want to disable confirmations.

objectManager

Manages an instance of a Wing object, aka a row in the database.

myApp.controller('MyCtrl', function($scope, $http, objectManager) {
  $scope.users = new objectManager({
      fetch_options : {
          _include_options: 1,
          _include_relationships: 1, // required
      },
      fetch_api : '/api/user/XXX',
      on_update : function(properties) {
          wing.success(properties.username + ' saved.');
      },
      on_delete : function(properties) {
          wing.success('Deleted' + object.name +'.');
      },
  });
});
options

An object of behavior changing options.

properties

Set the object's properties before it is fetched or created.

fetch_api

The URI used to fetch an object from Wing.

/api/user/XXX
fetch_options

A list of behavior changing options.

{
  "_include_relationships" : 1
}
on_fetch

A function to call when the object is initially fetched. It is passed the object's properties.

on_error

A function to call if anything errors with talking to Wing about the object. It is passed whatever it gets back from Wing.

on_create

A function to be called when the object is created.

on_update

A function to be called whenever this object is successfully updated.

on_delete

A function to be called when this object is deleted.

create_api

The URI used to create the object in Wing.

/api/user
with_credentials

Defaults to true. If you don't want to pass your credentials to the server, then set to false.

properties

An object containing the list of properties retrieved from Wing.

fetch(options)

options

An optional object containing a set of behavior modifiying options.

on_success

A function to call when the object is initially fetched. It is passed the object's properties.

on_error

A function to call if the fetch fails.

create(properties, options)

Create this object in Wing.

properties

A required object containing the properties to create the object in Wing with.

options

An optional object containing behavior changing options.

on_success

A function to be called if the creation is successful. It is passed a list of properties, and then a reference to the newly created objectManager.

on_error

A function to be called if the creation fails.

update(options)

Updates the database with the properties in this object.

options

See partial_update() for details.

save(property)

Updates the value of property in the database with the value of property in this object.

partial_update(properties, options)

Updates this object and the database with properties.

properties

A required object containing properties for this object.

options

An optional object containing behavior changing options.

on_success

A function to be called after the update succeeds.

on_error

A function to be called if the update fails.

call(method, uri, properties, options)

Make a call to an arbitrary web service, the result of which is expected to be a property list for this object. This object is then updated with that property list.

method

GET, PUT, DELETE, or POST.

uri

The URI you wish to call.

/api/user/XXX/check-in
properties

An object containing any parameters you wish to pass to the service you're calling.

options

An optional object containing behavior changing options.

on_success

A function to be called when this call is successful.

on_error

A function to be called if this call errors.

delete(options)

Deletes this object from Wing. Will ask for confirmation before delete. Confirmations can be managed by the confirmations factory.

options

An optional object containing behavior changing options.

on_success

A function to be called when this delete succeeds.

on_error

A function to be called if the delete fails.

skip_confirm

If this is true then the user will not be asked to confirm the delete.

objectListManager

Manages a list of Wing objects, aka a selection of rows in the database. This is a list of objectManagers.

myApp.controller('MyCtrl', function($scope, $http, objectListManager) {
  $scope.users = new objectListManager({
      fetch_options : {
          _include_options: 1,
          _include_relationships: 1, // required
      },
      list_api : '/api/user',
      create_api : '/api/user',
      on_create : function(properties, index) {
          wing.success(properties.username + ' created.');
      },
      on_update : function(properties, index) {
          wing.success(properties.username + ' saved.');
      },
      on_delete : function(properties, index) {
          wing.success('Deleted' + object.name +'.');
      },
  });
});
list_api

Required if you want to retrieve a list of objects. The URI to fetch a list of objects of this type from Wing.

/api/user
fetch_options

An object containing the parameters used to filter the list of objects retrieved. This all comes from the Wing REST API (RestUsage).

{
  _sort_by : 'name',
  query : 'blue'
  _include_relationships : 1,
  _include_related_objects : 1
}
create_api

Required if you want to create objects. The URI to post to to create an object of this type.

/api/user
options_api

Normally auto generated from the create_api, but you can override it here. Used with the fetch_options() method.

/api/user/_options
on_create

A function to be executed when a new object is created. It will be passed the properties of the object and an index number.

on_update

A function to be executed when an object is updated. It will be passed the properties of the object and an index number.

on_delete

A function to be executed when an object is deleted. It will be passed the properties of the object and an index number.

on_each

A function to be executed when an object is initially retrieved. It will be passed the objectManager instance of the object.

with_credentials

Defaults to true. If you don't want to pass your credentials to the server, then set to false.

objects

A list of objectManager objects currently managed by the list manager.

paging

An object containing pagination information about the current list.

{
 "total_pages" : 1,
 "next_page_number" : 2,
 "total_items" : "3",
 "previous_page_number" : 1,
 "items_per_page" : "10",
 "page_number" : "1"
}

find_object(id)

Return the index number of a specific object in the list based upon id. Returns -1 if the object is not found.

id

The unique id of the object in the database.

get_object(id)

Return an object in the list based upon id. Returns null if the object is not found.

id

The unique id of the object in the database.

search(options)

options

An object containing various search behavior modifications.

params

Put search params here that you don't want to be attached to all subsequent queries via the fetch_options.

accumulate

If set to true, the object list will not be reset before adding the newly fetched data.

on_create

A function to be executed when a new object is created. It will be passed the properties of the object and an index number.

on_update

A function to be executed when an object is updated. It will be passed the properties of the object and an index number.

on_delete

A function to be executed when an object is deleted. It will be passed the properties of the object and an index number.

on_each

A function to be executed when an object is initially retrieved. It will be passed the properties of the object, and the objectManager instance of the object.

on_success

A function to be executed when an a result set comes back on successful search. It will be passed the result set.

all(options)

Similar to search() except that it fetches the complete list of objects, not just one page of them.

options
params

Put search params here that you don't want to be attached to all subsequent queries via the fetch_options.

on_each

A function to be executed when an object is initially retrieved. It will be passed the properties of the object, and the objectManager instance of the object.

on_all_done

A function to be executed once all objects have been fetched.

on_success

A function to be executed after each page of objects has been retrieved.

reset()

Sets the object list to empty and then returns a reference to the objectListManager.

fetch_options(store_data_here, options)

Fetches object creation options. The URI it fetches them from is based upon the create_uri passed into the constructor, unless you specified options_api in the constructor. Stores an object containing information retrieved by fetch_creation_options. This data provides enumerated lists of data that can be used to create or update an object.

{
     "registration" : [
        "pending",
        "open",
        "closed"
     ],
     "_registration" : {
        "closed" : "Closed",
        "open" : "Open",
        "pending" : "Pending"
     },
     "private" : [
        0,
        1
     ],
     "_private" : {
        "1" : "Private",
        "0" : "Public"
     }
}
store_data_here

Pass in an existing object and the options retrieved will be stored in this location.

options

An optional object that modifies the behavior of the request.

on_success

This method will be executed if the options fetch is successful. Gets passed the result of the request.

on_error

This method will be executed if the options fetch is an error. Gets passed the result of the request.

create(properties, options)

Create a new object in the database and insert it into this list.

unshift

By default new objects are pushed on to the end of the list. If this property is set to true then the new object will be prepended to the list.

on_success

A function to be executed if the object is sucessfully created. It is passed a list of properties.

update(index, options)

Updates the object's properties in the database with the object's properties in objectManager. See update() in objectManager for details.

index

The index number of the object in the objects list.

options

See update() in objectManager for details.

save(index, property)

Updates the value of property in the database with the value of property in objectManager. See save() in objectManager for details.

index

The index number of the object in the objects list.

options

See save() in objectManager for details.

partial_update(index, properties, options)

Updates a specific set of properties in the database and objectManager specified by properties. See partial_update() in objectManager for details.

index

The index number of the object in the objects list.

options

See partial_update() in objectManager for details.

delete(index, options)

Deletes the object from the database and objectListManager. See delete() in objectManager for details.

index

The index number of the object in the objects list.

options

See delete_update() in objectManager for details.

Directives

input[number]

If an input tag is of type number then it will force the value to be a number even if it is cast as a string.

<input type="number" model="user.age">

forceNumber

Forces a model value to be a number.

<input type="text" model="user.employee_number" force-number>

autosave

Automatically save the value of a form element anytime the model is updated.

<input ng-model="object.properties.property_name" autosave="object">

forceString

Forces a model value to be a string.

<input type="text" model="user.employee_number" force-string>

wingSelect

If an object included _include_options in its fetch_properties then you can display those options easily as a list using this directive.

<wing-select object="object_name" property="property_name"></wing-select>

checklist

In Angular one checkbox input type="checkbox" ng-model="..." is linked with one model. But in practice we usually want one model to store array of checked values from several checkboxes. Checklist solves that task without additional code in controller.

checklist-model

Required. Use instead of ng-model.

checklist-value

What should be picked as array item.

value

What should be picked as item, but unlike checklist-value, this does not evaluate as an angular expression, but rather a static value.

ng-model

Every checkbok will span a new scope and define a variable named checked to hold its state. You can modify this name by using this attribute.

checklist-comparator

A custom comparator. If it starts with dot(.) then it will be an expression applied to the array item. Otherwise it should evaluate to a function as an angular expression. The function return true if the first two arguments are equal and false otherwise.

checklist-before-change

An angular expression evaluated each time before the checklist-model has changed. If it evaluates to 'false' then the model will not change anymore.

checklist-change

An angular expression evaluated each time the checklist-model has changed.