Skeleton Navigation: Replacing Bootstrap with Aurelia-Materialize bridge components

This post will guide you through a clean installation of aurelia-skeleton-navigation and changing that example app to use Aurelia-Materialize bridge instead of Bootstrap.

We will use the JSPM version in this guide.

  • Get the skeleton navigation project from here: https://github.com/aurelia/skeleton-navigation/releases
  • Extract the skeleton-esnext directory as this is the one using JSPM. You can also use skeleton-typescript but we’ll discuss esnext here.
  • Change your working directory to the directory you’ve just extracted.

Now you need to install the dependencies for npm and jspm. This might take a while.

Issue the following commands on the console:

$ npm install
$ jspm install

Next, remove Bootstrap:

$ jspm uninstall bootstrap

And remove all references to Bootstrap.
In src/main.js remove the first line:

import 'bootstrap';

In src/app.html remove this line:

<require from="bootstrap/css/bootstrap.css"></require>

Change your package.json and add the following override for jspm (as a child of the “jspm” property):

"overrides": {
  "npm:materialize-css@0.98.2": {
    "main": "dist/js/materialize",
    "format": "global",
    "shim": {
      "dist/js/materialize": {
        "deps": [
          "jquery",
          "../css/materialize.css!"
        ]
      }
    }
  }
}

Remember to adjust Materialize’s version to the one you’re installing – this line:

npm:materialize-css@0.98.2

Now install necessary JSPM plugins, Materialize-CSS and the bridge:

$ jspm install css aurelia-materialize-bridge npm:materialize-css aurelia-event-aggregator

Include a reference to Material Design icons in your index.html:

<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">

Change your src/main.js to look like this:

export function configure(aurelia) {
 return aurelia.loader.loadModule('materialize-css').then(() => {
   aurelia.use
   .standardConfiguration()
   .developmentLogging()
   .plugin('aurelia-materialize-bridge', bridge => bridge.useAll() );

   return aurelia.start().then(() => aurelia.setRoot());
 });
}

When you start gulp watch now, you should already see a “materialized” navigation skeleton app. What you will see immediately is a pretty borked layout, so let’s fix this.

Replace your src/nav-bar.html template with the following content:

<template bindable="router">
  <md-navbar fixed="true">
    <a href="#" class="brand-logo left"><span class="flow-text">${router.title}</span></a>
    <ul class="right hide-on-med-and-down">
      <li md-waves repeat.for="row of router.navigation" class="${row.isActive ? 'active' : ''}">
        <a href.bind="row.href">${row.title}</a>
      </li>
    </ul>
  </md-navbar>
</template>

Replace your src/child-router.html template with the following content:

<template>
  <section class="au-animate">
    <h2>${heading}</h2>
    <div class="row">
      <div class="col m2">
        <md-well router.bind="router"></md-well>
      </div>
      <div class="col m10" style="padding: 0">
        <router-view></router-view>
      </div>
    </div>
  </section>
</template>

Replace your src/users.html template with the following content:

<template>
  <require from="blur-image"></require>

  <section class="au-animate">
    <h2>${heading}</h2>
    <div class="row au-stagger">
      <div class="col s6 m3 card-container au-animate" repeat.for="user of users">
        <div class="card">
          <canvas class="header-bg" width="250" height="70" blur-image.bind="image"></canvas>
            <div class="avatar">
              <img src.bind="user.avatar_url" crossorigin ref="image"/>
            </div>
            <div class="content">
              <p class="name">${user.login}</p>
              <p><a target="_blank" class="btn btn-default" href.bind="user.html_url">Contact</a></p>
            </div>
          </div>
      </div>
    </div>
  </section>
</template>

You get the idea here: replace Bootstrap’s css grid with Materialize’s css grid. 🙂

Next, replace the Bootstrap controls of src/welcome.html with Materialize components:

