Giter Site home page Giter Site logo

ngurlbind's Introduction

ngUrlBind

Easily bind AngularJS scope properties to your URL hash.

In simpler terms, if you have a property called user on your scope, with a value of {firstName: 'John', lastName: 'Doe'}, and you bind it to the URL, your URL hash will be something resembling #?user=~(firstName~'John~lastName~'Doe). When the state of $scope.user changes, the URL hash will change with it. If the page is loaded or reloaded with a valid hash, the state from the hash will be transferred to the $scope.user property on load.

See a simple example or an advanced example.

AngularJS's two-way binding allows you to bind data from a model to the DOM and back. ngUrlBind allows you to additionally bind data from an AngularJS model to the URL hash and back. Does that make it four-way binding?

While the whole Single-Page App thing is new and trendy, ngUrlBind is inspired by the "Hypermedia as the Engine of Application State" principle, one of the core components of REST's Uniform Interface constraint.

Why?

ngUrlBind is useful during development where you want to be able to hit refresh on your browser (or use livereload) without having AngularJS lose its scope state, or at least certain parts of it.

Subject to the limitations noted below, it is also useful in production, if you want your users to persist and exchange certain aspects of Angular's state. For instance think about exchange of URLs over email of IM, or just simple bookmarking.

We have made this as it's useful to us in both of these cases and are making it available to anyone else who may find it useful.

How does it work?

ngUrlBind's principle of operation is simple. Selected model properties are reflected to the URL hash as the AngularJS application is being used. They are then seeded back to the model when the page is loaded with the appropriate hash. We use the very elegant jsurl to serialise JSON data to the URL as it becomes both more readable and shorter than using Base64.

Binding a property

All you need is to inject the ngUrlBind service into your controller and call

ngUrlBind($scope, 'propertyName')

That's it. This will bind the user property of your current controller's scope to the URL hash.

Important: For the moment, only first-level properties are supported. So no dots in the 'propertyName' argument. Feel free to investigate and remove this limitation, pull requestes welcome.

Here's a more complete example:

angular.module('ngUrlBindExample', ['ngUrlBind'])
    .controller('mainCtrl', function($scope, ngUrlBind){
        $scope.user = {}
        ngUrlBind($scope, 'user')
    })

This will bind the state of the user property to the URL hash. Refreshing the page will restore the state of the user object through the URL hash.

Known Limitations

A major limitation is that ngUrlBind doesn't play well with AngularJS routing. We're fairly confident this can be remedied, but haven't had the need for now.

Another limitation is that the first user action creates a hash, which adds a step to the user's history. By strict HATEOAS this is correct, but this should probably be improved for the sake of UX and practicality.

ngUrlBind is not for everything, and it's not for everywhere. But it's got its uses.

I haven't done any performance testing, but I wouldn't be surprised if it wasn't fantastic at this point. In object.Observe() we trust.

Installation

bower install ngUrlBind

make sure ngUrlBind/dist/ngUrlBind.js is loaded before your angular module. ngUrlBind is wrapped in the Universal Module Definition so it supports AMD, CommonJS, and plain ol' global declaration via script tag.

Make your angular module require the 'ngUrlBind' module and inject the ngUrlBind service into your controller. You're ready to go.

Development

You'll need to clone this repository, have gulp installed globally (via npm install -g gulp) and then run npm install.

Once you're set up run gulp build to convert the source to a js file in /dist or simply run gulp to build continuously with a watcher. The code in /example points to the version in /dist as a dead-simple way of testing.

Future

At the end of the day this is a simple little module that's been used non-trivially in only one project. There's undoubtedly lots to fix, for which we welcome your pull requests and issues.

ngurlbind's People

Contributors

fortuneteller avatar

Watchers

 avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.