Julien Enselme personal blog - Aurelia

Aurelia Store and Immer

2020-08-09T00:00:00+02:00

I spoke last year of Aurelia store in this article At the time, it wasn't possible to combine Aurelia Store and Immer. The root cause of the issue was fixed in the latest version of Immer (7.0), so we can now combine both.

Let's study how to do this:

Install immer with npm install --save immer@^7.0.7 or yarn add immer@^7.0.7
Because we need Aurelia to update the state when it's used in component to add some observers, we must disable immer's auto-freezing. You can do this in main.js or app.js with:
```
import {setAutoFreeze} from 'immer';
// This is required to allow Aurelia to add its observer on objects in the state.
setAutoFreeze(false);
```
Update you actions to use produce. This will allow you to modify the state directly without mutating it. This way, the history features of the store will be preserved. For a simple example:
```
// Before.
export function selectBackend(state: State, selectedBackend: SelectableBackend) {
    const newState = {...state};
    newState.selectedBackend = selectedBackend;
    return newState;
}

// After
export const selectBackend = produce((state: State, selectedBackend: SelectableBackend) => {
    state.selectedBackend = selectedBackend;
});
```
Thanks to immer, you don't have to copy the state explicitly, immer will create a new state based on your modification automatically. The produce function takes a function that will receive the draft of the state you can modify as first argument and all other arguments passed to you action as extra arguments. So the function you need to pass to produce takes the same arguments as a standard action. You still need to be aware and pay attention to some details:
- All the objects in the store are changed so immer can track the changes without modifying the original objects. This means that this won't work:
```
export deleteArticle = produce((state, article) => {
    // Will return -1 because article is not in the articles array, it's proxied version is.
    const indexOfArticleToDelete = state.articles.indexOf(article);
});
```
- Only the state will be a "draft" (to use immer terminology) and can be modified directly. If you were to modify other argument, you would mutate them. And if they are in the store, you would update them the store as well. So this won't work as expected and will mutate the object:
```
export markAsRead = produce((state, article) => {
   article.isRead = true;
});
```
For both these issues, you need to first find the proper object in the draft state and apply the modification to it. You can view an example here.

If you want more detail, you can check this commit of one of my project when I updated my actions to use immer.

As noted by Vildan Softic (the creator of Aurelia Store), you can organize how you update the state differently to update the state correctly while keeping things clear without requiring immer. You can see an example here. Many thanks to him for pointing that out and giving me some pointer to correctly test Aurelia Store with Immer.

So while I think it's really nice to be able to use Immer, whether to use it or not highly depends on your programming style and on whether you can afford adding yet another library to your project (immer is about 15kB minified which is tiny, but it adds up with the rest).

Switching from Aurelia CLI to Webpack

2020-07-04T00:00:00+02:00

