Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 39 ยท Getting Started

Your First Ember Page

Build a first Ember page step by step. Generate a route, edit its template, link pages together and see how the router, template and component work as one flow.

Reading about a framework only goes so far. In this lesson you will walk through the steps of adding pages to a fresh Ember app: a home page, an about page and a link between them. Along the way you will see the three files that make up almost every Ember screen.

Real versus stand-in. The bash, js and hbs code blocks without a Run button are real Ember code to type into your own project. The runnable blocks are plain JavaScript stand-ins that imitate what Ember does with those files (matching a URL, filling a template) so you can watch the mechanism work.

Start from a clean slate

Create the app with the welcome page removed, then start the server:

Terminal
npx ember-cli@latest new my-first-app --no-welcome
cd my-first-app
npm start

Open http://localhost:4200. The page is blank, and that is correct: nothing is defined yet.

Step 1: the application template

app/templates/application.gjs is wrapped around every page. It is the place for a header, a footer and the spot where the current route will show up, marked with {{outlet}}.

JavaScript
// app/templates/application.gjs
import { pageTitle } from 'ember-page-title';

<template>
  {{pageTitle "My First App"}}

  <header>
    <h1>My First App</h1>
  </header>

  <main>
    {{outlet}}
  </main>
</template>

Save the file. The browser updates by itself. {{outlet}} is a placeholder: when the URL changes, the template of the matching route is rendered there.

Step 2: a home page

Generate the index route:

Terminal
ember generate route index

You get app/routes/index.js, app/templates/index.gjs and a test. The route file can stay as the generator wrote it. Edit the template:

JavaScript
// app/templates/index.gjs
<template>
  <h2>Welcome</h2>
  <p>This page lives at the root URL, <code>/</code>.</p>
</template>

Every app has an implicit index route for /, so you do not need to declare it in the router.

Step 3: an about page

Terminal
ember generate route about

The generator adds a line to app/router.js:

JavaScript
// app/router.js
import EmberRouter from '@ember/routing/router';
import config from 'my-first-app/config/environment';

export default class Router extends EmberRouter {
  location = config.locationType;
  rootURL = config.rootURL;
}

Router.map(function () {
  this.route('about');
});

Now fill in app/templates/about.gjs:

JavaScript
<template>
  <h2>About</h2>
  <p>I am learning Ember. The URL <code>/about</code> shows this page.</p>
</template>

Visit http://localhost:4200/about. If you reload the page directly on /about, it still works, because the development server sends every URL to index.html and Ember's router takes over.

Never write <a href="/about"> for links inside your app; that would reload the whole page. Use the LinkTo component instead:

JavaScript
// app/templates/application.gjs
import { LinkTo } from '@ember/routing';
import { pageTitle } from 'ember-page-title';

<template>
  {{pageTitle "My First App"}}

  <header>
    <h1>My First App</h1>
    <nav>
      <LinkTo @route="index">Home</LinkTo>
      <LinkTo @route="about">About</LinkTo>
    </nav>
  </header>

  <main>
    {{outlet}}
  </main>
</template>

@route takes the route name, not the URL. If you later change the URL of a route, the links keep working. LinkTo also adds the class active to the link of the current page, so you can style it.

Step 5: show something dynamic

Templates are not only static text. Values come from the route's model or from a component. Edit app/routes/index.js:

JavaScript
import Route from '@ember/routing/route';

export default class IndexRoute extends Route {
  model() {
    return { name: 'visitor', visits: 3 };
  }
}

And show it:

JavaScript
// app/templates/index.gjs
<template>
  <h2>Welcome, {{@model.name}}</h2>
  <p>This is visit number {{@model.visits}}.</p>
</template>

Route templates receive the model as @model. Mustaches {{ }} print a value and escape any HTML in it, which protects you from cross-site scripting by default.

What happens when you visit a URL

The following stand-in imitates the three steps: the router finds the route for a path, the route builds a model, and the template fills its placeholders. It is not Ember's code, only the idea in about thirty lines.

JS URL, route, model, template

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The active class that LinkTo adds is simple to imitate. This block builds the navigation HTML for a given current route:

JS Which link is active?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Troubleshooting a first app

  • A page is blank. Check the browser console and the terminal. Typos in router.js or a template that does not export a <template> are the usual causes.
  • A link does nothing. @route must match a name declared in router.js (or index).
  • Template changes do not show. The dev server must be running; save the file and wait for the rebuild message.
  • 404 on reload in production. Your web server must send every path to index.html. See the deployment chapter in the track.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does {{outlet}} do in application.gjs?

    The application template wraps every page. The outlet is the slot where child route templates appear.
  2. 2. Why use LinkTo instead of an a tag with href for in-app navigation?

    LinkTo uses the router to transition between routes, so the app keeps its state and only the needed templates are re-rendered.
  3. 3. In a route template, how do you read the object returned by the route's model() hook?

    Route templates receive the model as the argument @model.
  4. 4. Which file lists the URLs of the app?

    Router.map in app/router.js declares routes. The index route for / is implicit.

Summary

  • application.gjs wraps every page and contains {{outlet}}.
  • ember generate route name creates a route, a template and a test, and adds the route to router.js.
  • Link inside the app with <LinkTo @route="name">, which prevents full page reloads.
  • A route's model() hook returns data; the template reads it as @model.

Next: Modern JavaScript You Need for Ember