604
/*
* -----------------------
* Ember.js Cheatsheet
* -----------------------
*
* Docs: https://guides.emberjs.com/
* Quick start: https://guides.emberjs.com/current/getting-started/quick-start/
*
* Table of contents
* -------------------
* 01 | Installation
* 02 | Ember CLI
* 03 | Directory layout
* 04 | Routes
* 05 | Templates
* 06 | Components
* 07 | Models
* 08 | Services
* 09 | Testing
* 10 | Addons
* 11 | Configuration
* 12 | Community
*
*/
/*
* 01 | Installation
* --------------------------------------------------------------
* Getting started with Ember is easy. Ember projects are created
* and managed through our command line build tool Ember CLI.
*/
```
npm install -g ember-cli
ember new <application-name>
ember serve
```
/*
* 02 | Ember CLI
* --------------------------------------------------------------
* Ember CLI is the Ember.js command line utility that provides a
* fast Broccoli-powered asset pipeline, a strong conventional
* project structure, and a powerful addon system for extension.
*
* Among the principal features of Ember CLI are:
- Project/Addon creation: create new projects quickly without having to worry about project structure;
- Build pipeline: asset compilation, finger-printing and more out of the box;
- Generators: use the built-in generators and get files that follow the latest practices, and matching tests;
- Ember Addons: extend both your application and Ember CLI itself with community solutions. Also an excellent
way to easily integrate 3rd party libraries into your Ember app.
*/
Basic commands
Command | Aliases | Description
--------------------------------------------------
```
ember new | | Create new project with the provided name (ex. ember new <app-name>)
ember server | ember s | Starts development server (default port is 4200)
ember test | ember t | Run tests in CI mode
ember generate | ember g | Run generator
ember destroy | ember d | Remove code created by generator
ember help | ember h | Get more info on available cli command
ember install | ember i | Install given addon into project and save to package.json
ember | | List available cli commands
```
Useful commands
```
ember s --proxy <proxy-url>
ember s --port <port>
```
/*
* 03 | Directory Layout
* --------------------------------------------------------------
*
* Layout of the root folder */
app/
` This is where folders and files for models, components, routes, templates and styles are stored. The majority of your coding on an Ember project happens in this folder. `
config/
` The config directory contains the environment.js where you can configure settings for your app. `
node_modules/
` This directory is from npm. npm is the package manager for Node.js. Ember is built with Node and uses a variety of Node.js modules for operation. The package.json file maintains the list of current npm dependencies for the app. Any Ember CLI addons you install will also show up here. `
public/
` This directory contains assets such as images and fonts. `
vendor/
` This directory is where front-end dependencies (such as JavaScript or CSS) that are not managed by NPM go. `
tests/testem.js
` Automated tests for our app go in the tests folder, and Ember CLI's test runner testem is configured in testem.js. `
ember-cli-build.js
` This file describes how Ember CLI should build our app. `
package.json
` Packages listed in package.json are installed in the node_modules directory. `
/*
* Layout of the app directory */
adapters/
` Adapters with the convention adapter-name.js. `
components/
` Components with the convention component-name.js. Components must have a dash in their name. So blog-post is an acceptable name, but post is not. `
controllers/
` Controllers behave like a specialized type of Component that is rendered by the router when entering a Route. `
helpers/
` Helpers with the convention helper-name.js. Helpers must have a dash in their name. Remember that you must register your helpers by exporting makeBoundHelper or calling registerBoundHelper explicitly. `
models/
` Models with the convention model-name.js. `
routes/
` Routes with the convention route-name.js. Child routes are defined in sub-directories, parent/child.js. To provide a custom implementation for generated routes (equivalent to App.Route when using globals), use app/routes/basic.js. `
styles/
` Contains your stylesheets, whether SASS, LESS, Stylus, Compass, or plain CSS (though only one type is allowed, see Asset Compilation). These are all compiled into <app-name>.css. `
templates/
` Your HTMLBars templates. These are compiled to /dist/assets/<app-name>.js. The templates are named the same as their filename, minus the extension (i.e. templates/foo/bar.hbs -> foo/bar). `
serializers/
` Serializers for your models or adapter, where model-name.js or adapter-name.js. `
utils/
` Utility modules with the convention utility-name.js. `
router.js
` Your route configuration. The routes defined here correspond to routes in app/routes/. `
/*
* 03 | Routes
* --------------------------------------------------------------
*
* When your application starts, the router matches the current URL to the routes that you've defined.
* The routes, in turn, are responsible for displaying templates, loading data, and setting up application state.
*
* > ember g route <route-name>
*/
import Route from '@ember/routing/route';
export default Route.extend({
model() {
// Typically, the model hook should return an Ember Data record,
// but it can also return any promise object (Ember Data records are
// promises), or a plain JavaScript object or array. Ember will wait
// until the data finishes loading (until the promise is resolved)
// before rendering the template.
}
});
/*
* 04 | Templates
* --------------------------------------------------------------
*
* Ember uses the Handlebars templating library to power your app's user
* interface. Handlebars templates contain static HTML and dynamic
* content inside Handlebars expressions, which are invoked with
* double curly braces: {{}}.
*
* Templates are backed with a context. A context is an object from
* which Handlebars expressions read their properties. In Ember this
* is often a component. For templates rendered by a route (like application.hbs),
* the context is a controller.
*
* > ember g template <template-name>
*/
// Here's an basic exmpale of a template
```hbs
Hello, <strong>{{firstName}} {{lastName}}</strong>!
```
/*
* 05 | Components
* --------------------------------------------------------------
*
* Ember components are used to encapsulate markup and style into
* reusable content. Components consist of two parts: a JavaScript
* component file that defines behavior, and its accompanying Handlebars
* template that defines the markup for the component's UI.
*
* > ember g component <component-name>
*/
// app/components/<component-name>.js
import Component from '@ember/component';
export default Component.extend({
});
// app/templates/components/<component-name>.hbs
```hbs
{{yield}}
```
/*
* Actions
*
* Provide a means to communicate events and changes
*/
// app/components/rental-listing.js
import Component from '@ember/component';
export default Component.extend({
isWide: false,
actions: {
toggleImageSize() {
this.toggleProperty('isWide');
}
}
});
// Actions can be attached to DOM elements inside templates using the {{action}} helper
``` app/templates/components/rental-listing.hbs
<article class="listing">
<a {{action 'toggleImageSize'}} class="image {{if isWide "wide"}}">
<img src="http://www.fillmurray.com/200/300" alt="">
</a>
</article>
```
/*
* Component lifecycle
*
* As components are rendered, re-rendered and finally removed, Ember provides
* lifecycle hooks that allow you to run code at specific times in a component's life.
*/
On Initial Render
1 init
2 didReceiveAttrs
3 willRender
4 didInsertElement // Good place to integrate with 3rd party libraries
5 didRender
On Re-Render
1 didUpdateAttrs
2 didReceiveAttrs
3 willUpdate
4 willRender
5 didUpdate
6 didRender
On Component Destroy
1 willDestroyElement
2 willClearRender
2 didDestroyElement
/*
* Block params
*
* Components can have properties passed in, but they can also return
* output to be used in a block expression.
*/
// Here an entire blog post model is being passed to the component as a
// single component property. In turn the component is returning values using yield.
``` app/templates/index.hbs
{{blog-post post=model}}
```
``` app/templates/components/blog-post.hbs
{{yield post.title post.body post.author}}
```
// The block expression can then use block params to bind names to any yielded
// values for use in the block. This allows for template customization when using
// a component, where the markup is provided by the consuming template, but any
// event handling behavior implemented in the component is retained such as click() handlers.
``` app/templates/index.hbs
{{#blog-post post=model as |title body author|}}
<h2>{{title}}</h2>
<p class="author">by {{author}}</p>
<p class="post-body">{{body}}</p>
{{/blog-post}}
```
// The names are bound in the order that they are passed to yield in the component template.
/*
* 06 | Models
* --------------------------------------------------------------
*
* Models are objects that represent the underlying data that your application
* presents to the user. Different apps will have very different models,
* depending on what problems they're trying to solve.
*
* Ember Data, included by default when you create a new application,
* is a library that integrates tightly with Ember to make it easy to
* retrieve models from your server as JSON, save updates back to the server,
* and create new models in the browser.
*
* > ember g model <model-name>
*/
import DS from 'ember-data';
import { computed } from '@ember/object';
const { attr, Model } = DS;
export default Model.extend({
firstName: attr('string'),
lastName: attr('string'),
birthday: attr('date'),
// Computed properties
// These are effectively fuctions declared as properties. The function's result
// will recompute every time one of the provided 'dependent keys' changes.
fullName: computed('firstName', 'lastName', function() {
let firstName = this.get('firstName');
let lastName = this.get('lastName');
return `${firstName} ${lastName}`;
})
});
/*
* 07 | Services
* --------------------------------------------------------------
*
* A Service is an Ember object that lives for the duration of the application, and can
* be made available in different parts of your application. Services are useful for
* features that require shared state or persistent connections.
*
* Example uses of services might include:
*
* - User/session authentication.
* - Geolocation.
* - WebSockets.
* - Server-sent events or notifications.
* - Server-backed API calls that may not fit Ember Data.
* - Third-party APIs.
* - Logging.
*
* > ember g service <service-name>
*/
/*
* Defining services
*
* Like any Ember object, a service is initialized and can have properties and
* methods of its own. Below, the shopping cart service manages an items array
* that represents the items currently in the shopping cart.
*/
// app/services/shopping-cart.js
import Service from '@ember/service';
export default Service.extend({
items: null,
init() {
this._super(...arguments);
this.set('items', []);
},
remove(item) {
this.get('items').removeObject(item);
}
});
/*
* Accessing services
*
* To access a service, you can inject it in any object such as a component or another
* service using the `inject` function from the `@ember/service` module.
*/
// app/components/cart-contents.js
import Component from '@ember/component';
import { inject } from '@ember/service';
export default Component.extend({
shoppingCart: inject() // will load the service in file /app/services/shopping-cart.js
actions: {
remove(item) {
this.get('shoppingCart').remove(item);
}
}
});
// Once injected into a component, a service can also be used in the template.
// Note cart being used below to get data from the cart.
```hbs app/templates/components/cart-contents.hbs
<ul>
{{#each cart.items as |item|}}
<li>
{{item.name}}
<button {{action "remove" item}}>Remove</button>
</li>
{{/each}}
</ul>
```
/*
* 08 | Testing
* --------------------------------------------------------------
*
* Testing is a core part of the Ember framework and its development cycle.
*
* > ember g acceptance-test <test-name>
* > ember g integration-test <test-name>
* > ember g unit-test <test-name>
* > ember t --server
* > ember s && visit localhost:4200/tests
*/
/*
* Acceptance & application tests
*
* In these kinds of tests, we interact with the application in the same ways that a
* user would, such as filling out form fields and clicking buttons. Application
* tests ensure that the interactions within a project are basically functional, the
* core features of a project have not regressed, and the project's goals are being met.
*
* Some useful helpers from '@ember/test-helpers':
* - `click(selector)`
* Clicks an element and triggers any actions triggered by the element's click event and
* returns a promise that fulfills when all resulting async behavior is complete.
*
* - `fillIn(selector, value)`
* Fills in the selected input with the given value and returns a promise that
* fulfills when all resulting async behavior is complete. Works with <select> elements
* as well as <input> elements. Keep in mind that with <select> elements, value must be set
* to the value of the <option> tag, rather than its content (for example, true rather than "Yes").
*
* - `triggerKeyEvent(selector, type, keyCode)`
* Simulates a key event type, e.g. keypress, keydown, keyup with the desired keyCode on element found by the selector.
*
* - `triggerEvent(selector, type, options)`
* Triggers the given event, e.g. blur, dblclick on the element identified by the provided selector.
*
* - `visit(url)`
* Visits the given route and returns a promise that fulfills when all resulting async behavior is complete.
*
* - `currentURL()`
* Returns the current URL.
*
* - `find(selector, context)`
* Finds an element within the app's root element and within the context (optional). Scoping to the
* root element is especially useful to avoid conflicts with the test framework's reporter, and this
* is done by default if the context is not specified.
*
* - `findAll(selector)`
* Find all elements matched by the given selector. Equivalent to calling querySelectorAll() on the
* test root element. Returns an array of matched elements.
*
*/
import { module, test } from 'qunit';
import { setupApplicationTest } from 'ember-qunit';
import { visit, fillIn, click } from '@ember/test-helpers';
module('Acceptance | posts', function(hooks) {
// `setupApplicationTest` deals with application setup and teardown.
setupApplicationTest(hooks);
test('should add new post', async function(assert) {
await visit('/posts/new');
await fillIn('input.title', 'My new post');
await click('button.submit');
const title = this.element.querySelector('ul.posts li:first').textContent;
assert.equal(title, 'My new post');
});
});
/*
* Integration & rendering tests
*
* Rendering Tests are, as the name suggests, rendering components and helpers
* by verifying the correct behaviour when the component or helper interacts
* with the system in the same way that it will within the context of the application,
* including being rendered from a template and receiving Ember's lifecycle hooks.
*
* If we need to test the interactions between various parts of the application,
* such as behaviour between UI controls we can utilize Rendering Tests.
*/
// app/components/pretty-color.js
import Component from '@ember/component';
import { computed } from '@ember/object';
export default Component.extend({
attributeBindings: ['style'],
style: computed('name', function() {
const name = this.get('name');
return `color: ${name}`;
})
});
// tests/integration/components/pretty-color-test.js
import { module, test } from 'qunit';
import { setupRenderingTest } from 'ember-qunit';
import { render } from '@ember/test-helpers';
import hbs from 'htmlbars-inline-precompile';
module('Integration | Component | pretty color', function(hooks) {
// Make sure to call the setupRenderingTest function together with the hooks
// parameter first in your new module. This will do the necessary setup for
// testing your component for you, including setting up a way to access the
// rendered DOM of your component later on in the test, and cleaning up
// once your tests in this module are finished.
setupRenderingTest(hooks);
test('it renders', async function(assert) {
assert.expect(2);
// set the outer context to red
this.set('colorValue', 'red');
await render(hbs`{{pretty-color name=colorValue}}`);
assert.equal(this.element.querySelector('div').getAttribute('style'), 'color: red', 'starts as red');
this.set('colorValue', 'blue');
assert.equal(this.element.querySelector('div').getAttribute('style'), 'color: blue', 'updates to blue'); });
});
// Stubbing services
//
// In cases where components have dependencies on Ember services, it is
// possible to stub these dependencies for rendering tests. You stub Ember
// services by using the built-in register() function to register your
// stub service in place of the default.
import { module, test } from 'qunit';
import { setupRenderingTest } from 'ember-qunit';
import { render } from '@ember/test-helpers';
import hbs from 'htmlbars-inline-precompile';
import Service from '@ember/service';
//Stub location service
const locationStub = Service.extend({
city: 'New York',
country: 'USA',
currentLocation: {
x: 1234,
y: 5678
},
getCurrentCity() {
return this.get('city');
},
getCurrentCountry() {
return this.get('country');
}
});
module('Integration | Component | location indicator', function(hooks) {
setupRenderingTest(hooks);
hooks.beforeEach(function(assert) {
this.owner.register('service:location-service', locationStub);
});
test('should reveal current location', async function(assert) {
await render(hbs`{{location-indicator}}`);
assert.equal(this.element.textContent.trim(),
'You currently are located in New York, USA');
});
});
/*
* Unit & container tests
*
* Unit tests (as well as container tests) are generally used to test a
* small piece of code and ensure that it is doing what was intended.
*/
// app/services/some-thing.js
import Service from '@ember/service';
export default Service.extend({
foo: 'bar',
testMethod() {
this.set('foo', 'baz');
}
});
// tests/unit/services/some-thing-test.js
import { module, test } from 'qunit';
import { setupTest } from 'ember-qunit';
module('Unit | Service | some thing', function(hooks) {
// The `setupTest` helper provides us with some conveniences, such as the `this.owner` object,
// that helps us to create or lookup objects which are needed to setup our test.
// In this example, we use the `this.owner` object to lookup the service instance that
// becomes our test subject: `someThing`. Note that in a unit test you can customize any
// object under test by setting its properties accordingly. We can use the `set` method
// of the test object to achieve this.
setupTest(hooks);
test('should update foo on testMethod', function(assert) {
const someThing = this.owner.lookup('service:some-thing');
someThing.testMethod();
assert.equal(someThing.get('foo'), 'baz');
});
});
/*
* Running tests
*
* Run your tests with `ember test` on the command-line. You can re-run your tests on
* every file-change with `ember test --server`.
*
* Tests can also be executed when you are running a local development server
* (started by running `ember server`), at the `/tests` URI which renders the `tests/index.html` template.
*/
```
ember test
ember test --server
ember test --filter="dashboard"
run ember server then visit http://localhost:4200/tests
```
/*
* 09 | Addons
* --------------------------------------------------------------
*
* Ember has a rich ecosystem of addons that can be easily added to projects.
* Addons provide a wide range of functionality to projects, often saving time and
* letting you focus on your project.
*
* To browse addons, visit the [EmberObserver](https://emberobserver.com/) website. It catalogs and categorizes Ember
* addons that have been published to NPM and assigns them a score based on a variety of criteria.
*
* > ember install <addont-name>
*/
/*
* 10 | Configuration
* --------------------------------------------------------------
*
* Ember CLI ships with support for managing your application's environment. Ember CLI
* will setup a default environment config file at config/environment. Here, you can define
* an ENV object for each environment, which are currently limited to three: development,
* test, and production.
*/
// The ENV object has three important keys:
// - `EmberENV` can be used to define Ember feature flags (see the Feature Flags guide).
// - `APP` can be used to pass flags/options to your application instance.
// - `environment` contains the name of the current environment (development,production or test).
// You can access these environment variables in your application code by importing from `your-application-name/config/environment`.
import ENV from 'your-application-name/config/environment';
if (ENV.environment === 'development') {
// ...
}
/*
* 11 | Community
* --------------------------------------------------------------
*
* Ember's secret sauce
*
* more at [Ember Community Page](https://emberjs.com/community/)
*
*/
// Ember Discussion Forum
//
// url: http://discuss.emberjs.com/
//
// A great venue for discussing things like features, architecture, and best practices
// and a great place to ask questions (and get great answers from Ember Core Team members
// and other members of the community)
// Ember Community Slack
//
// url: https://embercommunity.slack.com/
//
// Use the Slackin app to receive an invitation.
// Ember Times
//
// url: https://the-emberjs-times.ongoodbits.com/
//
// Follow the progress of new features in the Ember ecosystem, requests for community
// input (RFCs), and calls for contributors
// Ember Weekly
//
// url: http://www.emberweekly.com/
//
// A curated list of Ember learning resources (podcasts, videos, blog posts, books, and more)
// Official Ember Blog
//
// url: https://emberjs.com/blog/
//
// Big announcements like new Ember.js version release notes or State of the Union information
// Ember Github
//
// url: https://github.com/emberjs/
// Ember Meetups
//
// url: https://emberjs.com/community/meetups/