<template>
  <section class="au-animate">
    <h2>${heading}</h2>
    <form role="form" submit.delegate="submit()">
      <md-input md-label="First Name" md-value.bind="firstName"></md-input>
      <md-input md-label="Last Name" md-value.bind="lastName"></md-input>
      <md-card md-title="Full name">
        <p class="help-block">${fullName | upper}</p>
      </md-card>
      <button md-button md-waves="color: light;" type="submit">Submit</button>
    </form>
  </section>
</template>

Now you have a materialized skeleton navigation.

Note: in some cases (it’s not clear to me when this happens), Materialize will not be initialized completely when Aurelia starts. This leads to several global functions or jQuery plugins not being available at the time a component is initialized.

In this case, you would need to wait for Materialize to finish. I’ve created a small brute-force-ish function to deal with this.

function waitForMaterialize() {
  return new Promise((resolve, reject) => {
    let iterations = 0;
    const handler = window.setInterval(() => {
      iterations++;
      let ma = window.Materialize;
      if (
        ma.elementOrParentIsFixed &&
        ma.escapeHash &&
        ma.fadeInImage &&
        ma.guid &&
        ma.scrollFire &&
        ma.showStaggeredList &&
        ma.toast &&
        ma.updateTextFields
      ) {
        console.log(`waited ${iterations} iterations for Materialize to finish loading`);
        window.clearInterval(handler);
        resolve();
      }
    }, 1);
  });
}

Add this function to main.js and call this method from the “configure” function:

export function configure(aurelia) {
 return aurelia.loader.loadModule('materialize-css').then(() => {
   aurelia.use
   .standardConfiguration()
   .developmentLogging()
   .plugin('aurelia-materialize-bridge', bridge => bridge.useAll() );

   return waitForMaterialize().then(() => {
     return aurelia.start().then(() => aurelia.setRoot());
   });
 });
}

Thanks to Steven Boyd for pointing this out!

 

Is Aurelia difficult to use and how can Monterey help?

While Aurelia (as a JavaScript framework) is completely unobtrusive, to the point that experienced Aurelia developers feel like just writing JavaScript with few light touches of Aurelia API, it is relatively difficult to create the development environment with all needed tooling to make the applications run in today’s browsers that do not (yet) support es6 and esn7 versions of JavaScript.

In its first release, Monterey addresses some of the tooling issues, trying to balance the usefulness with “time to market” (Aurelia Tools team is very small and needs to chose the features set for each subsequent release very carefully in order to create a steady stream of useful innovations). So it should not be a surprise that Monterey’s primary focus is on creating new applications – with special accent on using Aurelia-CLI tool. This decision was not made easy particularly because Aurelia-CLI is very new and because it supports only RequireJS module loader, at the time when most existing Aurelia applications are SystemJS module loader based. However, we are very committed to sharing Aurelia core team’s vision so providing full scaffolding based on Aurelia CLI was a good start.

Aurelia-CLI is not frozen in time (it is really just in Alpha stage) so we can all expect support for other module loaders and many features we do not know about – which is another reason why Monterey application scaffolding feature could be viewed as a visual shell on top of Aurelia-CLI.

In order to help developers with existing applications, Monterey offers graphical views of configuration data (NPM Package Manager, JSPM Package Manager), collection of plugins (aka features) that help with the integration of tools that developers use in their daily workflows and the support for creating new applications from the Aurelia application skeletons. In this context, Monterey reaches wider than supporting just the RequireJS module loader, following the same steps Aurelia introduced so far.

The important fact to remember is that Monterey is in its infancy and that we plan to make it as powerful / useful as our resources allow us and in order that our initial users will suggest to us. This is why it is important that you fill in the survey (at the end of the Introducing Monterey blog article) or share your opinions with us as either comments to this blog article or in this Gitter chat room.

Some interesting early comments on Monterey

Just a few days ago, Rob Eisenberg,  Aurelia team leader and architect introduced Monterey to all Aurelia developers in his blog Introducing Monterey. Here are a few comments provided by users who took their time to answer the Monterey survey question “Any other thought you would like to share with us“, starting with critical and ending with very encouraging..

  • This GUI tool is absolutely no use to me in some development contexts, such as Unix/screen/SSH on remote servers.

