How to Create Ember.js Entities from Scratch

As part of my internship at Nearsoft, I took a deep dive into Open Source projects. Having some experience with backend development (using Express.js as the web framework) I thought it’d be a great idea to level up by diving into Ember.js, understanding the framework and hope to contribute in some way.

Here’s how to generate entities using Ember.js.

Transitioning from the world of mechatronics engineering, domotics, and IoT devices to the world of software development has been one of the most rewarding and challenging experiences in my life. I had never been exposed to this amount of information before, not even in college. There’s a lot to learn: languages, libraries, frameworks, OS, VCS, and database are just some simple things any developer should be aware of.
I chose JavaScript to start. It is widely being used and has a lot of libraries available. I also got into the MERN stack (MongoDB, Express.js, React.js, Node.js) to develop a couple of projects.

The first thing a did was follow the basic tutorial. Two minutes later I had my application running, and it even had tests. I was surprised, “Are you serious? I’ve spent days doing this exact same thing, it’s even better organized.. and it’s tested!”

What Is Ember?

Ember.js is a Javascript frontend framework built for productivity. It’s designed to help build websites with rich and complex user interactions. It provides developers with many features to manage complexity in modern web applications. It also acts as an integrated development toolkit that enables rapid iteration.

With Ember’s Handlebars integrated templates that update automatically when data changes, developers write a lot less code. It’s main goal is for developers to focus on what makes their app special, not wasting their time making trivial choices.

Some of the features provided by Ember.js are,

Ember CLI

Is a robust development toolkit to create, develop, and build Ember applications

Routing

Enables developers to drive de application state from the URL

Templating engine

Uses Handlebars syntax to write your application’s templates

Ember Data

Provides a consistent way to communicate with external APIs and manage application state

Ember Inspector

Is a browser extension to inspect your application live

Ember’s First Commands

Let’s start with Ember CLI, Ember’s command line utility, and how it generates many of the entities that you’ll need in your app (routes, models, components, controllers, etc.)

First, we need to install Ember. We can do it with a single command using npm (make sure Node.js and npm are installed),

npm install -g [email protected]

The next step is creating our App. To create a new project using Ember CLI, we need to use the new command. Let’s make an app called ember-quickstart.

ember new ember-quickstart

This command generates a new directory called ember-quickstart and sets a new Ember application inside it. The application will include everything you need to build production-ready web applications: a development server, template compilation, JavaScript and CSS minification, and ES2015 features via Babel. With the new command, a project structure is created with various files and directories,

|--app
|--config
|--node_modules
|--public
|--tests
|--vendor
ember-cli-build.js
package.json
README.md
testem.js

app

Is where folders and files for routes, components, templates, styles and models are stored. Coding happens in this folder

config

Contains the environment.js, where you can configure settings for your app

node_modules

Is where npm packages, listed in package.json, are installed. Ember CLI addons are also installed here

public

Is the directory that contains assets such as images and fonts

tests

Is where automated tests go

vendor

Is the directory where front-end dependencies that are not managed by Bower go

ember-cli-build.js

Is the file that describes how Ember CLI should build our app

package.json

Is the file that maintains the list of current npm dependencies for the app

testem.js

Is the file where Ember CLI’s test runner testem directory is configured

Let’s Do It!<.h2>

Let’s run the project to confirm everything is working. Change directory (cd) into the application directory and start the development server by typing,

cd ember-quickstart
ember serve

Navigate to http://localhost:4200 and you’ll see the default welcome screen. Edit the app/templates/application.hbs and change it to the following,

<h1>Ember Application</h1>
{{outlet}}

Let’s build an application that shows a demo page. The first step is to create a route.

Routes are the different pages that make up your application. To generate a route, just type,

ember generate route demo

If the route was generated successfully, you’ll see an output that tells you the generator has created the following,

• A route file at app/routes/demo.hbs
• A template at app/templates/demo.js that is to be displayed when the user visits /demo
• An entry point in the application’s router, located in app/router.js
• A unit test for this route, located at tests/unit/routes/demo-test.js

Open the newly created template in app/templates/demo.hbs and add the following HTML,

<h2>Demo Page</h2>

Navigate to http://localhost:4200/demo and you should see the text you put in the index.hbs template, below the <h1> from the application.hbs template.

With just two commands we’ve created a very basic app and its first index route, as well as all the files you might need to test, develop, and build the application. Amazing, isn’t it? It really saves a lot of time and effort.

