AngularJS Client Library for Lelylan

See on Github

Introduction

Build web apps for the Connected Home using the power of AngularJS and Lelylan, a new platform to monitor and control your devices through a simple, open and robust REST API.

Getting Started

Installation

Install lelylan-ng using Bower. 

$ bower install lelylan-ng --save

Basic Example

This example shows you how the client works. 

<html ng-app="app">
  <body>

    <!-- authorization -->
    <oauth
      site="http://people.lelylan.com"
      client-id="CLIENT_ID_HERE"
      redirect-uri="REDIRECT_URI_HERE"
      profile-uri="http://api.lelylan.com/me"
      scope="resources">
    </oauth>

    <!-- owned devices -->
    <div ng-controller="MainCtrl">
      <div ng-repeat="device in devices">{{device.name}}</div>
    </div>

    <script>
      function MainCtrl($scope, Device) {
        Device.all().success(function(data) { $scope.devices = data });
      }
      angular.module('app', ['lelylan.client']);
    </script>
  </body>
</html>

To fully understand how it works read the next section.

Create your first app with lelylan-ng

In this section you will learn how to create a web app showing the list of your devices.

Setup

To build our app we'll use Yeoman, a collection of tools and frameworks helping developers to quickly build web applications.

Installation

With a recent version of Node.js installed, install the yo package. In this way you have Yo, Grunt and Bower and can run them directly from the command-line. 

$ npm install -g yo

With Yeoman you can install additional generators with npm. For this tutorial you need to install the AngularJS generator. 

$ npm install -g generator-angular

Create your AngularJS app

To begin, go to the terminal, make a new directory and cd into it. 

$ mkdir new-project && cd $_

You can now kick-start your AngularJS app. 

$ yo angular

It will also ask you if you would like to include Twitter Bootstrap and other stuff. Once you've decided, just hit Enter. It will take a while to complete.

To preview what the app looks like run the serve command. 

$ grunt serve

The server supports LiveReload, meaning you can fire up a text editor, edit a custom element and the browser will reload on save.

Install lelylan-ng

Install lelylan-ng using Bower. 

$ bower install lelylan-ng --save

Now you have oauth-ng and all its dependencies ready to be used. Restart the server to automatically add them to your index page. 

$ grunt serve

The setup is now completed.

Add lelylan client

Add the Lelylan client to your AngularJS app. 

// app/scripts/app.js
angular.module('newProjectApp', ['lelylan.client', ... ])

OAuth 2.0 Server

Lelylan uses an OAuth 2.0 server for authentication and authorization. Register a new application and get your Client ID and Client Secret.

Add the oauth-ng directive

The easiest way to get an authorization token is to use oauth-ng, an AngularJS directive for OAuth 2.0. Open your main.html view, place the oauth tag and set the Client ID and Client Secret with the ones previously created. 

<oauth
  site="http://people.lelylan.com"
  client-id="CLIENT_ID_HERE"
  redirect-uri="REDIRECT_URI_HERE"
  profile-uri="http://api.lelylan.com/me"
  scope="devices">
</oauth>

Check out the oauth-ng docs if you want to better understand how it works.

Get your devices

To get your devices use the Device#all method. Open the main controller and replace the existing code with the one below. 

angular.module('newProjectApp')
  .controller('MainCtrl', function ($scope, Device) {
    Device.all()
      .success(function(data) { $scope.devices = data })
      .error(function(data) { $scope.error = 'Unauthorized request. Login first.' })
  });

In this snippet of code we inject the Device service and call the Device.all() method to get all of your devices returning a promise with two $http specific methods: success and error.

Show your devices

Supposing you have created some devices in Lelylan (if not create one), now you need to show them. Open the main.html view and list your devices by showing their names. 

<div ng-if="devices" ng-repeat="device in devices">{{device.name}}<div>

You're done!

Open your index page, click to the Login link and authorize your application to get a new access token. You are now ready to see the name of all your devices.

This is just a first simple example of what you can do. Learn how to monitor and control your devices using the device directive. for more interesting use cases.

Implemented services

All methods are fully described in the Dev Center.

Requests

Every request returns a promise with two $http specific methods: success and error. 

Device.all().
  success(function(data, status, headers, config) {
    // this callback will be called asynchronously
    // when the response is available
  }).
  error(function(data, status, headers, config) {
    // called asynchronously if an error occurs
    // or server returns response with an error status.
  });

Subscription services

When using the subscriptions API the access token is not required. In this case the authentication is done by setting the client ID and the client Secret. 

Subscription.auth({
  clientId: 'CLIENT_ID_HERE',
  clientSecret: 'CLIENT_SECRET_HERE'
});

Subscription.all().success(function(data) {
  scope.subscriptions = data
})

Caching

Every request can be cached adding the cache option. 

// makes the http request enabling the cache
Device.all({}, { cache: true }).
  success(function(data, status, headers, config) { ... }).

// get the cached request
var $cache = $cacheFactory.get('$http');
var resource = $cache.get('http://api.lelylan.com/devices');

Next time you ask for a previously cached resource, the HTTP request is not fired and the cached value is returned.

Configurations

Lelylan client accepts the following options.

Here a configuration example. 

angular.module('app').config(function(lelylanClientConfigProvider) {
  lelylanClientConfigProvider.configure({ endpoint: 'http://localhost:9000' });
});

Links

Thanks

Mail or Tweet us for any idea that can improve the project.

This project was created and released as open-source thanks to Lelylan and all people contributing with their code, ideas and passion.