Full documentation • API reference • All releases and notes
Entangle Angular with server side code
AngularJS is awesome, but there's also a lot to be said for "traditional" server side applications - SEO, reuse of existing tools, less code duplication. With ngTangle you can "entangle" your "traditional" application with some AngularJS goodies via minimal adjustments.
npm install --save ng-tangle
import 'ng-tangle' in your application, or add a reference to
"/path/to/ng-tangle/index.js" in your HTML. ngTangle depends on
angular-route, so make sure that's also loaded.
Your Angular application must import
ngTangle as a dependency:
Download or clone the repository and follow the rest from the steps above.
ngTangle defines a few directives you can add to your (traditional) HTML to
give it AngularJS superpowers. ngTangle interceps all "normal" anchor clicks to
fake an SPA, so at the very least you'll want to use
You don't want to duplicate your routing table in Angular. Your server-side code already handles that just fine. Well: you don't have to!
tangle-template directive (as an attribute) defines an HTML element as
"updatable". Whenever ngTangle intercepts a click on an anchor, it issues an
XMLHttpRequest to get the contents instead, and after receiving them updates the
marked elements with the new content.
Templated elements should be unique in your HTML structure or weird things might happen. They must be unique based on ID (duh), class name (
.maincould be applied to a top-level
<footer>, for instance) and tag name (e.g. a page only ever has one
<title>). If any of these checks fail, the element will be left alone.
Note that ngTangle doesn't touch any existing
ng-click directives, so you can
safely mix and match. Also, any routes specifically defined in Angular will also
Any form with the
tangle-submit attribute will have its submission intercepted
and performed via an XMLHttpRequest as well. The resulting page (presumably
HTML) is subsequently fed to the
On succesfull submission, the
'tangleSubmitted' event is broadcasted to the
$rootScope. You can watch this and e.g. show a notification.
Forms not tagged with the directive are handled "the usual" way, i.e. either a
full page refresh or an
ng-submit handler (or some other handler if you're
feeling particularly masochistic).
If any page requests a redirect (by issuing one of the 3xx HTTP headers),
$http service follows it verbatim (and this is a browser feature,
not an Angular-issue). While
ngTangle correctly updates your content with the
output from the redirect, we would also like the URL in the address bar to
To accomplish this,
ngTangle looks for a
"Tangle-Target" header in the
response. This header should contain the full URI (including scheme/hostname) of
the page being rendered. If this URI differs from the one just set by
ngTangle will update it for you.
How to send custom headers depends on your server setup. E.g. in PHP you would write something like this:
<?php header("Tangle-Target: http://example.com/the/full/path/");
The target header is recommended but optional. If you omit it, Tangle simply
won't "redirect". Note that this may cause weird behaviour, e.g. when you
declare forms with
action="" and the form now points at the wrong URL.
Flushing the HTTP cache
ngTangle caches all
$http.get calls for templates using
$cacheFactory. However, there are many cases where you want
to explicitly "flush" this cache (or parts of it). For instance when a logged in
user has just logged out and menu options need to be hidden. For this purpose
you can send a custom header called
This header can contain any string, but the important thing is it should represent the "state" of the entire application. I.e., for our example of the user logging out you could simply use her user ID (which would be empty or 0 if no longer authenticated). You can usually set such a header in a central place in your application.
Note that this usage of "ETag" differs from "normal" HTTP caching in that it doesn't describe the state of the URI but rather of the entire application. How that state is computed is of course up to the implementor.
ngTangle uses the
tangleFlush event to trigger cache flushes, so
you can also call this manually (e.g. when using Web sockets and something is
known to have changed on a certain page). Either fire the event with no
parameters to clear the entire cache (quick and dirty) or optionally specify a
particular URI or an array of URIs to clear specifically. Again, these URIs must
It should also be noted that the
tangle-submit directive updates the cache
for the URI being submitted to, so in many cases the flush will happen
implicitly. It is mostly relevant if something alters the global application
This is just a quick and dirty first version. For future development:
- Make the handler smarter in what it extracts/replaces. It now just loops
through all HTML nodes in the returned string.
- Personal pet peeve: the
<script type="text/ng-template"> tag. Vim won't
syntax-highlight the HTML inside, and while I'm sure there's a plugin for that
(or else it would be trivial to write) abusing
<script> feels dirty. I'd
much rather just write HTML and have a directive to turn it into a template.