> For the complete documentation index, see [llms.txt](https://aurelia-1.gitbook.io/v1-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://aurelia-1.gitbook.io/v1-docs/introduction/contact-manager-tutorial.md).
# Contact manager tutorial
Now that you've got the basics down, you need to learn how to use the CLI, build a more complex app and get a solid knowledge foundation for real-world work.
Ready to dive deeper? Let's build a contact manager app to showcase Aurelia's power and versatility. This tutorial will take you beyond the basics, introducing key features and practical techniques you'll use in real-world projects. We'll also get you comfortable with the CLI, setting you up for more complex development work.
## Setting up your machine
Before diving into Aurelia, you'll need to set up your development environment. This process is straightforward:
1. Install Node.js if you haven't already.
2. Use npm (or your preferred package manager) to install the Aurelia CLI.
If you've already installed the Aurelia CLI, feel free to skip ahead to the next section.
For detailed installation instructions, check out our [Quick Start](broken://pages/kiWMNkUajy31cDQTHPJ5) guide.
## Creating a new Aurelia project
Let's create our contact manager app. From the command line, run:
```
au new
```
You'll see several options. Name your project "contact-manager" and choose either "Default ESNext" or "Default TypeScript" based on your preference. (Skip the "Custom" option for this tutorial.)
When prompted to install dependencies, hit enter to accept the default "yes".
Your project is ready after installation (which may take a few minutes). Navigate to the project folder in your terminal and launch it with:
```
au run --open
```
This command runs the app, opens a browser tab, and watches for source changes. You'll see "Hello World!" in your browser if everything's set up correctly.
### Adding required assets
In this tutorial, we'll use a mock in-memory backend. To save time, we've prepared the CSS and some utility functions in advance. Before we start coding, download these essential assets and add them to your project.
[Download the Contact Manager Assets](https://aurelia.io/downloads/contact-manager-assets.zip)
Once you've downloaded the zip file, extract it, and you'll find three files:
* `web-api.js` - The fake, in-memory backend.
* `utility.js` - Some helper functions used by the app.
* `styles.css` - The styles for this app.
Copy all of these files to your project `src` folder. TypeScript users should also rename the file extensions from `.js` to `.ts`.
## Building the application shell
{% hint style="warning" %}
Before proceeding, please ensure you are familiar with the concepts introduced in [Aurelia for new developers](broken://pages/Q2dzIoMHSjRH5HhE5hYz) or have some basic experience with Aurelia.
{% endhint %}
Let's start by looking at a picture of the final product of this tutorial. It will help us to see the application's structure and the pieces we need to build.
Our app layout consists of a header, a contact list on the left, and a detail pane. This structure forms our app's shell. Let's set it up.
First, we'll configure the `App` class with a router. This allows browser history to reflect the selected contact, enabling smooth navigation. Update your `app.ts/js` with this code:
{% tabs %}
{% tab title="Javascript" %}
```javascript
import {PLATFORM} from 'aurelia-pal';
export class App {
configureRouter(config, router){
config.title = 'Contacts';
config.options.pushState = true;
config.options.root = '/';
config.map([
{ route: '', moduleId: PLATFORM.moduleName('no-selection'), title: 'Select' },
{ route: 'contacts/:id', moduleId: PLATFORM.moduleName('contact-detail'), name:'contacts' }
]);
this.router = router;
}
}
```
{% endtab %}
{% tab title="TypeScript" %}
```typescript
import {Router, RouterConfiguration} from 'aurelia-router';
import {PLATFORM} from 'aurelia-pal';
export class App {
router: Router;
configureRouter(config: RouterConfiguration, router: Router){
config.title = 'Contacts';
config.options.pushState = true;
config.options.root = '/';
config.map([
{ route: '', moduleId: PLATFORM.moduleName('no-selection'), title: 'Select' },
{ route: 'contacts/:id', moduleId: PLATFORM.moduleName('contact-detail'), name:'contacts' }
]);
this.router = router;
}
}
```
{% endtab %}
{% endtabs %}
{% hint style="warning" %}
After changing the code above, if you immediately try to compile, you may receive a compile error on your unit tests because the sample test references the `App` class, which we just changed. To address this, remove the dummy unit test.
{% endhint %}
Adding routing to your Aurelia app is straightforward. Include a `configureRouter` method in your `App` class. This method receives two parameters: `RouterConfiguration` and `Router`.
Use the `map` method on the configuration object to set up your routes. Each route requires at least two properties:
1. `route`: The URL pattern to match
2. `moduleId`: The module to load when the route is matched
In this setup, we've defined two routes:
1. An empty route (`''`) that loads the `no-selection` module when no specific route is matched.
2. A `contacts/:id` route that loads the `contact-detail` module when a specific contact is selected. The `:id` part is a parameter that can be used to identify the selected contact.
This configuration allows for a default view and a detailed contact view in your application.
{% hint style="info" %}
Did you notice the calls to `PLATFORM.moduleName(....)`? This special API is used in Aurelia Webpack projects to allow Webpack to identify strings that represent modules. This enables Webpack to include the referenced module in the built package.
{% endhint %}
Two key points to note in this configuration:
1. The `config.title` property sets a base title for the browser's document. You can also set titles on individual routes. When you do, the router's title and the matched route's title combine to form the final document title.
2. The lines `config.options.pushState = true;` and `config.options.root = '/';` are optional. They enable pushState-based routing. Without these, Aurelia defaults to hash-based routing, which works even on older browsers like IE9.
Routing examples:
* PushState: `http://localhost:8080/contacts/1`
* Hash-based: `http://localhost:8080/#/contacts/1`
The second route introduces a name property. This allows us to reference the route by name later on, eliminating the need to repeat the route pattern throughout our code.
With our navigation structure in place, let's set up the visual layout. Update your `app.html` file with this markup:
```html
Contact List Placeholder
```
The structure of this view reveals some key Aurelia concepts. At the top, you'll notice `require` elements. These function similarly to ES2015's `import` syntax, allowing you to bring in resources like custom styles into your view.
The main body of the view consists of a navbar and a two-column layout. The first column contains a placeholder for our contact list, while the second houses the `router-view` custom element. This Aurelia-provided element indicates where the current route should be rendered, offering flexibility in your application's layout.
Note that when you have a `configureRouter` method in your view-model, your view must include a `router-view`.
To complete our application shell setup, we need to install and import Bootstrap. While we're using Bootstrap in this tutorial for styling, feel free to use any CSS framework you prefer in your own projects.
To install Bootstrap, run the following command:
```sh
npm install bootstrap
npm install font-awesome
```
Next, we need to import it into our `main.ts/js` by adding the following line to the top of the file:
```javascript
import 'bootstrap/dist/css/bootstrap.css';
import 'font-awesome/css/font-awesome.css';
```
{% hint style="info" %}
Whenever you install new dependencies used in your app, make sure to restart the `au run` command, in order to have the CLI re-bundle your freshly added dependencies.
{% endhint %}
## Creating the default route
If you run the application now, using `au run`, you'll see a compile error similar to:
```sh
ERROR in ./src/app.js
Module not found: Error: Can't resolve 'contact-detail' in '/contact-manager/src'
```
This behavior is normal. We've used `PLATFORM.moduleName(....)` in our route configuration, but we haven't created the actual modules yet. Let's fix that now. Create a new file called no-selection.js in the src folder and add this code:
{% tabs %}
{% tab title="Javascript" %}
{% code title="no-selection.js" %}
```javascript
export class NoSelection {
constructor() {
this.message = "Please Select a Contact.";
}
}
```
{% endcode %}
{% endtab %}
{% tab title="TypeScript" %}
```typoscript
export class NoSelection {
message = "Please Select a Contact.";
}
```
{% endtab %}
{% endtabs %}
Now, let's create a simple "no selection" screen. This will prompt users to choose a contact when none is selected.
Create a new file named `no-selection.html` in your `src` folder with this content:
```html
${message}
```
This container applies basic styling to display our user message.
Now, let's create a placeholder for our contact detail screen. This will keep our build happy. In the src folder, add a new file called `contact-detail.ts/js` with this code:
```javascript
export class ContactDetail {
}
```
With this in place, you can now run your application. If you haven't stopped/restarted it after editing the bundles, then you must do that now. When you run the application, you should see something similar to this:
## Creating the contact list
Now that we've set up our application's basic structure and routing, it's time to make things more interesting. Let's replace that placeholder div with a proper contact list by creating a custom element.
In Aurelia, building custom elements follows the same pattern as creating your `App` component or routed components. This consistency is a hallmark of the framework. To get started, create a new file called `contact-list.ts/js` and add the following code:
{% tabs %}
{% tab title="Javascript" %}
```javascript
import {WebAPI} from './web-api';
import {inject} from 'aurelia-framework';
@inject(WebAPI)
export class ContactList {
constructor(api) {
this.api = api;
this.contacts = [];
}
created() {
this.api.getContactList().then(contacts => this.contacts = contacts);
}
select(contact) {
this.selectedId = contact.id;
return true;
}
}
```
{% endtab %}
{% tab title="TypeScript" %}
```typescript
import {WebAPI} from './web-api';
import {inject} from 'aurelia-framework';
@inject(WebAPI)
export class ContactList {
contacts;
selectedId = 0;
constructor(private api: WebAPI) { }
created() {
this.api.getContactList().then(contacts => this.contacts = contacts);
}
select(contact) {
this.selectedId = contact.id;
return true;
}
}
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
We use a dashed naming convention to separate the words *contact-list* as our custom element name. The name of the class instead should be defined by using the UpperCamelCase version *ContactList*.
{% endhint %}
The `ContactList` view-model showcases a few key Aurelia features. It uses dependency injection, a core Aurelia concept, to manage class dependencies. Our `ContactList` class depends on the WebAPI class, which Aurelia will automatically provide when instantiating ContactList.
The `created` method demonstrates Aurelia's component lifecycle. By implementing this method, we hook into the stage where both view-model and view are ready. Here, we fetch the contact list from our API and store it for binding in the view.
Lastly, we have a `select` method for contact selection, which we'll explore further when we look at the view. Speaking of which, let's create a `contact-list.html` file for our view:
```html