But, how does it create all those files and how can we customize what files are created?

Ember CLI’s Generators and Blueprints

Ember CLI ships with Blueprints, snippet generators for many of the entities. To see a list of available blueprints, run ember generate --help. Take a look at the /blueprints directory in the Ember’s repository at GitHub. You’ll see all the blueprints Ember uses to create entities through the generate command.

Blueprints follow a very simple structure. The route blueprint is as follows,

blueprints/route/
|-------- files
|	|-------- __root__
|		|-------- __path__
|			|-------- __name__.js
|		|-------- __templatepath__
|			|-------- __templatename__.hbs
|-------- index.js

blueprints/route-test/
|-------- mocha-0.12-files
|	|-------- tests
|		|-------- unit
|			|-------- __path__
|				|-------- __test__.js
|-------- index.js

Ember CLI takes this blueprints and, when generating a new route, modifies the files’ names and content with the help of the fileMapTokens method found in the index.js file which contains the installation configuration. It can be modified to create a customized installation. The files directory contains templates for all the files to be installed into the target directory.

The fileMapTokens method, responsible of modifying the blueprint’s default names is,

fileMapTokens: function() {
 return {
   __name__: function (options) {
     if (options.pod) {
       return 'route';
     }
     return options.locals.moduleName;
   },
   __path__: function(options) {
     if (options.pod) {
       return path.join(options.podPath, options.locals.moduleName);
     }
     return 'routes';
   },
   __templatepath__: function(options) {
     if (options.pod) {
       return path.join(options.podPath, options.locals.moduleName);
     }
     return 'templates';
   },
   __templatename__: function(options) {
     if (options.pod) {
       return 'template';
     }
     return options.locals.moduleName;
   },
   __root__: function(options) {
     if (options.inRepoAddon) {
       return path.join('lib', options.inRepoAddon, 'addon');
     }

     if (options.inDummy) {
       return path.join('tests', 'dummy', 'app');
     }

     if (options.inAddon) {
       return 'addon';
     }

     return 'app';
   }
 };
}

According to fileMapTokens in route/index.js, installation of the route is as follows,

• The __name__ token is substituted with the module name. When you invoke ember generate route demo then __name__.js becomes demo.js
• The __path__ token is substituted with the blueprint name at install time. When the user invokes ember generate route demo then __path__ becomes routes
• The __templatepath__ token is substituted with templates
• The __templatename__.hbs token is substituted with the module name. When you invoke ember generate route demo then __templatename__.hbs becomes demo.hbs
• The __root__ token is substituted with either app or addon, depending on where it’s generated

If you remember, a test is also installed when the generate route is invoked. According to the fileMapTokens found at route-test/index.js, the test installation is as follows,

• The __path__ token is substituted with the blueprint name at install time. When the user invokes ember generate route demo then __path__ at tests/unit/ becomes routes
• The __test__ token is substituted with the module name and appended with -test at installation. When you invoke ember generate route demo then __test__.js at tests/unit/routes/ becomes demo-test.js

Up to this point, we know how the route, template, and test files are created. We still need to create an entry point in the application’s router. Without it, we wouldn’t be able to access our template.

The application’s router is located at app/router.js. The updateRouter method, in blueprints/route/index.js is used to update the router by,

• Creating a new EmberRouteGenerator instance (from ember-router-generator.js dependency found in node_modules)
• Call the add method
• Write the route to the router.js file.

The modified code in the router should look as follows,

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

Once the route is added to the router, we’re able to access the template through http://localhost:4200/demo. All other routes will be added to this file as well.

Ember Magic

As a result of invoking ember generate route demo we’ve added the following folders and files to our project (explained above),

app/
|-------- routes
|	|-------- demo.js
|-------- templates
|	|-------- demo.hbs
|-------- router.js (modified)

tests/
|-------- unit
|	|-------- routes
|		|-------- demo-test.js

Before using Ember, the backend structure of my previous projects would have taken more time and look very differently. With this tool, I might as well handle all that repetitive tasks to Ember and follow it’s philosophy by focusing on what makes my app special, not wasting my time making trivial choices.

Taking a peek under the hood takes away the magic, sure, but once you understand how the magician does his tricks, you can become the magician! Or at least try. Understanding how things are done gives you the ability to change them, you can customize how the blueprints are transformed and installed into your project.

But we’ll leave all that customization for another time.