This branch contains the tutorial steps and processes used to implement the start-app shown below:
Above is a snaphot of the Starter-App with a Master-Detail layout: showing a list of users (left) and a user detail view (right).
Also shown is the user experience that will be displayed for smaller device sizes. The responsive layout reveals the menu button that can be used to hide the user list. And the share button can be used to show the Share bottom sheet view.
This Starter app demonstrates how:
- Angular Material
layoutandflexoptions can easily configure HTML containers - Angular Material components
<md-toolbar>,<md-sidenav>,<md-icon>can be quickly used - Custom controllers can use and show
<md-bottomsheet>with HTML templates - Custom controller can easily, programmatically open & close the SideNav component.
- Responsive breakpoints and
$mdMediaare used - Theming can be altered/configured using
$mdThemingProvider
This sample application is purposed as both a learning tool and a skeleton application for a typical AngularJS Material web app: comprised of a Side navigation area and a content area. You can use it to quickly bootstrap your angular webapp projects and dev environment for these projects.
- - -
Here are some generalized steps that may be used to conceptualize the application implementation process:
- Plan your layout and the components you want to use
- Use hard-coded HTML and mock content to make sure the components appear as desired
- Wire components to your application logic
Use the seamless integration possible with Angular directives and controllers
This integration assumes that you have unit tested your app logic
- Add Responsive breakpoints
- Add Theming support
- Confirm ARIA compliance
- Write e2e Tests
It is important to validate your app logic with Angular Material UI components.
###### Wirefame
The illustration below shows how we planned the layout and identified the primary components that will be used in the Starter ap:
Note: that container #2 (above) is a simple
<div>container and not an Angular Material component.
- - -
These tutorial use jspm.io: package manager for SystemJS which is built on top of the dynamic ES6 module loader. This allows developers to load any module format (ES6, CommonJS, AMD, and globals).
These tutorials assume that you have already cloned the repository and executed the following commands:
npm install jspm -gjspm update
You will notice html Tutorials #0 thru #8: these will be used to guide you through the development process. By following these tutorials stages, you will be very quickly introduced to the powerful features of Angular Material.
Each tutorial presents the resulting changes for that stage. It is recommended, however, that you start with the preceding tutorial and manually make the changes requested. The effort you invest to implement these changes will highlight specific concepts at each Tutorial stage.
At each tutorial stage, you should use a web-server to view the that tutorial page. Open the dev console to see any warnings and browser the elements.
- - -
Let's just review our initial setup used in tutorial_0.html:
<head> <link rel='stylesheet' href='http://fonts.googleapis.com/css?family=Roboto:400,700'> <link rel="stylesheet" href="./assets/app.css"/> </head> <body ng-cloak> <!-- No content yet! --> <script src="./jspm_packages/system.js" type="text/javascript"></script> <script src="config.js" type="text/javascript"></script> <script type="text/javascript"> System .import('boot_ngOnly') .catch( console.error.bind(console) ); // make sure any errors print to console </script> </body>With boot.js:
import angular from 'angular'; /** * Manually bootstrap the application when AngularJS and * the application classes have been loaded. */ angular .element( document ) .ready( function() { angular .module( 'starter-app', [ ] ) .run(()=>{ // Use main 'App' module and log startup status console.log(`Running the 'starter-app' ES6 Material-Start Tutorial`); }); let body = document.getElementsByTagName("body")[0]; angular.bootstrap( body, [ 'starter-app' ]); });- - -
@see tutorial_1.html
Here you modified the application [available in tutorial_0.html] to use Angular-Material.
- In the HTML, load the Angular Material CSS stylesheet.
- Load the Angular Material JS library and its dependent libraries
- Configure the app dependency on 'ngMaterial'
<head> <link rel="stylesheet" href="./jspm_packages/github/angular/bower-material@master/angular-material.css"/> </head>Note the NPM and JSPM configurations already installed the Angular Material libraries. Re-installs are easy done using
jspm install angular-material@master.
// Load libraries import angular from 'angular' import 'angular-animate'; import 'angular-aria'; import 'angular-material'; angular .module( 'starter-app', [ 'ngMaterial' ] ) .run(() => { //.... });- - -
@see tutorial_2.html
Here you used the wireframe planning and layout to identify the components and attributes needed.
- Add the
<md-toolbar>,<md-sidenav>,<md-content>containers
Note: that the md-sidenav is the container the Users master list view, and the md-content is the container for the User detail view.
- Add the layout and flex attributes to configure the container layouts and sizing aspects.
- Use
md-locked-opento lock the sidenav open on the left - Use the
md-whiteframe-2dpto add a shadow the the sidenav
<body layout="column"> <!-- Container #1 (see wireframe) --> <md-toolbar layout="row" > <div class="md-toolbar-tools"> <h1>Angular Material - Starter App</h1> </div> </md-toolbar> <!-- Container #2 --> <div flex layout="row"> <!-- Container #3 --> <md-sidenav md-is-locked-open="true" class="md-whiteframe-2dp"></md-sidenav> <!-- Container #4 --> <md-content flex id="content"></md-content> </div> </body>- - -
@see tutorial_3.html
Here you will use hard-coded elements to confirm rendering and layout of the container child elements and Angular Material components.
<body layout="column"> <md-sidenav md-is-locked-open="true" class="md-whiteframe-2dp"> <md-list> <!-- List item #1 --> <md-item > <md-button> <md-icon md-svg-src="./assets/svg/avatar-1.svg" class="avatar"></md-icon> Lia Luogo </md-button> </md-item> <!-- List item #2 --> <md-item > <md-button> <md-icon md-svg-src="./assets/svg/avatar-4.svg" class="avatar"></md-icon> Lawrence Ray </md-button> </md-item> </md-list> </md-sidenav> <md-content flex id="content"> <!-- User details sample --> <md-icon md-svg-src="./assets/svg/avatar-1.svg" class="avatar"></md-icon> <h2>Lia Luogo</h2> <p> I love cheese... </p> </md-content> </body>- - -
@see tutorial_4.html
Here you integrate your custom, application logic.
- Import and add the
/src/App.jsmodule as a dependency App.jsinternally loads the Users moduleUsers.jsdefines your data services, models, and controllers
// Load libraries import angular from 'angular'; import 'angular-animate'; import 'angular-aria'; import 'angular-material'; import App from '../App'; export default angular.module( "starter-app", [ 'ngMaterial', App.name ] )in Users.js
// Load the custom app ES6 modules import UsersController from 'users/UsersController' import UsersService from 'users/UsersDataservice' // Define the Angular 'users' module export default angular .module( "users", [] ) .service("usersService" , UsersService ) .controller("UsersController" , UsersController );- - -
@see tutorial_5.html
Here you will replace the hardcoded HTML with dynamic markup using Angular directives (eg ng-repeat) and {{ }} interpolation markup.
- Use dynamic HTML that will be compiled and rendered by Angular
- Register a custom icon set of 'user' avatars for the user list
- Register menu and share icon urls for the md-buttons
<!-- Wireframe Container #2 --> <div flex layout="row"> <!-- Wireframe Container #3 --> <md-sidenav md-is-locked-open="true" class="md-whiteframe-2dp"> <md-list> <md-list-item ng-repeat="it in ul.users"> <md-button ng-click="ul.selectUser(it)" ng-class="{'selected' : it === ul.selected }"> <md-icon md-svg-icon="{{it.avatar}}" class="avatar"></md-icon> {{it.name}} </md-button> </md-list-item> </md-list> </md-sidenav> <!-- Wireframe Container #4 --> <md-content flex id="content"> <md-icon md-svg-icon="{{ul.selected.avatar}}" class="avatar"></md-icon> <h2>{{ul.selected.name}}</h2> <p>{{ul.selected.content}}</p> <md-button class="action" md-no-ink> <md-icon md-svg-icon="share" ></md-icon> </md-button> </md-content> </div>in src/App.js
// Load libraries import angular from 'angular' import Users from 'src/users/Users' export default angular .module( "UsersApp", [ 'ngMaterial', Users.name ] ) .config(function ($mdIconProvider) { // Register the user `avatar` icons $mdIconProvider .defaultIconSet("./assets/svg/avatars.svg", 128) .icon("menu", "./assets/svg/menu.svg", 24) .icon("share", "./assets/svg/share.svg", 24); });- - -
@see tutorial_6.html
Here you will add responsive breakpoints so the application layout will adapt to different device display sizes.
- Lock the Users list open if device display is wider than > 600px; hide otherwise.
- Hide the Toolbar menu icon button if the Users list is open.
- Add
clicksupport for the menu and share buttons. - Register icons for bottomsheet
<body> <!-- Wireframe Container #1 --> <md-toolbar layout="row"> <md-button class="menu" hide-gt-sm ng-click="ul.toggleList()"></md-button> </md-toolbar> <!-- Wireframe Container #2 --> <div flex layout="row"> <!-- Wireframe Container #3 --> <md-sidenav md-is-locked-open="$media('gt-sm')" md-component-id="left"> </md-sidenav> <!-- Wireframe Container #4 --> <md-content flex id="content"> <md-button class="share" md-no-ink ng-click="ul.share($event)"></md-button> </md-content> </div> </body>in src/App.js register the share icons displayed in the User Detail view bottomsheet:
// Load libraries import angular from 'angular' import Users from 'src/users/Users' export default angular .module( "UsersApp", [ 'ngMaterial', Users.name ] ) .config(function ($mdIconProvider) { $mdIconProvider .defaultIconSet("./assets/svg/avatars.svg", 128) .icon("menu", "./assets/svg/menu.svg", 24) .icon("share", "./assets/svg/share.svg", 24) .icon("google_plus", "./assets/svg/google_plus.svg", 512) .icon("hangouts", "./assets/svg/hangouts.svg", 512) .icon("twitter", "./assets/svg/twitter.svg", 512) .icon("phone", "./assets/svg/phone.svg", 512); });- - -
@see tutorial_7.html
Here you will configure a different, darker theme to be used.
- Use
$mdThemingProviderto configure a different theme using primary colors from the brown color palette and accent colors from the red color palette.
// Load libraries import angular from 'angular' import Users from 'src/users/Users' export default angular .module( "UsersApp", [ 'ngMaterial', Users.name ] ) .config(function ($mdIconProvider, $mdThemingProvider) { $mdIconProvider .defaultIconSet("./assets/svg/avatars.svg", 128) .icon("menu", "./assets/svg/menu.svg", 24) .icon("share", "./assets/svg/share.svg", 24) .icon("google_plus", "./assets/svg/google_plus.svg", 512) .icon("hangouts", "./assets/svg/hangouts.svg", 512) .icon("twitter", "./assets/svg/twitter.svg", 512) .icon("phone", "./assets/svg/phone.svg", 512); $mdThemingProvider.theme('default') .primaryPalette('brown') .accentPalette('red'); });- - -
@see tutorial_8.html
Here you will fix any ARIA warnings that Angular Material may display in the Dev console.
- Insert
aria-labelattributes for mdButton components that do not have labels.
<body> <!-- Wireframe Container #1 --> <md-toolbar layout="row"> <md-button class="menu" aria-label="Show User List"></md-button> </md-toolbar> <!-- Wireframe Container #2 --> <div flex layout="row"> <!-- Wireframe Container #3 --> <md-sidenav>...</md-sidenav> <!-- Wireframe Container #4 --> <md-content flex id="content"> <md-button class="share" aria-label="Share"></md-button> </md-content> </div> </body>With only eight (8) Tutorial Steps and a few minutes of work, we have quickly created a functional Angular Material application that is beautiful, responsive, theme'ed, accessible, and easily maintained.