digitalbazaar / bedrock-angular

Bedrock AngularJS Framework

bedrock-angular

A bedrock bower module that provides an extensible AngularJS application. The application provides common, basic functionality such as a simple, bedrock-integrated, configuration system, animations, application routing, multi-transclusion support, and UI Bootstrap support. It can be extended using other angular modules, in most cases, by simply installing them via bower.

Click here to read about style guidelines and how to write AngularJS modules for the bedrock framework.

Click here to learn how to write a bedrock-angular "pseudo bower" package.

Quick Examples

bower install bedrock-angular

Configuration

How It Works

A Quick Bedrock Primer

Bedrock is a foundation onwhich to build web applications. It uses a modular design to help keep code well-organized and to allow a healthy ecosystem to grow without hindrance. It is also designed to make it possible to provide most of the generic, core infrastructure your project needs via simple installation, with zero or minimal configuration.

Bedrock web applications are typically built by installing a backend npm module, bedrock-views, and a companion frontend bower package, bedrock-angular.

The bedrock-views module, via a dependency bedrock-requirejs, expects all frontend code to behave like a bower package. This means that any packages you install via bower will be automatically made available to the browser once you've installed them and restarted your bedrock server. If you want to serve a directory that isn't in a bower package, you can manually add a bower manifest for it to bedrock's configuration system. This establishes a "pseudo bower package" for your directory, causing it to be treated just like it was any other bower package.

Click here to learn how to write a bedrock-angular "pseudo bower" package.

The bedrock-angular package will create a core, generic AngularJS application for you, and automatically integrate any bower packages that contain AngularJS components.

So, taken together, all you should need to do to add new frontend content to your bedrock-based AngularJS web application is install bower packages or manually describe directories as if they were bower packages.

Overview

Serving components

First we need to learn how bedrock makes components available to the browser. When components are installed via bower packages, bedrock will automatically parse their bower.json files and make them available to the browser.

Not every component will be installed via bower. For those that are manually integrated into our application, we need to update bedrock's configuration to tell bedrock to treat them as if they were bower packages.

To do this we create a "pseudo bower package" for each component. This is just a way to get directories to behave like bower packages, so that bedrock can deal with both bower packages and directories in a consistent way.

These "pseudo bower packages" are pushed onto an array that is referenced in bedrock's configuration system as:

bedrock.config.requirejs.bower.packages

Click here to learn how to write a bedrock-angular "pseudo bower" package.

Template replacement

Click here to learn how to write a basic "skinning" package.

Click here to learn how to write an advanced "skinning" package.

bedrock-angular's Issues

Rename "showLoginModal" event

The showLoginModal event name is too specific. Instead, some kind of permission denied event should be emitted that could be handled by some other module to potentially show a login modal (or do something else).

See: https://github.com/digitalbazaar/bedrock-angular/blob/master/app.js#L143-L144

// invalid session or missing session, show login modal
$rootScope.$emit('showLoginModal');

What happened to demo-warning-component?

It used to live here, where is it now?

Create brJsonLdService

Move these lines:

https://github.com/digitalbazaar/bedrock-angular/blob/master/app.js#L224-L232

  // configure document loader to load security context locally
  jsonld.useDocumentLoader('xhr', {secure: true});
  var documentLoader = jsonld.documentLoader;
  jsonld.documentLoader = function(url) {
    if(url === 'https://w3id.org/security/v1') {
      url = config.data.baseUri + '/contexts/security-v1.jsonld';
    }
    return documentLoader(url);
  };

Into a new brJsonLdService that doesn't modify the shared AMD jsonld instance.

Update analytics support.

The current Google Analytics support will only fire an event for the first page loaded. It does not have support for the current "single page app" style. Some options:

• Use a GA or general analytics lib:
  • https://angulartics.github.io/
• Update snippet and add SPA support by hand.
  • Example: https://spin.atomicobject.com/2016/11/21/google-analytics-angularjs-app-ngroutes/
  • Ref: https://developers.google.com/analytics/devguides/collection/analyticsjs/
  • Ref: https://developers.google.com/analytics/devguides/collection/analyticsjs/tracking-snippet-reference
