Skip to content

Major: deprecate addon in favor of ember-page-title #108

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
snewcomer wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Major: deprecate addon in favor of ember-page-title #108

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
208 changes: 2 additions & 206 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,207 +1,3 @@
# Sane Document Title [![Build Status](https://travis-ci.org/kimroen/ember-cli-document-title.svg?branch=master)](https://travis-ci.org/kimroen/ember-cli-document-title) [![Ember Observer Score](http://emberobserver.com/badges/ember-cli-document-title.svg)](http://emberobserver.com/addons/ember-cli-document-title) [![Code Climate](https://codeclimate.com/github/kimroen/ember-cli-document-title/badges/gpa.svg)](https://codeclimate.com/github/kimroen/ember-cli-document-title)
This addon adds sane `document.title` integration to your ember app.
# Sane Document Title

Originally based on [this gist by @machty](https://gist.github.com/machty/8413411), and since improved upon by many fabulous contributors.

Tested to work with Ember 1.13.13 and up.

## Install
Install by running

```
ember install ember-cli-document-title
```

## So, how does this work?
This adds two new keys to your routes:

1. `titleToken`
2. `title`

They can be either strings or functions.

Every time you transition to a route, the following will happen:

1. Ember will collect the `titleToken`s from your leafmost route and
bubble them up until it hits a route that has `title` defined.
`titleToken` is the name of the route's model by default.
2. If `title` is a string, that will be used as the document title
3. If `title` is a function, the collected `titleToken`s will be passed
to it in an array.
4. What is returned from the `title` function is used as the document
title.

## Examples!

### Simple, static titles
If you just put strings as the `title` for all your routes, that will be
used as the title for it.

```js
// routes/posts.js
export default Ember.Route.extend({
title: 'Our Favorite posts!'
});

// routes/post.js
export default Ember.Route.extend({
title: 'Please enjoy this post'
});
```

### Dynamic segments with a static part
Let's say you want something like "Posts - My Blog", with "- My Blog"
being static, and "Posts" being something you define on each route.

```js
// routes/posts.js
export default Ember.Route.extend({
titleToken: 'Posts'
});
```

This will be collected and bubble up until it hits the Application Route
```js
// routes/application.js
export default Ember.Route.extend({
title: function(tokens) {
return tokens.join(' - ') + ' - My Blog';
}
});
```

### Dynamic title based on model info
In this example, we want something like "Name of current post - Posts -
My Blog".

Let's say we have this object as our post-model:

```js
Ember.Object.create({
name: 'Ember is Omakase'
});
```
And we want to use the name of each post in the title.

```js
// routes/post.js
export default Ember.Route.extend({
titleToken: function(model) {
return model.get('name');
}
});
```

This will then bubble up until it reaches our Posts Route:

```js
// routes/posts.js
export default Ember.Route.extend({
titleToken: 'Posts'
});
```

And continue to the Application Route:

```js
// routes/application.js
export default Ember.Route.extend({
title: function(tokens) {
tokens = Ember.makeArray(tokens);
tokens.unshift('My Blog');
return tokens.reverse().join(' - ');
}
});
```

This will result in these titles:
- On /posts - "Posts - My Blog"
- On /posts/1 - "Ember is Omakase - Posts - My Blog"

### Async titles using promises
You may be in a situation where it makes sense to have one or more of your `titleToken`s be asynchronous. For example if a related model is async, or you just enjoy working with Promises in your past-time.

Luckily, you can return a promise from any of your `titleToken` functions, and they will all be resolved by the time your `title` function receives them.

An example! Let's say we have these two Ember Data models; a `post` and its `user`:

```js
// models/post.js
export default DS.Model.extend({
name: DS.attr('string'),
author: DS.belongsTo('user', { async: true })
});
```

```js
// models/user.js
export default DS.Model.extend({
firstName: DS.attr('string'),
lastName: DS.attr('string')
});
```

In our document title, we want the name of the author in parenthesis along with the post title.

The `author` relationship is `async`, so getting it will return a promise. Here's
an example where we return a promise that resolves to the post name plus the author
name in parenthesis:

```js
// routes/post.js
export default Ember.Route.extend({
titleToken: function(model) {
var postName = model.get('name');

return model.get('author')
.then(function (user) {
var authorName = user.get('firstName') + user.get('lastName');

return postName + '(by ' + authorName + ')';
});
}
});
```

With the same configuration for `Posts` and `Application` routes as in the previous example, this will result in this title:
- On /posts/1 - "Ember is Omakase (by John Smith) - Posts - My Blog"

It's worth noting that the page title will not update until all the promises have resolved.

### Use with `ember-cli-head`

Using `ember-cli-document-title` with [ember-cli-head](https://github.com/ronco/ember-cli-head)
is very straight forward and allows you to use the wonderful route based declarative API for
`title` and still easily add other things to the document's `<head>` (i.e. `meta` tags).

Only a few tweaks are needed to use both of these addons together:

* Install both addons:

```sh
ember install ember-cli-head
ember install ember-cli-document-title
```

* Add `headData` and `setTitle` to your `app/router.js`:

```js
const Router = Ember.Router.extend({
location: config.locationType,
headData: Ember.inject.service(),

setTitle(title) {
this.get('headData').set('title', title);
}
});
```

* Remove `<title>` from your `app/index.html`.

* Update `app/templates/head.hbs` (added by ember-cli-head):

```hbs
{{! app/templates/head.hbs }}

<title>{{model.title}}</title>
```
This addon has been deprecated in favor of [ember-page-title](https://github.com/ember-cli/ember-page-title). The last version available to users is [1.1.0](https://github.com/kimroen/ember-cli-document-title/blob/master/CHANGELOG.md#110).