We are really not sure how to address this user’s view 🙂

  • Skeleton’s seem to be difficult to get working at times. They need to be polished and rock solid.

We would very much like to fix this issue and if would be very helpful to know more about your experience

  • It’s handy, but I would prefer other features.

Such as …?

  • I’m a bit afraid that from outside aurelia community, this tool could prevent some people start using aurelia – “wow – do I need an application to manage my application development – aurelia must be really difficult to use”. I think it’s important to state the purpose of this tool.

A very good advice that we are trying to address immediately – see this article.

  • I would like to run a sequence of commands. E.g. build my project (au run –watch), open chrome, open visual studio for the front-end, open visual studio to my back-end project all with the click of one button.

Thank you for this suggestion which is completely in line with our plans.

  • Love NPM update module! Keep up the good work.

Configuration of existing applications is high on our list of Monterey features

  • Could this be a Lightswitch replacement?

Very interesting observation, given that providing Lightswitch-like tool was one of the ideas that made us thinking to create Monterey 🙂

  • Awesome framework, awesome tooling, its a joy being a developer.

Thank you, your opinion is a great reward for our work.

What is the App launcher?

Monterey is designed to be (user) extensible and that feature is facilitated by the App Launcher Monterey utility (we use the name “features” to reference utilities – see more about features here). You can find a lot more about App Launcher on this  user manual page.

Here are a couple of screenshots illustrating App launcher user interface:

image-1
Image 1: How to integrate the console with Monterey