Recently I decided to change the build system I use on my main Aurelia project. I changed in April 2016 from JSPM to Webpack (JSPM was really not awesome at the time, I can't say for now), again in August 2016 from Webpack to the CLI and now I am switching back to webpack. At the time, I moved away from webpack because of a big bundle of 1.3 MB that was always loaded. I didn't manage to split it correctly using Webpack while Aurelia CLI gave me the flexibility I needed to load less JS by default. So why did I decided to switch again?

To get smaller bundles: since Webpack is not used just by Aurelia it supports many optimization to reduce the size of your bundles (like tree shaking to remove unused code).
To simplify assets management: Webpack can do it directly. I used to rely on gulp-rev to correctly version them. But it required manual work to get it working. Now I can just rely on Webpack.
Currently, Server Side Rendering with Aurelia is only supported by Webpack. This could be a big plus for my site where I have public facing pages that would gain from being correctly indexed by Google.
Hot Module Reload to speed development (alone this wouldn't have been enough for a switch, but it's nice).

Since my last try, Webpack and Aurelia's support for Webpack both significantly improved so I guessed this was worth a try to help me reduce my bundles (that the main reason I tried to be honest, the other ones are more bonuses).

Here's how I made the switch. I:

Copied required dependencies from a new project created with the CLI (it was of course configured to use webpack, which is now the default option for a bundler). That included of course webpack and webpack-dev-server.
Changed .css into .scss in HTML files so styles are correctly loaded by webpack on my require lines.
Used PLATFORM.moduleName where necessary. This is required to bridge Aurelia with Webpack. See the documentation. This mainly implied to:
1. Add PLATFORM.moduleName to link moduleId to their module my route configurations.
2. Add PLATFORM.moduleName in plugin definition.
Updated my storage service so it uses a prefix for my keys. This was required because webpack use localStorage to store things and I looped on all the keys which resulted in errors in my code.
Updated aurelia.json to match one provided by the webpack skeleton.
Added a webpack configuration. It's based on the one from the skeleton. I had to change (to match what I do in my project):
1. Where I get sources from src to app.
2. The name of the static folder from public to assets.
3. Where I send the static files when the app is built.

Import all my images and assets directly in JS files so Webpack would correctly copy and version them. This way, in JS I can use the imported name to point to the assets and let Webpack handle the versioning. I had a bunch of gulp tasks to do this before and it was a bit cumbersome. See this page and this commit for more details on how to manage assets with webpack. To help me generate the import lines and the mapping objects I often needed, I relied on this small Python script:

files_list = """COPY HERE THE RESULT OF ``ls -d PATH``""".strip().split()

import_name_to_file_name = {}
for elt in files_list:
    file = elt.split("/")[-1]
    file = file[:-4]
    components = file.split('-')
    components = [c.title() if index > 0 else c for index, c in enumerate(components)]
    import_name = ''.join(components)
    import_name_to_file_name[file] = import_name
    print(f'import {import_name} from "../../{elt}"')
print('{')
for key, val in import_name_to_file_name.items():
    print(f'"{key}": {val},')
print('}')

Added index.ejs as a base index file for webpack and adapt it to suit my needs.
Updated my jest configuration so I could run my tests again. I even went a bit further and stopped using Aurelia CLI to use Jest CLI directly. This allowed me to have access to all the options provided by Jest more easily. To do this, aside from updating the configuration to support Webpack, I had to make sure the environment variable BABEL_TARGET was correctly set to node. Without it, Babel doesn't target the proper runtime and it doesn't work. Since I already used nps to launch some scripts, this wasn't an issue. I defined my tasks to run tests like this:
```
test: {
    default: crossEnv("BABEL_TARGET=node jest"),
    coverage: crossEnv("BABEL_TARGET=node jest --coverage"),
    watch: crossEnv("BABEL_TARGET=node jest --watch"),
},
```
See this commit for more details.
Used a webpack plugin to help me generate my ServiceWorker to preload all bundles and assets: serviceworker-webpack-plugin. The details are here.

I had one big issue during the switch: compose. I use this to dynamically select a view model to display in an element like this: <compose view-model="./${type}" model.one-way="popupModel"></compose> (where type is passed to my component and corresponds to JS and HTML files to load on the view (for instance if type is transition Aurelia will load and inject the content of transition.js and transition.html). Sadly, Webpack doesn't know what to do with this out of the box. Luckily, I found a thread on the forum that gave the solution: declare all you need to use with PLATFORM.moduleName in the component definition. See this commit for more details (or the thread on the forum).

I'd also like to point out that the configuration generated by the CLI can optimize for two major use cases:

Usage over HTTP 1.1: you get fewer but bigger bundles.
Usage over HTTP 2: you get a lot of small bundles (around 50 in my case).

Since my site is only compatible with modern browser and supports HTTP 2, I decided to optimize for that. One important point to know is that by default, all bundles will be loaded by the index.html even those you won't need yet. To prevent this (and put some pages in dedicated bundles), you can specify a chunk name to PLATFORM.moduleName like this: PLATFORM.moduleName('myRouteModule', 'chunkName'). This way, all that's required for myRouteModule to run will only be loaded when the route becomes first active. That's a good thing to know to avoid loading to much JS from the start if your app is big. See this page to learn more about this.

Results:

Bundle sizes before webpack:
- Total first party JS loaded on the whole site: 1.54 MB
- Total first party JS on the home page: 1.02 MB
Bundle sizes with webpack:
- Total first party JS loaded on the whole site: 1.26 MB
- Total first party JS on the home page: 618 kB

So that's a gain of about a 400 kB. Not bad.

To conclude, I am satisfied with the switch: I reached my goal and can take advantages of webpack which is nice! I'd also like to point out that the transition went way smother that I expected: I got it working in a couple of hours and then had to spend some time with various issues (like assets management or the issue with compose) and to tailor the build to my needs which are not standard. All in all, I think I made the switch in less than 30 hours. Not bad. If your needs are less complex than mine, it should be way less than this. I guess both Webpack and Aurelia matured a lot since the last time I made a build system switch. That's a very good thing!

Writing a PWA with Aurelia

2019-09-01T00:00:00+02:00

Contents

PWA basics
The App
- manifest.json
- ServiceWorker
Conclusion
Resources
History

I feel like Progressive Web Application (PWA for short) are a more and more popular way to build mobile apps. That's understandable since you can use the same technology you use to build a SPA to build one! So you stay in known grounds, can use your usual web browser to develop and test the app. And, unlike hybrid apps, you also enhance your standard SPA! In this article, I'll explain how I build a PWA named aurss with the Aurelia framework. I'll start by explaining what PWAs are and some specific tech you must use to make them work. Then I'll explain how to build one with Aurelia.

PWA basics

Simply put, PWAs are "installed" web pages: when you browse on a website that is a PWA, you will be prompted to install it. If you accept, you will see the icon of the APP on your home screen (like any other app) and if you press this icon, the PWA will launch in full screen mode just like a native app. But you didn't go to the app store to install it.

As a developer, building a PWA means:

Your users don't have to install it: they can use the app directly on the website without installing anything and you'll still be able to provide them advanced features like caching.
You will have more control on when you can update it: no need to submit it to the app store and wait for validation. Just push files to you server. The update will occur the next time your users reopen the app.
You are not bound by the rules of any app stores.
The app will work on any device with a recent browser. Chrome has the best support for PWAs right now, Firefox is quite good but Safari support can be an issue (even if it's getting better, see this article for instance).
The app can be progressively enhanced (eg by adding better offline support or better caching).
You show notifications the user with the Notification API and the Push API.
You can access some native features (like the camera or the microphone).

Here are the basic components needed to make a PWA:

manifest.json: it's a JSON file describing how the app must be displayed and installed. You'll use it to specify the name, icon, orientation and some display properties of your app. See here for more details. It is required to make your app a PWA.
ServiceWorker (SW for short): it behaves like a proxy server between your app and the network. It will keep working even when the tab is closed. So it will allow you to:
- Have caching and offline support.
- Sync things in the background.
- Subscribe to notifications of the Push API and display them to users.
Please note that:
- It only works over HTTPS (except for localhost).
- It cannot access the DOM.
- It may apply to all or only part of the pages.
- It must be registered to have an effect.
- It will only get updated if its content changed and after the tab is closed and reopen (unless you use the dev tools and force it to reload on change).
See here for more. It is required to make your app a PWA.
indexDB: where you put data to exchange with the SW (SW cannot access localStorage). See here for more information.
Many other APIs I'll just list here so you know what you can do:
- Notification API to display notification to the user.
- Push API to receive messages from a server.
- Many more: geolocation, camera access, …

The App

Now that we've seen what the basic components are, let's see how to do this with Aurelia.

In a nutshell, you want to build a normal app while paying attention to some details, relating with the SW: it will rely on indexDB for storage, on the fetch API for network (luckily that's what the Aurelia HTTP client is using), all its APIs are promise based and it will be reinstalled only when it changes.

I assume you are familiar with Aurelia so I won't explain Aurelia specific things (since they don't exist, I just build a standard app using the framework) and focus on PWA stuff. Anything I explain here is applicable with a basic app created by the CLI (if possible use webpack since this article will be easier to follow if you do).

So to make your app a PWA, you will have to:

Add the manifest.json.
Add the service worker.
Check with lighthouse that the app is installable.

You can then add other capabilities if needed.

manifest.json

Once you've build the app, you can add the manifest.json file. To do so add in your index.html or index.ejs:

<link rel="manifest" href="/manifest.json">

Then in the static/ folder (if you are not using webpack as configured by aurelia-cli, you may need to adapt this, the goal is to have this file in the root of the build files next to the index.html file), you can create the manifest.json file. Below is an example, you can adapt it to your needs. It also has more properties, see the documentation to view all its possibilities.

{
    "name": "aurss – RSS reader",
    "short_name": "aurss",
    "start_url": "/",
    "scope": ".",
    "display": "standalone",
    "background_color": "#FFF",
    "theme_color": "#493174",
    "description": "RSS reader for TTRSS",
    "dir": "ltr",
    "lang": "en-US",
    "orientation": "portrait-primary",
    "icons": [{
        "src": "/icons/aurss.96x96.png",
        "type": "image/png",
        "sizes": "96x96"
    }, {
        "src": "/icons/aurss.512x512.png",
        "type": "image/png",
        "sizes": "512x512"
    }]
}

ServiceWorker

Then, include the service worker:

Create a file named sw.js in your src folder. Leave it empty for now.

if ('serviceWorker' in navigator) {
    runtime.register()
        .then((registration) => this.logger.info('Service worker is registered', registration))
        .catch((registrationError) => this.logger.error(
            'Service worker failed to register', registrationError,
        ));
} else {
    this.logger.info('Service worker is not available in this browser.');
}

Make sure it will be copied when you build the application next to the index.html. For instance, with webpack, you can use this plugin (which will also be handy later for caching so I recommend that you use it or something similar).

Note

Even you are using TypeScript, I suggest you rely on plain JavaScript for the SW file. It will be much easier to write and you won't have to worry about transpilation.

Tip

If you are using Chrome, the Application tab of the dev tools is really useful. It will show you information about the manifest file, the service worker and the used storage.

Tip

ES6 imports won't work with SW, you must use something like importScripts('/src/js/idb.js'); to import things.

Now the SW is bootstrapped, we can start to use it to:

Cache the shell of the app (ie the files it needs to work) and provide offline support. This is done once the SW is installed, so when the installed event has been fired (self represent the SW instance):

// Name of our static cache.
const staticCachePrefix = 'static';
// Update this each time you app shell changes.
// This way, the SW will have changed and get reinstalled
// allowing for the new files to be cached.
const VERSION = '1.0.0';
const staticCacheName = `${staticCachePrefix}-${VERSION}`;

self.addEventListener('install', (event) => {
    log('Installing SW version:', VERSION);
    // waitUntil is there to make the sure SW is neither paused nor stopped
    // while we expect it to do some work until the promise we passed to it completes.
    // See: https://stackoverflow.com/a/37906330
    event.waitUntil(
        caches.open(staticCacheName)
            .then(cache => {
                console.log('Caching app shell');
                // serviceWorkerOption comes from serviceworker-webpack-plugin.
                // Adapt if needed.
                cache.addAll(serviceWorkerOption.assets);
            }),
    );
});

You can then use in your app.js file, in the constructor, something like the code below to display notification to the user about online/offline status:

this.onOffline = () => this.store.dispatch(isOffline.name);
this.onOnline = () => this.store.dispatch(isOnline.name);

if (!navigator.onLine) {
    this.store.dispatch(isOffline.name);
} else {
    this.store.dispatch(isOnline.name);
}

window.addEventListener('offline', this.onOffline);
window.addEventListener('online', this.onOnline);

Catch network requests, for instance to implement dynamic caching.

self.addEventListener('fetch', (event) => {
    // Let the browser do its default thing
    // for non-GET requests.
    if (event.request.method !== 'GET') {
        return;
    }

    event.respondWith(
        caches.match(event.request)
            .then((response) => {
                return response || fetch(event.request);
            }),
    );
});

When offline, you can store data in indexDB to send it as soon as the browser gets online again. To do this, you must listen to the sync event in the SW. You can take inspiration from this code for the SW part and from these utility functions (see a usage here) to achieve this.

Note

There are many caching strategies: with network fallback, cache only, network only, network with cache fallback, cache then network. I won't detail them here. Search on the internet if needed.

Note

Don't forget to clean the cache from time to time. This can be done with:

self.addEventListener('activate', (event) => {
    console.log('Cleaning old cache shell');
    event.waitUntil(
        caches.keys()
            .then((keylist) => Promise.all(
                keylist
                    .filter((key) => key !== staticCacheName && key.startsWith(staticCachePrefix))
                    .map((key) => caches.delete(key))
            )),
    );
});

Finally, you should test you app with lighthouse to check it actually is a PWA. The tool will also check for performance which is a good thing. In the Chrome dev tools, go to the Audit tab, verify that Progressive Web App is checked under the audit section and run the audit. The report should tell you that you have indeed created a PWA (and if not, what you are missing).

Conclusion

To sum up:

PWAs are not tied to any framework. You can make a PWA without one or add PWA capabilities to a SPA written with any framework.
They are quite fast to develop and allow for good code re-use because you are not making an app distinct from you main web site.
You don't have to learn many new technologies, most of the things you will do will be standard we development.
You can progressively enhance an app with PWA capabilities.
Pay attention to what they support and what they don't before starting and to iOS support.

Resources

My test application: aurss It's MIT licensed so you can re-use it. Don't hesitate to ask me questions in the comment or in Gitlab.
A course I took (I highly recommand it)

History

2022-09-11: update link to manifest.json in MDN to point to the documentation about PWA and not about Web Extensions. Thank Colin O.

Some thoughts on Aurelia Store

2019-08-24T00:00:00+02:00

On my spare time, I am developing a board game that uses the Aurelia framework. I currently manage the state in a service without any dedicated state management solutions (like RxJS, Aurelia store, Redux, …). And I feel I am reaching to the limit of what I can do with it and feel the need for a dedicated solution. So I decided to give aurelia-store the official plugin for state management for the framework. I did so in at test project: aurss a small app to list rss feeds.

First, let me explain a bit why we would need a store: in Aurelia, you can use services (ie instances of a object) that are injected into your components. You can use them for actions (eg interaction with an external API) and to store data. If you app is big, you will end up with many services. You'll have to keep them all in sync (maybe with observers or the event aggregator) and make sure your component are correctly updated.

It turns out this approach can be quite tricky and that's why solutions like Redux (from the React world) or VueX for Vue.js and of course Aurelia store have emerged: to help you manage the state in a single place so you don't have to do the hard work of keeping everything in sync. Instead of having multiple services, you have one store, you rely on functions to change its state and the store "notifies" your components that something changed and that they must be updated. It also comes with some nice features like easy persistence and recovery from local storage and time travel.

Aurelia store more specifically is a plugin for Aurelia to help you use this pattern with the Aurelia framework. It's based on RxJS a popular library for event programming. The idea of RxJS is register actions to do when a given event occurs as specified by the observer pattern, ie do something like this:

const observable = fromEvent(document, 'click');
observable.subscribe(() => console.log('clicked!'));
observable.subscribe((event) => sendEventToAnalytics(event));

I'll let you see the doc of RxJS to learn more about that.

What's very interesting about Aurelia store is that while based on RxJS (and its full power), it remains easy to use at first: you don't need to know RxJS to start and don't need much knowledge to do even quite advanced things. Please read the introduction to Aurelia store to have a more detailed explanation about why the plugin exists and its relationship with RxJS.

Let's see briefly how to use it (I assume you are already familiar with Aurelia, if not, the official documentation will give you more details on how to integrate it in your app):

In your main.js file, you must enable the plugin and define an initial state:
```
aurelia.use.plugin('aurelia-store', { players: [] });
```

Inject the Store in your components:

import { inject } from 'aurelia-framework';
import { Store } from 'aurelia-store';

@inject(Store)
class MyComponent { …

Listen to events with:

// `this.state` will receive a new value each time the state is updated.
// This way, the component will re-render.
this.subscription = this.store.state.subscribe((state) => this.state);

Dispatch actions to update the state:

function addPlayer(state, player) {
    // Don't mutate the state directly, create a new one. See the doc for why.
    const newState = {..state};
    newState.players = [...newState.players];
    newState.players.push(player);
    return newState;
}
this.store.registerAction(addPlayer.name, addPlayer);
setInterval(() => this.store.dispatch(addPlayer, "Player " + parseInt(Math.random() * 100, 10), 10000);

Tip

Don't forget to dispose of subscription with this.subscription.unsubscribe. See the doc.

I must say the experience of using Aurelia store is very pleasant: the plugin is easy to integrate, it works well, it's not hard to understand, it seems to play nice with RxJS if you need some advance features (for instance to register to updates to part of the state or to get only the first change).

If I compare this to Redux which is the other state management solution I used, I think that using directly functions when we dispatch actions is a very good idea: instead of having actions and reducers like in Redux, you only have one concept to achieve the same result. It's also way easier to get started and is easier to understand (each time I have to touch a Redux code base, I have to re-understand how it works and what the link between actions and reducers is).

The fact that the plugin hides the complexity of RxJS is also a really good thing. By comparison with Angular (from the tutorial I made at least) where RxJS is fully exposed, it really simplifies the development and startup.

So I am really pleased with the plugin, what I can do with it and the overall developer experience it provides. There are some small gotchas though:

Don't forget to register your actions. You may forget at first. But the store will provide an helpful error message if you forget so it's not the end of the world.
Pay attention to async actions: unlike other solutions, the Aurelia store allows you to do something like this: await this.store.dispatch(costlyApiCall). If you do this, your app will freeze until the API call is done which is not what you want (and may not be noticeable locally if your API is on your machine). So for expensive async operations, split the actions in two: one to do the call and one to update the store when the call is done. To view an example of this, look at fetchArticles and receivedArticles from my test app. But if you know your async actions will resolve fast (querying IndexDB for instance), this shouldn't be an issue.
Immer.js (useful to ease the writing of state mutation) doesn't work with the plugin out of the box yet (see this discussion which also gives a possible solution and this issue). Maybe alternative solutions work (like immutable.js) but I haven't tried them. Update of 2020-08-09: it is now possible, see this update.

Issues while writing tests for a component using i18n

2019-08-04T00:00:00+02:00

Some time ago, I wanted to add some tests (behavior and render) on an Aurelia component that uses the i18n plugin and more precisely the df attribute in the view to display a localized date.

Since it was a while back (I wanted to write it earlier but couldn't), my memory may not completely accurate. I hope it can help you nonetheless. If you have questions, please post a comment.

My component is pretty basic: it takes some bindable as inputs, define a time format to format the date correctly, has 3 methods to add custom behavior and that's it. You can view the model here and the view here.

Also note I am using TypeScript, Webpack and Jest. If you use different tooling, you may need to adapt the example a bit.

In my test, I setup my component like this:

component = StageComponent.withResources(PLATFORM.moduleName('../../src/resources/elements/aurss-article'))
    .inView(`
    <aurss-article
        value.bind="article"
        mark-article-as-read.bind="markArticleAsRead"
        mark-article-as-unread.bind="markArticleAsUnread"
        open-article.bind="openArticle"
    ></aurss-article>
    `).boundTo(viewModel);

await component.create(bootstrap);  // bootstrap comes from aurelia-bootstrapper

I got this error when running the tests: Error: No ValueConverter named "df" was found!. I then tried to register the component with:

component = StageComponent.withResources([
    PLATFORM.moduleName('../../src/resources/elements/aurss-article'),
    PLATFORM.moduleName('aurelia-i18n'),
])

But all I got was: Error: Error invoking RelativeTime. Check the inner error for details..

After reading tests in the plugin repo and this article (which solves a similar problem but the proposed solution didn't work for me), here is how I nailed it:

I created an test/helpers.ts file with the code below. Its purpose is to bootstrap the i18n plugin (it resembles what you do in main.ts):

import {Aurelia, PLATFORM} from 'aurelia-framework';
import {Backend} from 'aurelia-i18n';

export const prepareI18nComponent = (component) => {
    component.bootstrap((aurelia: Aurelia) => {
        return aurelia.use.standardConfiguration()
            .plugin(PLATFORM.moduleName('aurelia-i18n'), (instance) => {
                const aliases = ['t', 'i18n'];

                // register backend plugin
                instance.i18next.use(Backend.with(aurelia.loader));
                const config = {
                    resources: {
                        en: {
                            translation: {
                                hello: undefined,
                            },
                        },
                    },
                    skipTranslationOnMissingKey: true,
                };

                return instance.setup(Object.assign({
                    attributes: aliases,
                    backend: {
                        loadPath: './locales/{{lng}}/{{ns}}.json',
                    },
                    debug: false,
                    defaultNS: 'translation',
                    fallbackLng: 'en',
                    interpolation: {
                        prefix: '{{',
                        suffix: '}}',
                    },
                    lng: 'en',
                }, config));
            });
    });
};

In the beforeEach function, I now setup the component like this:

beforeEach(async (done) => {
    viewModel = {
        article: createArticle(),
        markArticleAsRead: jest.fn(),
        markArticleAsUnread: jest.fn(),
        openArticle: jest.fn(),
    };

    component = StageComponent.withResources(PLATFORM.moduleName('../../src/resources/elements/aurss-article'))
        .inView(`
        <aurss-article
            value.bind="article"
            mark-article-as-read.bind="markArticleAsRead"
            mark-article-as-unread.bind="markArticleAsUnread"
            open-article.bind="openArticle"
        ></aurss-article>
        `).boundTo(viewModel);

    prepareI18nComponent(component);  // Bootstrap i18n

    await component.create(bootstrap);

    done();
});

I also configured jest to load a file name test/jest-pretest.ts before it executes the tests suite by adding, under the jest section of my package.json file:

"setupFiles": [
    "<rootDir>/test/jest-pretest.ts",
    "jest-localstorage-mock"
]

This file contains:

import {Options} from 'aurelia-loader-nodejs';
import {globalize} from 'aurelia-pal-nodejs';
import 'aurelia-polyfills';
import * as IntlPolyfill from 'intl';
import * as path from 'path';

Options.relativeToDir = path.join(__dirname, 'unit');
globalize();

(global as any).navigator = {};

global.Intl.NumberFormat   = IntlPolyfill.NumberFormat;
global.Intl.DateTimeFormat = IntlPolyfill.DateTimeFormat;
(window as any).Intl = global.Intl;

(window as any).Intl.NumberFormat   = IntlPolyfill.NumberFormat;
(window as any).Intl.DateTimeFormat = IntlPolyfill.DateTimeFormat;

It is meant to be sure the Intl API used by the plugin is correctly defined during the tests.

That's it! You can also take a look at the full project code in gitlab if you need more details: https://gitlab.com/Jenselme/aurss

Extract translations from your Aurelia app

2019-08-03T00:00:00+02:00

If you use Aurelia with the i18n plugin, you will have to maintain JSON files that will map a translation key to an actual translation. Manually editing the file to add/remove keys can be tedious.

Luckily, keys can be extracted automatically thanks to i18next-scanner. It can extract translation keys from JavaScript, TypeScript and HTML files.

To do this:

Install i18next-scanner with npm install --save-dev i18next-scanner or yarn add -D i18next-scanner.
Add the code below in i18next-scanner.config.js file at the root of your project.
Run ./node_modules/.bin/i18next-scanner src/**/*.{js,ts,html} to extract the translations. They will be under src/locales/{{lng}}/translation.json. Keys to be translated will have the value __STRING_NOT_TRANSLATED__.

The extraction supports the following patterns:

In code files: it will extract keys directly from i18next (usage like i18next.t('my-key')) and from the injected I18N service (ie if you use it like this: this.i18n.tr('my-key')).
In HMTL files:
- With the following attributes: data-i18n, data-t, t, i18n (usage like this <p t='my-key'></p>).
- With the following behaviors: t (usage ${ 'myKey' | t } and ${ 'myKey' & t } – the whitespace is not important).

If this doesn't exactly work for your use cases, please adapt the code below and ask a question in the comments if needed.

 1 const fs = require('fs');
 2 const path = require('path');
 3 const typescript = require("typescript");
 4 
 5 module.exports = {
 6     input: [
 7         'src/**/*.{ts}',
 8     ],
 9     output: './',
10     options: {
11         debug: true,
12         func: {
13             list: ['i18next.t', 'i18n.t', 'this.i18n.tr'],
14             extensions: ['.js'],
15         },
16         lngs: ['en', 'fr'],
17         ns: [
18             'translation',
19         ],
20         defaultLng: 'en',
21         defaultNs: 'translation',
22         defaultValue: '__STRING_NOT_TRANSLATED__',
23         resource: {
24             loadPath: 'src/locales/{{lng}}/{{ns}}.json',
25             savePath: 'src/locales/{{lng}}/{{ns}}.json',
26             jsonIndent: 4,
27             lineEnding: '\n'
28         },
29         nsSeparator: false, // namespace separator
30         keySeparator: false, // key separator
31         interpolation: {
32             prefix: '{{',
33             suffix: '}}'
34         },
35         removeUnusedKeys: true,
36     },
37 
38     transform: function customTransform(file, enc, done) {
39         const {ext} = path.parse(file.path);
40         const content = fs.readFileSync(file.path, enc);
41 
42         if (ext === '.ts') {
43             const {outputText} = typescript.transpileModule(content.toString(), {
44                 compilerOptions: {
45                     target: 'es2018',
46                 },
47                 fileName: path.basename(file.path),
48             });
49 
50             this.parser.parseFuncFromString(outputText, {list: ['i18next.t', 'i18next.tr', 'this.i18n.tr']});
51         } else if (ext === '.html') {
52             this.parser
53                 .parseAttrFromString(content, {list: ['data-i18n', 'data-t', 't', 'i18n'] });
54 
55             // We extra behaviours `${ 'myKey' | t }` and `${ 'myKey' & t }` from the file.
56             const extractBehaviours = /\${ *'([a-zA-Z0-9]+)' *[&|] *t *}/g;
57             const strContent = content.toString();
58             let group;
59             while (true) {
60                 group = extractBehaviours.exec(strContent);
61                 if (group === null) {
62                     break;
63                 }
64                 this.parser.set(group[1]);
65             }
66         }
67 
68         done();
69     },
70 };

You can also view the code in gitlab: https://gitlab.com/snippets/1881948

Because of the removeUnusedKeys: true options, keys that are not found will be removed from the JSON files. If you don't want this behavior, switch this option to false.

It is compatible with Javascript and Typescript. If you don't use Typescript, remove the line const typescript = require("typescript"); to avoid issues at import.

Integrate Rollbar with Aurelia

2017-08-19T00:00:00+02:00

I recently integrated Rollbar (a service to Detect, diagnose and debug errors with ease) into an Aurelia application. I explain here how I did it. I start by explaining how logging works with Aurelia and then how I integrated Rollbar into this.

Contents

Logging with Aurelia
Integration with Rollbar
- Using Rollbar within Aurelia
- Loading Rollbar

Logging with Aurelia

The main module to log things with Aurelia is simply named aurelia-logging. It is responsible for:

Setting the log level you want with setLevel.
Create/get loggers with getLogger. When you get a logger with this function, logs messages will be dispatched to all registered log appenders (more on that in a minute) while respecting the level of log you set.
Defining the Appender interface.

So the aurelia-logging is a generic module to deal with logging but doesn't log anything by itself. It is defined this way so it can work in various environment (eg the browser and Node) and send logs where you want (let it be the browser console or Rollbar).

To actually do some logging, we need to add at least one Appender with addAppender. For instance, you can use the aurelia-logging-console module to append log to the browser console. Or you can use au-rollbar to log the messages into Rollbar.

Let's illustrate this with an example. Let's say I configure the log level to log only warnings and above with Logger.setLevel(Logger.logLevel.warn); and that you added the ConsoleAppender and RollbarAppender to the list of appenders with Logger.addAppender(new ConsoleAppender()) and Logger.addAppender(new RollbarAppender());.

You then create your logger with let myLogger = Logger.getLogger('my-module'). You then use the logger, eg:

myLogger.warn('A warning')
myLogger.debug('A debug message')

The A warning message will be dispatched to the console and rollbar while A debug message won't be logged anywhere.

Integration with Rollbar

Using Rollbar within Aurelia

In order to integrate Rollbar into Aurelia, I created a RollbarAppender that implements the Appender interface (see the interface definition here). What it does is pretty straightforward: it dispatches incoming log messages to the proper methods of the Rollbar object. Just like in ConsoleAppender I prepend the level and id of the logger to the message.

Since according to the doc I can only give one message, I put the eventual extra parameters of the function in a JSON object to log them as extra arguments.

Here is the full code. You can download it here. You can also install it with npm install au-rollbar.

 1 export default class RollbarAppender {
 2     debug(logger, ...rest) {
 3         let mainArgs = rest[0];
 4         this.getRollbar().debug(`DEBUG [${logger.id}]: ${mainArgs}`, this._formatRest(rest));
 5     }
 6 
 7     info(logger, ...rest) {
 8         let mainArgs = rest[0];
 9         this.getRollbar().info(`INFO [${logger.id}]  ${mainArgs}`, this._formatRest(rest));
10     }
11 
12     warn(logger, ...rest) {
13         let mainArgs = rest[0];
14         this.getRollbar().warning(`WARN [${logger.id}] ${mainArgs}`, this._formatRest(rest));
15     }
16 
17     error(logger, ...rest) {
18         let mainArgs = rest[0];
19         this.getRollbar().error(`ERROR [${logger.id}]  ${mainArgs}`, this._formatRest(rest));
20     }
21 
22     _formatRest(rest) {
23         try {
24             return JSON.stingify({ extra: rest.slice(1) });
25         } catch (e) {
26             return undefined;
27         }
28     }
29 
30     getRollbar() {
31         if (!window.Rollbar) {
32             if (console.warn) {  // eslint-disable-line no-console
33                 console.warn('Rollbar is not defined');  // eslint-disable-line no-console
34             }
35 
36             return {
37                 debug: () => {},
38                 info: () => {},
39                 warning: () => {},
40                 error: () => {},
41             };
42         }
43 
44         return window.Rollbar;
45     }
46 }

You then need to import it with something like import RollbarAppender from './logging'; (or import RollbarAppender from 'au-rollbar' if you installed it with npm). You then need to configure your logging. Since I doubt you will want to enable it in development, I suggest you configure Aurelia like this (in your main.js file):

 1 import RollbarAppender from 'au-rollbar'
 2 import * as Logger from 'aurelia-logging';
 3 
 4 export function configure(aurelia) {
 5     aurelia.use.standardConfiguration();
 6 
 7     if (environment.debug) {
 8         // Only log to the console when developing (default configuration of developmentLogging)
 9         aurelia.use.developmentLogging();
10     } else {
11         // Production logging is inspired by developmentLogging
12         // This loads the ``aurelia-logging-console`` module and then configures logging.
13         aurelia.use.preTask(() => {
14             return aurelia.loader.normalize(
15                     'aurelia-logging-console',
16                     aurelia.bootstrapperName
17             ).then(name => {
18                 return aurelia.loader.loadModule(name).then(m => {
19                     // Once the module is loaded, we configure logging.
20                     // We add the ConsoleAppender so all messages are logged in the console of the browser.
21                     Logger.addAppender(new m.ConsoleAppender());
22                     // If the Rollbar exists in the window object (ie if Rollbar is loaded),
23                     // we add the RollbarAppender so messages are sent to rollbar.
24                     // If it is not, we print a warning in the browser console.
25                     if (window.Rollbar) {
26                         Logger.addAppender(new RollbarAppender());
27                     } else {
28                         console.warn('Rollbar is not defined');  // eslint-disable-line no-console
29                     }
30                     // Configure logger to log only messages of level warning or above.
31                     Logger.setLevel(Logger.logLevel.warn);
32                 });
33             });
34         });
35     }
36 
37     if (environment.testing) {
38         aurelia.use.plugin('aurelia-testing');
39     }
40 
41     aurelia.start().then(() => aurelia.setRoot('app', document.body));
42 }

Loading Rollbar

Now we need to load the Rollbar script for Rollbar to actually work. Since in addition to logging messages with the Rollbar object, Rollbar can log uncaught exception, it is better to load it as early as possible (to detect errors when Aurelia is bootstraping for instance). To achieve this, I decided to put the configuration and quickstart script (from here) into a rollbar.js script located in the scripts folder. Then, since I use the CLI to build my project, I edited aurelia_project/aurelia.json to add "scripts/rollbar.js", in the prepend section of the vendor bundle. So the definition of the vendor bundle looks like:

 1 {
 2     "name": "vendor-bundle.js",
 3     "prepend": [
 4         "node_modules/bluebird/js/browser/bluebird.js",
 5         "scripts/polyfills.js",
 6         "scripts/rollbar.js",
 7         "node_modules/requirejs/require.js"
 8     ],
 9     "dependencies": [
10         "aurelia-binding",
11         "aurelia-bootstrapper",
12         "aurelia-dependency-injection",
13         "aurelia-event-aggregator",
14         "aurelia-framework",
15         "aurelia-history",
16         "aurelia-history-browser",
17         "aurelia-loader",
18         "aurelia-loader-default",
19         "aurelia-logging",
20         "aurelia-logging-console",
21         "aurelia-metadata",
22         "aurelia-pal",
23         "aurelia-pal-browser",
24         "aurelia-path",
25         "aurelia-polyfills",
26         "aurelia-route-recognizer",
27         "aurelia-router",
28         "aurelia-task-queue",
29         "aurelia-templating",
30         "aurelia-templating-binding",
31         "text",
32         {
33             "name": "aurelia-templating-resources",
34             "path": "../node_modules/aurelia-templating-resources/dist/amd",
35             "main": "aurelia-templating-resources"
36         },
37         {
38             "name": "aurelia-templating-router",
39             "path": "../node_modules/aurelia-templating-router/dist/amd",
40             "main": "aurelia-templating-router"
41         },
42         {
43             "name": "aurelia-testing",
44             "path": "../node_modules/aurelia-testing/dist/amd",
45             "main": "aurelia-testing",
46             "env": "dev"
47         }
48     ]
49 }

If you want to load Rollbar from another location, you can use the rollbarJsUrl property in the configuration object and give it the URL from which you want to load the script.

That's it. If you have any question or remark, please leave a comment.

A sample application with Aurelia UX

2017-08-14T00:00:00+02:00

This is a follow up to my Small comparison of ionic2 and Aurelia + Framework7 for hybrid mobile applications article where I compared ionic2 and Aurelia with Framework 7 for building an hybrid applications. At the time, Aurelia UX was not yet ready (and we were expecting a different, closed source project called Aurelia Interface). Now, Aurelia UX made huge process and I was able to write the sample application in it. I describe here how it went. The code is available on github with the other applications.

As a reminder, here are the features of the TODO application:

List all the saved todos (home page)
Edit an existing todo
Add a todo
Mark a todo as done on the home page. Done todos must have their title strike-through on the home page.

I wrote the application in TypeScript and CSS, since they are the languages Aurelia UX and its showcase application are written in. Here are screenshots of the result:

I based my application on the Aurelia UX showcase app: I cloned this repo, remove the code I didn't need and started to add my code. It is structured like this:

An assets folder with the images and fonts
An aurelia_project folder that contains the configuration for the cli
A custom_typings folder for TypeScript type definitions
A scripts folder created by the cli for some useful scripts (eg require.js)
A src folder that contains the application in itself. It contains:
- The main.ts file which is the entry point to the application
- routes.ts to configure the routes of the application
- CSS files common to all the application
- app.ts, app.css and app.html which configure the layout of the page and configures the menu and the router
- A models folder that contains type definition of the application for TypeScript
- A pages folder which contains the HTML, JS and CSS code for each routes
- A services folder that contains services for the application

Now that's done, let's take a look at the code. I won't detail the main.ts too much since it is very classic. I'll just point out to line 18:

.plugin('aurelia-ux')

This is where we enable Aurelia UX in our application. If we don't, we won't be able to use its tags and attributes in our application.

In the app.ts, we import AureliaUX from the aurelia-ux module and inject it into our application. If you look at the constructor, you'll see the first interesting piece:

constructor(private ux: AureliaUX) {
    ux.design.primary = MAIN_THEME.primary;
    ux.design.accent = MAIN_THEME.accent;

    this.showNavigationMenu = false;
}

Here is the definition of MAIN_THEME:

const MAIN_THEME = {
    primary: '#009688',
    accent: '#4CAF50',
};

We are using this to set the color of the style of our application. If you look at the corresponding CSS, you can see something like:

styles.header {
    background: ${$design.primary};
    color: ${$design.primaryForeground};
}

As you may guess, thanks to the design property of the AureliaUX object, our CSS code and our TypeScript code are linked. The content of ux.design.primary will replace all the occurrences of ${$design.primary} in the CSS. And the best part is: it is dynamic! If you change ux.design.primary in your application, the style will update to reflect it. You can test this by opening the hamburger menu and clicking on the Alternate theme check box. This will call the theme changed function to update the style of the application.

To use this feature in our HTML, we must:

Require the CSS file with the ux hash:

<require from="./app.css#ux"></require>

Use styles.header as a custom attribute, like this:

<header styles.header>
    <h1 styles.header-h1>${router.currentInstruction.config.navModel.title}</h1>
    <a styles.clickable target="_self" click.delegate="toggleNavigationMenu()">
        <i styles.header-burger class="fa fa-bars" aria-hidden="true"></i>
    </a>
</header>

Simple and efficient, isn't?

Navigation in the application is handled by Aurelia's router. Since you are probably already familiar with it, I won't detail that here.

Lets take a look at the edit page. There isn't much in the TS code: we basically setup the validation (to know more about validation, see this article), rely on the storage service to load the TODO to edit (if we are editing an existing TODO) and save it in the cache. We also use this.router.navigateToRoute('list'); to navigate in the application.

The more interesting part is the HTML where I use tags defined by Aurelia UX. The form to add a TODO is located in a ux-form tag. I then use the custom tags to create:

The input for the title:

<ux-input
             placeholder="Title"
             value.bind="todo.title & validate"
></ux-input>

The textarea:

<ux-textarea
              auto-resize
              placeholder="Description"
              value.bind="todo.description & validate"
></ux-textarea>

The done checkbox:

<ux-field>
   <ux-checkbox checked.bind="todo.done">Done</ux-checkbox>
</ux-field>

The save button:

<ux-button type="raised" click.delegate="save()" disabled.bind="!canSave">Save</ux-button>

As you can see, they are simply custom elements and behave like any other custom elements would.

The list page is quite basic so I won't detail it. If you have questions, please leave a comment.

What I didn't test:

Building the application and sending it to my phone. I suspect this will be similar to what you can do with Framework 7 or ionic.
Using SCSS instead of CSS. I frankly have no idea how this would behave in conjuction with how you can interact with CSS inside Aurelia UX (things like ux.design.primary = MAIN_THEME.primary; in your JS and background: ${$design.primary}; in the CSS.

There is currently no documentation about Aurelia UX but the showcase app contains example for all the available components. You can clone the repo and launch it with npm install to install the dependencies and then au run to run it.

To conclude: I find the project promising. It's easy to work with, has some really nice features (such as the ability to have easy links between the code and the CSS). The look and feel of the application is great. The integration with Aurelia is perfect. It also looks a lot like ionic so developers used to this framework shouldn't be lost. They are however some downsides: this is still a work in progress and some components don't exist yet (eg select). I also found that the checkboxes are not always reliable. Some clicks where not taken into accounts. I don't know if this came from my browser (FireFox for desktop, I haven't tested on mobile) or from the way the check boxes are rendered (they are not real check boxes but divs so they can be styled correctly).

That's it for today. If you have a question or remark, please leave a comment below.

Form validation with Aurelia

2017-01-24T00:00:00+01:00

Note

Update from 2017-01-25: after new exchanges with Doug Kent I was able to improve my workaround to disable the submission of the form until it is valid. See the Disable the submission until the form is valid section for the code.

I promised some months ago that I will talk about form validation with Aurelia. At that time, the validation plugin was still under heavy development. Furthermore, aurelia-validation was dropped in favour of aurelia-validatejs and then aurelia-validatejs was dropped for aurelia-validation. Now things look to have settled down for aurelia-validation. That's what I'll talk about today.

From what I see in the documentation, the plugin is both powerful and expressive (many rules available, possibility to chain them, error reporting, possibility to create your own rules, possibility to hook on the render phase, …).

Contents

Quick overview
More advanced example
- Disable the submission until the form is valid
- Conclusion

Quick overview

To get started, you need to:

Install aurelia-validation: npm install --save aurelia-validation
Enable it in your application (in your main.js):

aurelia.use
  .standardConfiguration()
  .plugin('aurelia-validation')
  .developmentLogging();

The more direct way to use validation is to:

Import ValidationControllerFactory and ValidationRules from aurelia-validation
Inject ValidationControllerFactory in you component @inject(ValidationControllerFactory)
Create the validation controller: this.controller = controllerFactory.createForCurrentScope();
Use ValidationRules to create some validation rules. For instance to make a field named title of the current class mandatory: ValidationRules.ensure('title').required().on(this);

In a nutshell, this JavaScript code:

import { inject } from 'aurelia-framework';
import { ValidationControllerFactory, ValidationRules } from 'aurelia-validation';


@inject(ValidationControllerFactory)
export class TodoPage {
    constructor(controllerFactory) {
        this.controller = controllerFactory.createForCurrentScope();
        ValidationRules
            .ensure('title').required()
            .on(this);
    }
}

with this template:

<template>
    <input type="text" placeholder="Title" value.bind="title & validate" required>
</template>

You probably want to view the list of validation errors. To do that, you can use the validation-errors attribute like that:

<template>
    <div validation-errors.bind="errors">
        <input type="text" placeholder="Title" value.bind="title & validate" required>

        <ul if.bind="controller.errors">
            <li repeat.for="error of controller.errors">
                ${error.message}
            </li>
        </ul>
    </div>
</template>

This will display the default error message for each rule that failed. You can change this message with withMessage: ValidationRules.ensure('title').required().withMessage('Title must be provided in this form.').on(this). You can also use aurelia-i18n to translate these messages (see the documentation).

More advanced example

Now that we've covered the basics, let's get back to my mobile todo application built with Aurelia and Framework7. I have a form to create a TODO that requires a title:

My goal is to use aurelia-validation to:

Prevent the user to create a TODO until a title with at least 3 characters is supplied (just to see how we can chain rules for a property). In order to to that, I just need to use the proper validation rules (since the title is stored in a todo property of my object, I don't use .on(this) but .on(this.todo):
```
ValidationRules
      .ensure('title').required().minLength(3).withMessage('Title must at least be 3 chars long.')
      .on(this.todo);
```
Display an error message next to the title with a proper error message. This message will of course be updated as the user types. To achieve that, I need to:
1. Change how validation is trigger: by default it is on blur (that is when the user leaves the field). Let's import validateTrigger and update our controller: this.controller.validateTrigger = validateTrigger.changeOrBlur;
2. Use the validation-errors attribute on an element that only contains the input for my title. This way, the value bound to it will only contain errors for this field (by construction, validation-errors contains errors only for the fields it contains):
```
<div class="item-inner" validation-errors.bind="titleErrors">
    <div class="item-title label">
        Title
        <strong repeat.for="errorInfo of titleErrors">${errorInfo.error.message}</strong>
    </div>
    <div class="item-input">
        
        <input type="text" placeholder="Title" value.bind="todo.title & validate" required>
    </div>
</div>
```

Disable the submission until the form is valid

At this point I ran into a problem: how can I disable the submission of a TODO until it is valid? If I use validation-errors.bind="errors" on an element that includes the full form, I can use errors.length === 0 to check that it is valid. The problem is, that when the page loads, the form is invalid but since validation hasn't run yet, the submit button will be active. If I validate the form in the attached method of the component, errors is not empty (so the button is correctly disabled) but the error message for the title is displayed too soon (before the user event interacted with the form which is not what I want).

In Angular2, you can rely on the dirty property of your form controller to know if the user has started to interact with the form. So I could use something like controller.dirty && errors.length === 0 to enable/disable my button (see this article for form validation with Angular2).

~~Sadly there is no such property with aurelia-validation. There is an issue about this with a link to this blog post suggesting to hook on the rendering phase to solve this.~~

There a way to easily do this with aurelia. See Workaround 3 (how you should do it).

Workaround 1

I asked on gitter for help and Doug Kent suggested various solutions the most promising being to use two controllers: one to validate the button, one to display the error. I didn't managed to get it to work but, based on this idea, I found a workaround (and I hope we will have a clean method to do this in the future):

I keep the controller as is for validation and error display.
I use a Validator to manually validate the form without impacting error reporting. The idea is to:
1. Validate the form in attached: this form can also be used to edit an existing todo (which has a valid title), so the save button can be enabled or disabled on page load. This validation is done with the Validator which means no errors will be reported to the user.
2. Watch on the title property of my todo and validate the form each time it changes.

Here is the relevant part of the code:

import { inject, ObserverLocator } from 'aurelia-framework';
import { ValidationControllerFactory, ValidationRules, Validator, validateTrigger } from 'aurelia-validation';


@inject(ValidationControllerFactory, Validator, ObserverLocator)
export class TodoPage {
    constructor(controllerFactory, validator, ol) {
        // We rely on the controller to display the errors.
        this.controller = controllerFactory.createForCurrentScope();
        // We rely on the validator to know if the canSave the todo or not
        // (update the canSave property in the validation method)
        this.validator = validator;
        this.canSave = false;

        this.todo = {};
        ValidationRules
            .ensure('title').required().minLength(3).withMessage('Title must at least be 3 chars long.')
            .on(this.todo);
        this.controller.validateTrigger = validateTrigger.changeOrBlur;

        ol.getObserver(this.todo, 'title').subscribe(() => {
            this.validate();
        });
    }

    attached() {
        this.validate();
    }

    validate() {
        this.validator.validateObject(this.todo).then(results => {
            let valid = true;

            // results is an array of validation results. Each result has a
            // valid property set to true if the rule is valid.
            for (let result of results) {
                valid = valid && result.valid;
            }

            this.canSave = valid;
        });
    }
}

I then use canSave in my template:

<a href="#"
   class="button button-big button-fill color-green ${canSave ? '' : 'disabled'}"
   click.delegate="saveTodo()">Save</a>

You can view the full code here and here. It feels a bit hackish and I don't think this will scale to big forms.

Workaround 2 (looks more solid)

After new exchanges on gitter, Doug Kent made another suggestion: use a custom validator instead of StandardValidator. This way I should be able to hook on the validation phase and call a callback. Guess what: it worked. Let's see how.

We start by creating an new class respecting the Validator interface and taking as argument an instance of the StandardValidator which will do the actual validation work and a callback:

constructor(validator, cb) {
    this.validator = validator;
    this.cb = cb;
}

The idea is then to use the promise returned by this.validator.validateObject to call our callback each time the promise is resolved:

validateObject(object, rules) {
    return this.validator.validateObject(object, rules).then(results => {
        this.cb(results);
        return results;
    });
}

We are almost done. We also need to trigger the validation when a property of the form is validated. For instance, here, when the user modifies the title of the todo, validateObject won't be called. The controller will only call validateProperty. That's not a big problem: once the property is validated, we can validate the whole form to update TodoPage.canSave:

validateObject(object, rules) {
    return this.validator.validateObject(object, rules).then(results => {
        this.cb(results);
        return results;
    });
}

Now let's see how we can use this. We initialize the validator and the controller in the constructor:

// validator is an instance of StandardValidator that was injected by DI.
this.validator = new TodoValidator(validator, results => this.updateCanSave(results));
this.controller = controllerFactory.createForCurrentScope(this.validator);
this.controller.validateTrigger = validateTrigger.changeOrBlur;

Since this page can be used in two cases (creating a new todo and editing an existing one), we differ the creation of the validation rules a little bit: if we set them up in the constructor, they wouldn't apply on the proper object when editing a TODO. We wait for the activation and the page to distinguish between these to cases:

Creating a new TODO

this.todo = {};
this.setupValidation();

Editing a TODO

this.storage.getTodo(params.id)  // Fetch the TODO.
    .then(todo => this.todo = todo)  // Save the TODO in the current object.
    .then(() => {
        // Setup the validation rules.
        this.setupValidation();
        // Launch validation to enable the save button if the edited TODO is valid.
        this.validate();
    });

The setupValidation method is just here to create our validation rules:

ValidationRules
        .ensure('title').required().minLength(3).withMessage('Title must at least be 3 chars long.')
        .on(this.todo);

The validate method just calls this.validator.validateObject(this.todo);. As for updateCanSave it updates the canSave property based on the results of the validation:

updateCanSave(validationResults) {
    let valid = true;

    for (let result of validationResults) {
        valid = valid && result.valid;
    }

    this.canSave = valid;
}

And that's it. The main advantage of this method, is that no matter how many fields you have, you don't need extra work. It can also easily be reused for different forms. You can see the full code here (with additional comments) and here (template).

Workaround 3 (how you should do it)

As a follow up to this issue work has been done by Aurelia's contributor Jeremy Danyow so we can execute a callback each time the validator is called. This greatly simplifies the code. You can view the documentation here.

In the constructor, we create the controller with a new validator and register the callback:

constructor(validator, controllerFactory) {
    this.canSave = false;
    this.controller = controllerFactory.createForCurrentScope(validator);
    this.controller.validateTrigger = validateTrigger.changeOrBlur;
    this.controller.subscribe(event => this.validateWhole());
}

The callback passed to this.controller.subscribe will be called each time the validator is run, for reset and validate events. It has one parameter: the event. You can use it to filter by validation type or to get the errors associated with this run. Go here to view the full interface.

Note: We don't need to manually run this.validateWhole manually to initialize canSave correctly. When the form is created and validation is bootstraped, the validator will run with a reset event.

In our case, we want to validate the whole form each time a field is validated so we can update our canSave property:

private validateWhole() {
    this.validator.validateObject(this.todo)
        .then(results => this.canSave = results.every(result => result.valid));
}

And we are done. This is much simplier and shorter that all the other workaround.

Note: Running validation will not display errors messages associated to any field. So even if you validate multiple fields and display error messages for each one, validateWhole will not have an impact.

You can view the full file here and the associated template here.

Conclusion

You should now be able to validate your forms with Aurelia. If you have a question or a remark, please leave a comment.

Make navigation user friendly on your Aurelia SPA

2016-08-28T00:00:00+02:00

Contents

Add a spinner
Use the wait cursor while navigating
Display a message to no-script user
More

Add a spinner

Add the font awesome files to your project (CSS and fonts files).

Import the font awesome style sheet in your index.html

<link rel="stylesheet" href="/assets/fonts/fontawesome/font-awesome.min.css">

Add the CSS code below to create the spinner either directly in the index.html with style tag or in a CSS file that you load in it:

.splash {
    text-align: center;
    margin: 10% 0 0 0;
    box-sizing: border-box;
}

.splash .message {
    font-size: 72px;
    line-height: 72px;
    text-shadow: rgba(0, 0, 0, 0.5) 0 0 15px;
    text-transform: uppercase;
    font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
}

.splash .fa-spinner {
    text-align: center;
    display: inline-block;
    font-size: 72px;
    margin-top: 50px;
}

Update the div in which your Aurelia application will be instantiated. Eg, replace:

<body aurelia-app="main">
  <div>
  </div>
</body>

By:

<body aurelia-app="main">
  <div class="splash">
      <div class="message">Arena of Titans</div>
      <i class="fa fa-spinner fa-spin"></i>
   </div>
</body>

Use the wait cursor while navigating

Change your router-view from:
```
<router-view></router-view>
```
to:
```
<router-view class="${router.isNavigating ? 'navigating' : ''}"></router-view>
```
this will add a class navigating to the router-view tag when the router is navigating and nothing otherwise.
Add this global CSS code to your application:
```
.navigating {
    cursor: wait !important;
    opacity: 0.7;
}

.navigating button {
    cursor: wait !important;
    opacity: 0.5;
}
```
This will display the wait cursor on the page and reduce the opacity on the page to signal the user a navigation is going on. You can of course change this code to match your application.
Don't forget to add the router to your object. In the configureRouter(config, router) function, do:
```
this.router = router;
```

Display a message to no-script user

Some of your users may use an extension like noscript which disable JavaScript on page you visit. By default, you will greet them with either a blank page or a never-ending spinner. I think it is more user friendly to show them a message asking to enable JavaScript. To do, add in your body tag:

 <noscript>
     <p>Arena of Titans cannot work without JavaScript. Please enable it.</p>
     <p>Arena of Titans ne peut pas fonctionner sans JavaScript. Merci de l'activer.</p>
</noscript>

To view the full details, look at these two commits:

Switching an application to aurelia-cli

2016-08-17T00:00:00+02:00

About a month ago, I started to make experiments with the webpack plugin for Aurelia in order to split my applications into multiple bundles. The application in question is a strategy game called Arena of Titans. You can see it there (click play to create a game, or use this link).

It was working well but the initial load of any page was slow. It was easy to find out why: the bundle loaded by webpack was over 1.3 megabytes big. Why is it that big? Well, it contained the game board which is about 1.1 megabytes minified. Hence my will to split it into several bundles in order to speed up the loading of the site. We still have to load the big board on the game page but at least the site would work at an acceptable speed.

I didn't manage to do it with webpack and after some time trying I thought what about the new aurelia-cli? I was able to do it just fine. Here's how I did it. You can skip to the part about bundles if you're not interested in the rest.

Contents

Presentation of aurelia-cli
Preparation
- Updates in main.js
Style
Bundles
- Problems encountered with bundles and their solutions
Tests
Conclusion

Presentation of aurelia-cli

aurelia-cli is a project aimed to provide a command line interface to create and run projects written with the Aurelia JavaScript framework. You can:

Create a new project with au new <project-name>. You will then be guided by an assistant to configure the project: standard ES6 or typescript, pure CSS or SCSS/Less, …
Run the project with au run or au run --watch to rebuild the app when you save a modification.
Test the project with au test or au test --watch to retest the app when you save a modification.

It relies on gulp to launch its tasks and on Browsersync to provide a small HTTP server that will reload you page when you do a modification.

Preparation

To avoid messing with the current code, I created a new aurelia-cli project in a separate folder and I copied the proper files in my project:

The folder aurelia_project which contains the gulp tasks required by aurelia-cli to run and the configuration of the project.
The scripts folder which contains requirejs the module loader used by project running with aurelia-cli and its text plugin to load the HTML and CSS.
test/aurelia-karma.js a small file that allows you to use karma with aurelia-cli projects. See the section about tests to learn more on that.
karma.conf.js so my karma configuration file doesn't rely on webpack any more and meets the expectations of aurelia-cli.

I then updated my package.json file. To do that, I just compared my current package.json with the one from the aurelia-cli project: I added the proper dependencies (like aurelia-cli) and removed the old ones (like webpack).

To avoid style warning with on the environement.js file, I added it to the .eslintignore. This files contains utilities values to configure aurelia (are we testing? are we in debug mode?):

export default {
    debug: true,
    testing: false
};

I then removed all of webpack configuration files and run rm -rf node_modules && npm install to update the dependencies.

Then, I adapted aurelia.json to my needs:

The sources of my project are in a folder named app and not in src as it is by default. So I changed all paths (a replace src by app did it). I also had to correct aurelia-karma.js. See the section about tests to learn more about that.
I configured the router to use push states. Which means my URLs look like this: /game/create and not like this #/game/create. The problem is that, by default, requirejs will load its bundle under /game/scripts/bundle.js instead of /scripts/bundle.js. So I did my first patch in aurelia-cli to add an option to use absolute path in requirejs. This way if you use "useAbsolutePath": true in the build.targets section of your aurelia.json file, your bundles will always be loaded in /scripts/bundle.js.

I also updated my global.scss file to load fonts with an absolute URL and aurelia_project/tasks/run.js to change the port of Browsersync and disable the ghost mode which mimics on all browsers the action you do in one: I want to be able to test the game in different browsers running different players. I don't want it to reproduce what I do in every browsers I have opened.

Updates in main.js

I reverted Aurelia's configuration function to the classical export function configure(aurelia) and I added the two lines below to enable development logging only on debug mode and to enable the testing plugin when testing:

if (environment.debug) {
    aurelia.use.developmentLogging();
}

if (environment.testing) {
    aurelia.use.plugin('aurelia-testing');
}

I also updated my configuration of bluebird.js a promise library for javascript in main.js from:

  let Promise = require('bluebird').config({
    longStackTraces: false,
    warnings: false,
});

to:

Promise.config({
    longStackTraces: false,
    warnings: false,
});

Style

With webpack, you include the SCSS files like javascript but with the extension, like this: import ./style/global.scss. Webpack will then compile the file and include it in the bundle thanks the loader you've configured. With aurelia-cli, things are a little different. You include the file in your HTML files like you require custom elements:

<require from="./style/global.css"></require>

Note that the extension of the file must be .css whether you're using true CSS or another language compiled to CSS like SCSS. The reason is that it will be loaded as CSS. You just have to configure the cssPreprosessor in your aurelia.json for the code to be correctly processed:

"cssProcessor": {
   "id": "sass",
   "displayName": "Sass",
   "fileExtension": ".scss",
   "source": "app/**/*.scss"
}

Bundles

The ability to split my app into multiple bundles is the main reason I switched to aurelia-cli. To create a bundle, all you have to do is to add an object with a name and a list of dependencies to the build.bundles array of your aurelia.json file.

It works great but the first time I tried, my bundles were not filled correctly. I tried to include files like this: "[site/**/*.js]" but it didn't work. I did some search and I found this comment by TylerJPresley on a issue about creating multiple bundles with aurelia-cli which gave me the solution: you have to put stars in front of the file name. Like this: "[**/site/**/*.js]":

{
    "name": "site-bundle.js",
    "source": [
        "[**/site/**/*.js]",
        "**/site/**/*.{css,html}"
    ]
}

With that, my bundles were correctly created and filled but they were not loaded. However, it turns out that I was missing some files in them: I did put the site and game files but not app.js, environment.js and main.js. As you might expect, without these files Aurelia could not work correctly. So I create a common-bundle.js for them and other files needed in the whole application:

{
    "name": "common-bundle.js",
    "source": [
        "[**/locale/**/*.js]",
        "[**/app.js]",
        "[**/environment.js]",
        "[**/main.js]",
        "[**/services/options.js]",
        "[**/services/storage.js]",
        "[**/services/browser-sniffer.js]",
        "[**/widgets/aot-options/*.js]",
        "**/app.html",
        "**/widgets/aot-options/*.html",
        "**/widgets/aot-options/*.css",
        "**/style/*.css"
    ]
}

In addition to bundling your app files, you can also include non Aurelia dependencies from outside your project if they rely on AMD. For instance, here's how I define my game-create-bundle.js with clipboardjs:

{
   "name": "game-create-bundle.js",
   "dependencies": [
       {
           "name": "clipboard",
           "path": "../node_modules/clipboard/dist",
           "main": "clipboard"
       }
   ],
   "source": [
       "[**/game/create/**/*.js]",
       "**/game/create/**/*.{css,html}"
   ]
}

You can also prepend javascript files to a bundle. That's how requirejs and bluebird are loaded. Here's the relevant excerpt from the vendor-bundle.js (defined here):

"prepend": [
     "node_modules/bluebird/js/browser/bluebird.js",
     "scripts/require.js"
]

At last but not least, some Aurelia modules contains multiple files that must be resolved. To bundle those correctly, you need to use an object instead of the name of the module in you dependencies array. Like this:

"dependencies": [
    "aurelia-binding",
    {
        "name": "i18next",
        "path": "../node_modules/i18next/dist/commonjs",
        "main": "index"
    }
]

You can view the full definition of my vendor-bundle.js where this example is taken here and the definition of all my bundles here.

All in all, I think that bundling with aurelia-cli is very powerful, works well and, once you know for the double stars, is quite easy to setup with the help of a new project to give you the base configuration.

In the end, I have 6 bundles for the application:

vendor-bundle.js with requirejs, bluebird.js a promise library and all Aurelia related files.
common-bundle.js that contains the translations, app.js, main.js, environement.js and various services and widgets common to the site and the game.
site-bundle.js that contains all pages and widgets for the sites.
game-common-bundle.js that contains files required to create and play the game.
game-create-bundle.js that contains all the widgets to create the game.
game-play-bundle.js that contains all you need to actually play the game.

Problems encountered with bundles and their solutions

aurelia-cli loads its bundles with requirejs which I find great. Until during a test session a friend reported that he was not redirected to the game page when he first tried to create a game. The second time he tried everything worked fine.

I dug into the problem and found out why it was failing. The bundle containing the game is still big (about 1.3 megabytes). On some slow connection, it took more than 7 seconds to load it. Which means that we encountered the default timeout for requirejs and the app would consider the bundle could not be loaded and thus didn't redirect the player to the page even after the script was loaded. requirejs nicely logged an error with this link in the console.

The solution is to use the waitSeconds option of requirejs to increase the value of the timeout (you can also disable it as the documentation says). I did some tests directly in the generated bundle and it work.

The problem is that at the time of this writing, aurelia-cli doesn't allow you to give custom options to the loader. So, I made a pull request to allow the user to do just that in order to correctly solve my problem while still using the cli. I hope it will be merged soon.

In order to further improve load time on these slow connection, I preload the big game-play-bundle.js with the board as soon as a user reaches the create game page. To do that, I added the line below in the constructor of the create game page:

require(['game/play/widgets/board/board'], () => {});

You must use this syntax to load the script asynchronously. If you use:

require('game/play/widgets/board/board')

the script will be loaded synchronously which means the user can't prepare the game until it is completely loaded. That is of course not my goal.

Tests

First, since the code is not in the src folder but in app, I had to correct aurelia-karma.js (see Preparation for where it comes from) the file that boostrap karma for usage with aurelia-cli. I had to correct this line (52 at the time of this writing):

originalDefine('/base/src/' + name, [name], function (result) { return result; });

into:

originalDefine('/base/app/' + name, [name], function (result) { return result; });

I think it would be better for aurelia-karma to use paths.root for aurelia.json (more general). I gave it a try but didn't succeed. But there may be other ways to do this. See my issue on the subject for more details paths.root from aurelia.json.

In my test files, I had to change some import paths, remove my import ../setup since it is automatically loaded by aurelia-karma. The test/unit/setup.js has the same content as before to import ployfills and initialize Aurelia:

import 'aurelia-polyfills';
import { initialize } from 'aurelia-pal-browser';

initialize();

I also had to move my test-utils.js which contains various stubs I use in my unit tests from the test/unit folder into the app folder so it is correctly transpiled by babel. I also created a dedicated bundle named test-utils-bundle.js to avoid loading it in the true application.

Conclusion

This is it! Converting the project wasn't very hard but some problems (absolute loading of bundles, some problems with testing and the inability to configure requirejs) required some time to make it work correctly. Now I think that the project is ready for the future of Aurelia tooling and I don't think I'll need to switch tools again.

If you want all the gory details, take a look at this merge commit and the commits before it in the aurelia-cli branch.

Otherwise, you also take a look at my aurelia.json file here, browse the complete code of the app there and see it in action on the website (click play to create a game, or use this link).

If you have a remark or question about this article or the game, leave a comment below or contact me on twitter.

Next step on my agenda, setup code coverage of the original sources of the app (and not the bundle, that would be too easy). I hope I'll be able to make it work and write about it soon. Stay tuned!

Plugin for statistics with Piwik on an Aurelia SPA

2016-06-05T00:00:00+02:00

On Arena of Titans a game based on the Aurelia web framework I am developing with a friend, we use Piwik to have statistics about our visitors. When we were about to launch the game, I realized that Piwik was not logging all the pages but only the pages on which you entered. It makes perfect sense: navigation on the site is handled by Aurelia which means there is no page load and if there is no page load, Piwik doesn't load the navigation.

To go around this problem, I created a small plugin for Aurelia aurelia-piwik. What it does is straightforward: it register a callback for the router:navigation:success event which is fired by Aurelia's router on successful navigation. In this callback, I use Piwik's API to log the navigation.

You can easily use this plugin once installed by registering it in your main.js:

aurelia.use
 .standardConfiguration()
 .developmentLogging()
 .plugin('aurelia-piwik')

I must say I am impressed by how easy it was to implement and use. After nearly seven months of Aurelia usage, I am really glad to use this framework. If you haven't checked it out yet, please do!

The source are available under the MIT license on GitHub. The package is also available on npm.

Resolving blank page problem of Aurelia app with webpack on Safari

2016-06-03T00:00:00+02:00

While asking users to test an Aurelia application, it appeared that it didn't work on Safari due to this error:

It comes from the fact that Safari doesn't support the internationalization (window.Intl) API.

In order to solve it, I had to manually include the Intl.js polyfill. Since it is already pulled as a dependency, I just had to adapt the bootstrap function of Aurelia with the setup code for Webpack of Intl.js:

bootstrap(aurelia => {
     if (!global.Intl) {
         console.log('Intl not present')
         require.ensure([
             'intl',
             'intl/locale-data/jsonp/en.js'
         ], function (require) {
             require('intl');
             require('intl/locale-data/jsonp/en.js');
             boot(aurelia);
         });
     } else {
         boot(aurelia);
     }
 });


 function boot(aurelia) {
     aurelia.use
         .standardConfiguration()
         .developmentLogging()
         .plugin('aurelia-i18n', (instance) => {
             let language = navigator.language.split('-')[0];

             // register backend plugin
             instance.i18next.use(XHR);

             function loadLocales(url, options, callback, data) {
                 switch (url) {
                     case 'en':
                         callback(enTranslations, { status: '200' });
                         break;
                     case 'fr':
                         callback(frTranslations, { status: '200' });
                         break;
                     default:
                         callback(null, { status: '404' });
                         break;
                 }
             }

             instance.setup({
                 backend: {
                     loadPath: '{{lng}}',
                     parse: (data) => data,
                     ajax: loadLocales,
                 },
                 lng: language,
                 attributes: ['t', 'i18n'],
                 fallbackLng: 'en',
                 debug: false,
             });
         });

     aurelia.start().then(() => aurelia.setRoot('app', document.body));
 }

How I switched an Aurelia application to webpack

2016-04-24T00:00:00+02:00

Note: I wrote this post when aurelia-webpack wast still in pre 1.0.0 release. As niieani pointed out in the comments part of it may be outdated and you way want to use aurelia-webpack with easy-webpack instead. The general ideas are still valid though.

First thing first: why would I want to use webpack with Aurelia instead of the default JSPM?

I was tired of JSPM which I find buggy
No need for gulp anymore
All deps are in the package.json file and node_modules folder
webpack can build all kind of files (JS, TS, CSS, JSON, …) and perform optimization on them
Awesome dev server with hot reload.

If you are interested in the subject, you can read this article from Dwayne Charrington which gives more details on why you may want to use webpack.

Here are the steps I followed. I did them nearly a month back but haven't found the time to write this article before today, so it is based on my small notes and memories. I apologize if this article is not as precise as it could be. If you have a specific question or run into trouble, please leave a comment. Anyway, the thing to remember is that the migration went well and webpack works very well with Aurelia.

Update index.html. Copy/Pasting the index.html from the skeleton with little adaptation should do the trick. You will also need a index.prod.html file for use in production. Again, the skeleton has what you need.
Update dependencies in package.json. Adapt the one from the skeleton. You may need to add dependencies beside webpack specific ones (specified in the skeleton) to get your app working. For instance, aurelia-logging-console was not explicitly in my package.json (not even under the jspm key). You can also get rid of the jspm key. In my case, Aurelia will give you a nice debug message if you are lacking a required dependency.
Update configuration of Karma. See karma.conf in the skeleton. For your tests to work, you are very likely to need to bootstrap your tests by adding to each file (you can also put that in a setup.js file and import it in your test files):

import { initialize } from 'aurelia-pal-browser';

initialize();

Update main.js (create it if you don't have one). See the skeleton for inspiration. Important note: if you want you style files to be loaded with webpack, they must be imported in a JS file. main.js can be a good place to place these import.
Copy webpack.config.js and webpack.prod.config.js and adapt them if need be.
Remove JSPM files: rm -rf jspm_packages config.js
Remove unneeded node modules (eg jspm) rm -rf node_modules
Remove gulp related files: rm -rf gulpfile.js build
Install new dependencies: npm install
Take care of submodules Not needed with aurelia-webpack 1.0.0: if you see an error like this:

.*$:106 Uncaught (in promise) Error: Cannot find module './aurelia-i18n/t'.
.*$:106 Uncaught (in promise) Error: Cannot find module './aurelia-i18n/nf'.
.*$:106 Uncaught (in promise) Error: Cannot find module './aurelia-i18n/df'.
Uncaught (in promise) Error: Cannot find module './aurelia-i18n/rt'.

You need to enable sub-modules for this modules, with something like this:

new AureliaWebpackPlugin({
    includeSubModules: [
        { moduleId: "aurelia-i18n" }
    ]
})

See the documentation of the webpack plugin for more information on that.

Normally you are ready to launch ./node_modules/.bin/webpack-dev-server --config webpack.config.js --hot --inline --progress --devtool eval and start developing with Aurelia and webpack.

Small comparison of ionic2 and Aurelia + Framework7 for hybrid mobile applications

2016-03-15T00:00:00+01:00

Update (2017-08-14): I finally published the part on Aurelia UX. See it here.

Updates (2017-01-24):

aurelia-interface has been deprecated in favour of aurelia-ux.
Add a link to my article about aurelia-validation.
I don't think I'll start a project to use Aurelia with Framework7. I want to test aurelia-ux first. However, someone is starting one: https://github.com/alflennik/au7

Contents

Application features
Ionic2
Aurelia and Framework7
- Bonus
Conclusion

I spent some time recently to develop a mobile application with the ionic framework. This framework allows you to create mobile applications for Android and iOS with HTML5 and CSS3 and AngularJS. Which means you can develop native like applications with the ease of development of a web application: debug in a browser, use Javascript and a framework you probably already know and that's it! No java or Swift, just the power of the web. The application is then build for your phone with Apache Cordova.

Since they have a version 2 coming soon based on Angular2, I decided to use directly this version (currently in beta).

However, on a another project, I use Aurelia a JavaScript framework built with ES6 and around web standards aimed to create Single Page Applications easily. And I must say I love it. It embraces ES6 and the new possibilities offered by the language and its use of convention over configuration makes it easy to work with.

So I wanted to try to build a mobile application with it. There are plans for a commercial addon called Aurelia Interface. Sadly there is not much information about it available apart from that video. After a small discussion on Aurelia's gitter, Scalpal suggested to look at Framework7 an HTML/CSS (with small bits of JavaScript) framework to do pretty much the same thing as ionic without the dependency on a particular framework. That's what I did and it turned out to work well with Aurelia.

Let's test!

Application features

To compare the two possibilities, I wanted to do a basic todo list applications that can:

List all the saved todos (home page)
Edit an existing todo
Add a todo
Mark a todo as done on the home page. Done todos must have their title strike-through on the home page.

All todos must be stored in the permanent SqlStorage of the phone.

In additions to these features, both applications must work on a browser (for debug and development purposes), on an android emulator and on an android phone.

Here is how the home page looks like (Aurelia + Framework7 on the left, Ionic2 + Angular2 on the right):

And the todo page (Aurelia + Framework7 on the left, Ionic2 + Angular2 on the right):

The complete code of the applications is available on github under the MIT license. Normally, the READMEs are complete enough to let you try the applications. If you encounter any problem, leave a comment or open an issue!

Ionic2

I wrote this version in TypeScript a language made by Microsoft to ease the development of huge frontend applications and not ES6 since it is the recommended way for Angular2 applications (Angular2 is itself written in TypeScript).

To organize the application, I followed the standard structure proposed by ionic:

An app folder with the code. In this app folder:
- each pages (JS, HTML and eventually SASS) are grouped in a folder within pages.
- Global theme SASS files are in the theme folder.
- Boostrap (app.ts) and utils (models.ts) are directly in app.
A build folder used for debugging and by Cordova to generate the final application. It contains the index.html generated by ionic and will contain all the built files.

First, let's talk of models.ts. It only contains one class and is used in the application as a type for the TypeScript compiler (and completion).

export class Todo {
    public id: number;
    public title: string;
    public description: string;
    public done: boolean;
}

In app.ts the application is bootstrapped. It is generated by ionic. I only changed the value of MyApp#rootPage so its value is ListTodosPage the JavaScript class that defines my root page.

That leads us to the first important concept of Ionic2: navigation doesn't work with URLs. As you'll see if you launch the app, the URL is never updated. To navigate between pages, you use a NavController object and pass the page on which you want to go, like that:

this.nav.push(TodoPage)

A page being a class decorated with @Page a decorator that comes from the ionic framework.

On the main page, we display the navbar and the list of all todos. To do that, you use in your template the ion-navbar element. This allows you to easily customize the navbar for each page. Ionic will also automatically add a Back button in this navbar when you navigate to another page.

The main content of the page must be inside the ion-content element. Almost all the elements you will put in it are defined by ionic to help you and starts with ion.

You can also add Angular2 markup:

if the tag starts by a star (*), it's a template, like *ngFor="#todo of todos, #index = index". Note that the syntax is particular: to create a variable in a template, you must put a pound sing (#) before the name of the variable.
if the tag is between parenthesis it is bound to an event like (click)="viewTodo(todo)". The value of the tag will be executed when the event occurs.
if the tag is between bracket like [class]="getClass(todo)" it means its value is one way bound to the expression you pass.

<ion-navbar *navbar>
       <ion-title>TODO list</ion-title>
</ion-navbar>

<ion-content padding>
       <ion-list>
           <ion-item *ngFor="#todo of todos, #index = index">
               <ion-label [class]="getClass(todo)" (click)="viewTodo(index)">{{ todo.title }}</ion-label>
               <button item-right (click)="markTodoDone(todo)">Toggle done</button>
           </ion-item>
       </ion-list>

       <button full round (click)="addTodo()">Add</button>
</ion-content>

On the TypeScript side, we have a class ListTodosPage decorated by @Page. This decorator is only used here to defined the template used for the page but it is also used to define which pipes (filters in Angular2 terminology) and directives are available in the template.

In the constructor, we create the SQL database if it doesn't exist and retrieve the todos:

this.storage.query('CREATE TABLE IF NOT EXISTS todos(id integer primary key unique, title VARCHAR(10), description TEXT, done BOOLEAN)')
  .then(() => this.storage.query('SELECT * FROM todos'))
  .then(results => {
      for (let result of results.res.rows) {
          console.log(result)
          this.todos.push(result);
      }
  })
  .catch(err => console.log(err));

To view a particular todo, we use the navigation controller with navigation parameters:

this.nav.push(TodoPage, {
    todo: this.todos[index],
    index: index,
});

To add a todo, we just omit the navigation parameter.

We can then retrieve the todo on the TodoPage like this:

constructor(private nav: NavController, navParams: NavParams) {
     if (navParams.data.todo) {
         this.todo = navParams.data.todo;
     } else {
         this.todo = new Todo();
     }
}

Once we have our todo (the one we want to edit or a new one), we can create the form and bind its default value to the existing todo. This way, if we have an existing todo, the from will be prefilled with the correct values.

I must say that forms in Angular2 are a huge beast and I am not sure to fully see the interest of such a complex system (at least in most cases). The programming API and the template tags are powerful and allow you to create fine grained validators to suit your needs but they are hard to understand at first. You have a simple syntax which suffers from lack of functionality and a powerful and verbose one (which I use here). Let's look at the code:

let group: {[key: string]: Control} = {
    title: new Control(this.todo.title, Validators.compose([Validators.required])),
    description: new Control(this.todo.description),
    done: new Control(this.todo.done),
};

this.todoForm = new ControlGroup(group);
this.title = this.todoForm.controls['title'];
this.description = this.todoForm.controls['description'];
this.done = this.todoForm.controls['done'];

First we defined the group of input we want. We give them a default value and eventually the validator use to determine if the value is correct or not. Then we create the form and extract from it the controls that will be used in the template for validation.

Now we can look at the template. I won't dig into it. If you want to learn more about forms in Angular2, visit this page.

Just see how we use the controls to see if a field is correct or not and note that we use the [ngFormModel] tag to bind the form to the proper form object.

<form [ngFormModel]="todoForm" (ngSubmit)="save(todoForm.value)">
     <ion-item [class.error]="!title.valid && title.touched">
         <ion-label floating>Title</ion-label>
         <ion-input type="text" value="" [ngFormControl]="title"></ion-input>
     </ion-item>
     <div *ngIf="title.hasError('required') && title.touched"
         class="error-box">
             * Title is required!
     </div>
     <ion-item [class.error]="!description.valid && description.touched">
         <ion-label floating>Description</ion-label>
         <ion-textarea type="text" value="" [ngFormControl]="description"></ion-textarea>
     </ion-item>
     <ion-item [class.error]="!done.valid && done.touched">
         <ion-label>Done</ion-label>
         <ion-checkbox [ngFormControl]="done"></ion-checkbox>
     </ion-item>

     <button full round danger type="reset" (click)="cancel()">Cancel</button>
     <button full round type="submit" [disabled]="!todoForm.valid">Save</button>
 </form>

We can then save the todo with an SQL query and parameters replacement:

this.storage.query(
    'UPDATE todos SET title = ?, description = ?, done = ? WHERE id = ?',
    [todoValues.title, todoValues.description, todoValues.done, this.todo.id]
)

Aurelia and Framework7

I decided to use webpack (an official skeleton is available) instead of the default SystemJS. Two reasons for that:

It's a good way to test webpack support
During my initial research I found that people had problems with SystemJS and cordova. Since webpack is used by ionic2, I expected it to work well.

I followed the same structure than for ionic: each pages in app/pages/<pagename>, services in app/services and bootstrap (main.js and app.js directly in the app folder.

The HTML code in index.html and app.html is almost a copy/paste from the getting started of Framework7. There is just one point in app.html that is different: in the getting started, the code is design for iOS. To use the material design stylesheet (like I did), replace <div class="pages navbar-through toolbar-through"> by <div class="pages navbar-fixed toolbar-through">. Otherwise, the content of the page will partially be in the navbar (due to a missing padding-top: 46px).

main.js contains nothing particular, it's just the standard main provided by the skeleton.

Since navigation in the app will rely on the Aurelia router, we have to defines our route in app.js:

configureRouter(config, router) {
     config.title = 'Aurelia';
     config.map([
         {
             route: ['', 'todos'],
             name: 'todos',
             moduleId: 'pages/list-todos/list-todos',
             nav: true,
             title: 'todos'
         }, {
             route: ['todo', 'todo/:id'],
             name: 'todo',
             moduleId: 'pages/todo/todo',
             nav: true,
             title: 'View Todo',
         }
     ]);

     this.router = router;
 }

And to navigate, I use either:

this.router.navigateToRoute('todo', {id: todo.id});

To view/edit a precise todo. This allows me to get the todo with the given id from storage. To add a new todo, I use:

this.router.navigate('/todo');

To navigate to the route without the parameter.

Concerning the templates, nothing fancy. Just think to put your code in a div with either the list-block or the content-block class depending on what you want to do:

<ul>
    <li class="item-content" repeat.for="todo of todos" click.delegate="viewTodo(todo)">
       <div class="item-inner ${todo.done === true || todo.done === 'true' ? 'done' : ''}">
           ${todo.title}
       </div>
       <p><a href="#" class="button button-fill" click.delegate="toggleDone(todo)">Toggle Done</a></p>
    </li>
</ul>

We use Aurelia's binding mechanism to make the link with the JavaScript:

We repeat the element with repeat.for="todo of todos"
Bind a click event to a function with click.delegate
Use string interpolation to display the values with ${todo.title} or to update the value of a tag with class="item-inner ${todo.done === true || todo.done === 'true' ? 'done' : ''}". The part from ${ to } will be replaced by the value of the expression computed by Aurelia.

The main difference with the ionic app is that I used localForage in a custom class to store the todos. localForage is a small library by Mozilla that uses localStorage if neither IndexedDB nor WebSQL is supported with an API close the localStorage. With ionic, you have a simple way to use SQLite on the phone and WebSQL on your browser with nice capabilities for SQL queries but that's a ionic thing. Since behind the scenes, it relies on Cordova, it should be possible to use it with Aurelia and Framework7 but it felt overkill for my small test.

On the page to edit todos, nothing fancy. I create a nice looking form with the good classes. The structure is a little bit complicated but is necessary to have the proper theme. The rest is just classic html (here the code for one field):

<li>
    <div class="item-content">
        <div class="item-inner">
            <div class="item-title label">Title</div>
            <div class="item-input">
                <input type="text" placeholder="Title" value.bind="todo.title" required>
            </div>
        </div>
    </div>
</li>

Just note that in forms, Aurelia will do two way data bindings with value.bind whereas everywhere else it will do one way data bindings by default for performance reasons.

In the JavaScript, we just have to load the proper todo:

activate(params) {
     this.todo = {};
     if (params.id) {
         this.storage.getTodo(params.id)
             .then(todo => this.todo = todo);
     }
 }

To allow the todo to be saved, I do a basic check on the title (it must not be empty). No message saying that the field is required if the user touches it is displayed. That's the other import difference with ionic. It is due to a bug in aurelia-validation about how translations are loaded with webpack. This is clearly behind what I did in ionic but I'll update the code and this article once it is fixed.

Update: I created a new post about validation and Aurelia. The code samples used in it are based on this application You can see it here.

get canSave() {
     return this.todo.title !== undefined && this.todo.title.length > 0;
 }

Bonus

It's not useful for my application, but I wanted to show how to use Framework7's JavaScript should you need it. In a javascript file (you can name it f7.js) put the code below:

// Load JS for webpack
import 'framework7';


// Create F7 object
export const F7 = new Framework7({
    material: true,
});

You can then use it as you would expect:

import { F7 } from 'f7'
import {inject} from 'aurelia-framework';

@inject(F7)
export class ListTodosPage {

  constructor(f7) {
     this.f7 = f7;
  }
}

And in your HTML:

<a click.delegate="f7.openPanel('left')" href="#" class="button button-big button-fill">Open Left Panel</a>

To see a usage, go here for my code and there for the associated template.

Conclusion

Both application have roughly the same amount of code: 164 lines of JS and 40 lines of HTML for ionic and 143 lines of JS and 103 lines of HTML for Aurelia/Framework7. Since my storage service is about 40 lines that are handled by directly by ionic, I have about 100 lines of JS code for Aurelia. There is more HTML but it's mostly the bootstrap required for Framework7.
I find Aurelia lighter and easier to use. Even if typescript has some nice features like type error detection and a better auto-completion (since it can be based on the type of the object), it looks Javaish with type declarations and interfaces. In addition to that, the syntax for the template is weird (and it breaks some HTML validators like the one integrated in NetBeans IDE). I've used it for some days now, so I begin to get use to it but with my fist experience with Aurelia I didn't have this incomfortable moments at first: templating is plain and simple tag.bind (default) or tag.two-way or tag.one-way depending on what you want to do, string interpolation works everywhere and is just plain ES6 template strings.
ionic uses a lot of custom elements and tags. I guess the goal is to make the code less verbose, but sometime it is confusing. For instance, to make a text input field, you use <ion-input type="text" />. So logically to make a checkbox, I tried <ion-input type="checkbox" /> (which doesn't work) instead of <ion-checkbox [ngFormControl]="done" />. On the contrary, Framework7 is just plain HTML. You just have to respect a certain structure (well detailed on the documentation) and put the proper classes on your element. So it can integrate with pretty much everything and it's quite easy to learn.
ionic has some good bindings with Corodova. For instance its ability to use WebSQL on your browser but SQLite on your phone. There's no easy way (yet?) to do that with Aurelia/Framework7. Maybe Aurelia-Interface will have that too.
the startup time of the application was quite slow (several seconds) with both solutions. Maybe there is a way to improve that, I admit I haven't dug into it yet.
webpack is awesome ;-)

In the end, ionic has a good cli, documentation and some bindings for Cordova which make it complete and interesting. But in my opinion, the Aurelia/Framework7 feels more natural mostly because of the weird design choices of Angular2 and ionic has lots of custom element over HTML.

Maybe I should start something (skeleton and command line tool) to work with Aurelia, Framework7 and Cordova. If there's no news of Aurelia-Interface soon, I think it's highly probable that I'll try. I'll update this post if I do (or decide not to).