Getting Started with Aurelia: Front-end JavaScript Framework

Aurelia is a modern, front-end JavaScript framework for building browser, mobile, and desktop applications (as advertised). It focuses on aligning closely with web platform specifications, using convention over configuration, and having minimal framework intrusion. Benefits of choosing AureliaJs over frameworks like Angular has been described here. Give it a read.

This project is hosted at gihub.

nishanc/weather-app

Let’s create a skeleton app which we will convert into a Weather app. Following the documentation, install NodeJs version 10 or above and Git. Once you have the prerequisites installed, you can install the Aurelia CLI itself. From the command line, use npm to install the CLI globally.

npm install -g aurelia-cli

Next, still inside the terminal, navigate to a place on your computer where you want the project to live. You can then invoke the Aurelia CLI to generate the working skeleton of your app

au new

The CLI tool will then guide you through the creation of your application. The first question asks you for the name of your application, I have named it weather app.

Next you will be asked to select a choice of default setup — choose option 2. Default TypeScript here.

Next you will be asked to install npm dependencies, select Yes to this.

Once this is done, you will get a message as “Your Project “weather-app” Has Been Created!”. Now using the terminal navigate into weather-app directory. Execute command au run --watch to start the development server.

Then navigate to http://localhost:8080, if everything went well, you will see a big “Hello World!” in your browser.

I’m using visual studio code, you can use any other editor you like, let’s look at the file structure.

We’re mainly going to be concerned with the src folder, as it's where all of our components, service classes, and templates are going to live and will contain the bulk of our code. Looking in the src folder, you'll see the app.ts and app.html files. This is essentially the entry point to our application and is where the rest of our application will grow from. To start with, let's create our first component — the header.

To invoke the component generator, run this from the command line. (or use this extension I created)

au generate component Header

You will be asked which subfolder you want the component to be created in. You can just press ‘Enter’ if you want the component to be created inside the src folder, but I'm going to create components such as this inside a subfolder called 'components', just to keep them nice and organized. Just type /components and hit ‘Enter’.

You will notice there are two files, header.html and header.ts inside the src/components folder. Replace the contents of header.html with the following to create a basic Bootstrap navigation bar.

So far, this is mostly just Bootstrap’s standard markup for a responsive navigation bar. Notice the ${appTitle} directive in there? We're going to bind that from the 'controller' of this template, which can be found in the header.ts file. Replace its contents with the following

Continuing on, open app.html in the root of the src folder and replace its contents with the following, which will display the Header component on the page.

Notice that it brings in app.css, which just has some minor styling in it to put some distance in between the header and the content. Create the file app.css in the same directory as your app template and give it the following content.

Next, let’s bring in those bootstrap styles. Open index.ejs in the root of the project and add in the stylesheet inside the head tag so that it looks like this. (for my application, I’ve chosen to use the Solar theme, but you can use any of the themes that you like, as all of the markup should be compatible). Notice that we’ve also included script tags for Bootstrap(4.4.1) and jQuery so that the responsive navigation bar works correctly across smaller devices.

At this point, you should be able to see your application with a very basic header showing the application title and some basic coloring coming from your chosen Bootswatch styles.

Notice, however, that the HTML title of your application is not quite right — by default, it’s set to ‘Aurelia Navigation Skeleton’. We can change that to something a little more appropriate by opening webpack.config.js and altering line 17,

const title = 'Aurelia Navigation Skeleton';

to whatever title we like, in my case ‘Weather App’

Next big problem! where to get weather data? we will user OpenWeatherMap for this and their API https://openweathermap.org/forecast5. You need to create a free account and obtain an api-key if you want to follow along.

The API call looks like this.

https://api.openweathermap.org/data/2.5/forecast?q={city name}&appid={your api key}

We allow users to get forecast by city name. Create a new folder inside src named services and create a new file as weather-service.ts and add following code.

Make sure to replace <your api key> with, well, your API key. And install aurelia-http-client from npm. Read more about http-client here.

npm i aurelia-http-client

We will display the results in our home page, which is app.html If you want you can create a separate route for that, but to keep this tutorial simple I’m not going to configure routing. It is very straight foreword process actually, you can read about it and authentication here.

Open up app.ts and insert this code snippet.

At this point we’re just logging the response to the console and sending a hard coded city. We will change it later. The activate() method gets called when that route is hit. It is like the OnInit() in Angular. That’s why we are calling our function forecast() inside the activate() method.

So go to http://localhost:8080/ and open up a console and see if everything is working as expected.

So far so good. All we need now is UI elements which will get the city name from the user and display the results.

First we will create a search box and get user input (city name), and try to call the API with that city name. Add/update markup in app.html as follows.

Notice the submit.delegate in form tag points to the forecast() method we have in our app.ts and value.bind in input tag binds the value with city variable which we will add to the app.ts as follows.

Change the code in app.ts so that when we call the WeatherService we send the city taken from the user.

At this point, when you type a city name in the search box and hit ‘Search’ you should see respective results gets printed on the console. Let’s display the results to the user next.

The API returns weather forecast for 5 days with data every 3 hours by city name. We will display all of them in a table. First we need to cast the JSON response to a typescript interface. I have used http://json2ts.com to do this and created weather.ts in a folder called interfaces. Needless to say you have to play with the response JSON and understand it’s structure.

This will cast the response to WeatherObject in weather-service . Add / update following 3 lines in weather-service.ts

import { WeatherResponce } from 'interfaces/weather';
var forecast: WeatherResponce = JSON.parse(httpResponse.response);
resolve(forecast.list);

Add/update app.ts as follows.

And to display the forecastlist alter the app.html as follows.

Notice the repeat.for=”item of forcastlist” which will iterate over the list and get the fields out from the response.

That’s it, if you came this far, well done!, if you can’t get it to work, just play around a little bit, you will figure it out. I will list down the sources which were helpful for me.

Consider helping me out!

Aurelia - Binding Behavior

Creating your first Aurelia app: From authentication to calling an API