Aurelia Tools maintains the registry of all “user added features” as shown below (this view is rendered by a click on ‘Share this app launcher’ button on Image 1 above.

image-2
Image 2: registering your new ‘feature’ with Monterey features registry with the intent to share it with other users.

Do not like to read manuals?

If so, we provided an easier method that will keep you from getting lost. Check just this small section of the Monterey user manual for details – here are a couple of screenshots for enticement 🙂

image-1
Image 1: First step into live help system, which provides the brief descriptions of the key user interface elements on Monterey’s main view
image-2
Image 2: Hovering the cursor above ‘App launcher’ tile results with a tooltip that provides the link into the relevant page of the Monterey user manual.

What can Monterey do?

This initial preview is very limited when compared with our plans for Monterey. It is also quite capable already, when used to replace the most likely Aurelia application development workflow which is based on the Sublime-like text editor, console and a browser, starting from skeleton-esnext template. As explained in the related README.md document, you would start by creating the local copy of the that template and issue a series of commands in the console, invoking CLI tools like ‘npm’, jspm’ and ‘gulp’ and using tools like BrowserSync invoked by Gulp scripts.

Monterey does this same job in a lot more user friendly way, via modern GUI as shown next using the skeleton-esnext template. These screenshots and their sequence should be self-explanatory. There are some added comments where that is not true.

image-1
Image 1: First page of the Monterey app creation wizard
image-2
Image 2: Second page of the Monterey app creation wizard
image-3
Image 3: Third page of the Monterey app creation wizard, presenting the project configuration FYI
image-4
Image 4: Monterey shows its “understanding of the project structure by presenting this automatically created build in run workflow
image-5
Image 5: Task manager running stage (executing the ‘npm install’ task).
image-6
Image 6: Application building workflow reached the ‘gulp watch” task and Monterey presents the URL that will invoke the browser and render the app.
image-7
Image 7: Stopping the ‘gulp watch’ task using the Task manager

While the above 7 screenshots illustrate the full “create, build and run” cycle, this is a small fraction of Monterey’s abilities. We have built already some of the tools like NPM and JSPM manager, which can be used in many different scenarios (yet to be implemented, though)

image-8
Image 8: Monterey’s built in NPM package manager
image-9
Image 9: Monterey’s built in JSPM package manager

Subsequent versions will add more package managers and module loaders and the workflows needed to support tasks like

  • upgrade an Aurelia app to the next version of the Aurelia framework
  • convert an aurelia app from using JSPM loader to use Webpack loader
  • analyze compatibility of Aurelia framework modules version with third party modules.

All these projections of the future (see possible future plans for Monterey for more details) are just that – projections.


Did you like this article? Would you like to see any other “brief story” about Monterey? Give us your feedback here or in the comments form below.

First encounter

This post shows how to build and run the Aurelia Contact Manager Tutorial using Monterey as the development tool. The complete process is described with all details in the “Creating new application from Github” chapter of the Monterey user manual – here we will just show the sequence of screenshots, with minimum comments.

image-1
Image 1:  Create new application wizard – define template “type”
image-2
Image 2:  Create new application wizard – define source code location
image-3
Image 3:  Create new application wizard – define location for the new application folder
image-4
Image 4:  New project configuration summary
image-5
Image 5:  Create new application wizard – generated project’s build and run workflow default
image-6
Image 6:  Task manager screenshot showing the ‘au-run –watch’ task running
image-7
Image 7:  Contact manager running (started by a click on Start button on image 6)

Did you like this article? Would you like to see any other “brief story” about Monterey? Give us your feedback here or in the comments form below.

Monterey release notes 9-26-2016

This is the first alpha release, created to measure the interest for this tool in the Aurelia community domain.

Open issues

Introducing Monterey – Aurelia applications development tool

Today, we are ready to share a brand new approach to Aurelia applications development: instead of creating yet another IDE,  Aurelia Tools team’s approach was to “integrate all development tools, including various IDEs, CLI tools, File managers, Developer’s editors, Module loader managers into a single top level “command center” application. We named this application Monterey, hoping that will instill the same bliss as a visit to Monterey’s Fisherman Wharf did so many time to one our our members (Adriatic). At the moment, this name is just a code name and you will be given the chance to chose the real, meaningful name.

circle-of-tools

A lot more abstract definition of Monterey is used in the README.md file from the Monterey GitHub repository:

Monterey is an extensible application that provides a graphical user interface for a collection of tools to simplify the creation, configuration and maintenance of Aurelia applications.

A few other relevant facts:

  • Monterey is written in Aurelia and “packaged” as Electron based desktop application
  • Monterey is available as the “alpha” preview as both Windows and OSX application – get it from here.
  • The Monterey User manual is quite informative, with lots of examples of how to use Monterey.
  • We had very little testing done on the Linux platform, so we would like to hear how you experience using Monterey on Linux

Very important: please stay in touch with Aurelia Tools team – as this tool can only be as good as the sum of all ideas we hope to get from the Aurelia Community. So, please respond to this survey below; as Monterey grows, we will be able to offer other, more specific surveys, allowing you to directly influence what will this tool be.

Installing Monterey
Monterey can be installed on three different platforms: Windows, Mac and Linux. These installers can be downloaded by clicking on the tiles below:

  

main-view


Introducing Aurelia Kendoui Bridge 1.0 Beta

Aurelia-UI-Toolkits team is happy to present the completely re-architected bridge (interface to KendoUI SDK), which addresses a major performance improvement together with more convenient application configuration.

Briefly stated the new bridge supports the concept of user (application developer) installable KendoUI SDK. Instead of supporting just two KendoUI SDK configurations (KendoUI core and KendoUI PRO) this new bridge is completely agnostic to how many KendoUI widgets the application needs to use. This (code-breaking) change allows developers to use the bridge with any module loader – or not to use a module loader at all.

See this (pre)release note for more details about these breaking changes.

As a result, it is perfectly possible to use just a single Aurelia-KendoUI bridge component in your application, and only that component will be loaded at run time. This will result with the significant reduction in application’s load time.

We have added many more samples, rewritten the installation chapter and added the information about building your applications using SystemJS, Webpack and Aurelia-CLI.

Check the beta version of this new bridge catalog application for details on all these new features.