• Drop support here and add to new module (which would probably just load https://angulartics.github.io/).
• Drop support here and leave it to applications.

Make route resolve spinner more extensible

See: https://github.com/digitalbazaar/bedrock-angular/blob/master/app-component.html#L5-L9

We should make the route resolver extensible so its look and feel can be modified, its appearance can be delayed, etc. We should probably make it a component that can be swapped out.

Add filter/pipe for doing `requirejs.toUrl` from HTML templates

Presently, if you want to ensure your bower-package-relative URL is properly formed, you need to either call, from a controller, requirejs.toUrl or use $root.requirejs.toUrl in an angular HTML expression. We should create a filter (angular 1 terminology)/pipe (angular 2 terminology) that does this more cleanly and provide it to all packages that depend on bedrock-angular as a general feature:

So this:

<ng-include src="$root.requirejs.toUrl('package-name/foo.html')">

Becomes:

<ng-include src="'package-name/foo.html' | resolvePackageUrl">

The name "resolvePackageUrl" can be bikeshedded.

Consider adding a more customizable main page layout

This new layout would be optional (controlled via a config var) for backwards compatibility. The main idea is to make the main app component HTML not include any "magic" br-navbar or br-alert (or similar) components that reside above the ng-view component. Instead, only the ng-view component would exist. If a bedrock application author desired a navbar or alerts, they would put these components in each of their route components.

Some more thoughts on this issue:

Our main site layout (like most examples we can find on the Web) puts the navbar outside of the ng-view. This means that the navbar component does not need to be reparsed and setup on every route change, which is efficient. However, it also means that it lives in a different scope from the routes and it makes customizing the navbar based on the current route use a different mechanism from every other customization of components in the application that happens within ng-view.

If we were to place the navbar within ng-view, it would mean that every route component would need to include the navbar (boilerplate) or some other boilerplate component that included the navbar for them. This may also introduce additional API requirements to pass information through to where it needs to be. However, every customization of routes and every “resolved” variable would be done the same way throughout the application. It would also mean that hiding/showing or using different navbars would be much easier when writing custom applications as full control would be done via route components vs. there being some core HTML in bedrock-angular that resides outside of ng-view that’s always there but can be “turned off” via special options. Changing navbar options of any sort would be a simple matter of passing the right variables to the navbar component within one’s own route component. This approach would manifest full top-down control rather than top-down control for everything in an ng-view except the navbar, which presently requires some special bottom-up expression of variables that live outside of the scope of the route and that the navbar knows to look for on a given route.

supportDomain is not an available variable

On the 404 page, we have a "contact us" help link, like so:

<a href="mailto:support@{{supportDomain}}">Customer Support</a>.</p>

where supportDomain was probably at one point pulled from a vars config somewhere. This no longer happens though, and supportDomain is not a part of the controller on the component, so it's broken everywhere.

Disable debug data in production mode

https://docs.angularjs.org/guide/production#disabling-debug-data

Use of $onInit and $onChanges

I want to have a conversation about our use of these lifecycle hooks.

There is a pattern emerging in a number of modules where we use BOTH the $onChanges and $onInit hooks to run an init function. Here's an example in bedrock-angular-key: https://github.com/digitalbazaar/bedrock-angular-key/blob/master/keys-component.js#L40-L48

The first thing I want to make sure we are all aware of is that $onChanges is triggered before $onInit. This seems a bit counter-intuitive but according to this issue, it's done this way by design: angular/angular.js#14433

What we see happening in bedrock-angular-key is that init() is being called twice for no good reason. First by $onChanges, then again by $onInit. This of course results in redundant HTTP requests etc.

It seems to me that this emerging pattern of calling init() in both handlers needs to be revised.

I think that in the case of bedrock-angular-key we could just eliminate the $onInit trigger.

Add a 404 template, directive, and default 404 error route

Add a simple 404 template, directive, and a default 404 error route. Other routes can use these to handle page errors (eg: those that are based on query params or missing page data).