Skip to content
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.

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

Modernize docs #2136

Merged
merged 9 commits into from
Mar 30, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
127 changes: 65 additions & 62 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,19 +120,19 @@ in the template__:
import Controller from '@ember/controller';
import { inject as service } from '@ember/service';

export default Controller.extend({
session: service()
export default class ApplicationController extends Controller {
@service session;

});
}
```

```handlebars
{{!-- app/templates/application.hbs --}}
<div class="menu">
{{#if session.isAuthenticated}}
<a {{action 'invalidateSession'}}>Logout</a>
{{#if this.session.isAuthenticated}}
<a {{on "click" this.invalidateSession}}>Logout</a>
{{else}}
{{#link-to 'login'}}Login{{/link-to}}
{{/if}}
Expand All @@ -150,18 +150,18 @@ to invalidate the session__ and log the user out:
// app/controllers/application.js
import Controller from '@ember/controller';
import { inject as service } from '@ember/service';
import { action } from "@ember/object";

export default Controller.extend({
session: service(),
export default class ApplicationController extends Controller {
@service session;


actions: {
invalidateSession() {
this.get('session').invalidate();
}
@action
invalidateSession() {
this.session.invalidate();
}
});
}
```

For authenticating the session, __the session service provides the
Expand All @@ -175,21 +175,21 @@ library comes with, e.g.:
// app/authenticators/oauth2.js
import OAuth2PasswordGrant from 'ember-simple-auth/authenticators/oauth2-password-grant';

export default OAuth2PasswordGrant.extend();
export default class OAuth2Authenticator extends OAuth2PasswordGrant {}
```

With that authenticator and a login form like

```handlebars
{{!-- app/templates/login.hbs --}}
<form {{action 'authenticate' on='submit'}}>
<form {{on "submit" this.authenticate}}>
<label for="identification">Login</label>
{{input id='identification' placeholder='Enter Login' value=identification}}
<input id='identification' placeholder="Enter Login" value={{this.identification}} {{on "change" this.updateIdentification}}>
<label for="password">Password</label>
{{input id='password' placeholder='Enter Password' type='password' value=password}}
<input id='password' placeholder="Enter Password" value={{this.password}} {{on "change" this.updatePassword}}>
<button type="submit">Login</button>
{{#if errorMessage}}
<p>{{errorMessage}}</p>
{{#if this.errorMessage}}
<p>{{this.errorMessage}}</p>
{{/if}}
</form>
```
Expand All @@ -201,25 +201,27 @@ the __session can be authenticated with the
// app/controllers/login.js
import Controller from '@ember/controller';
import { inject as service } from '@ember/service';
import { action } from "@ember/object";
import { tracked } from "@glimmer/tracking";

export default class LoginController extends Controller {
@tracked errorMessage;
@service session;

@action
async authenticate() {
let { identification, password } = this;
try {
await this.session.authenticate('authenticator:oauth2', identification, password);
} catch(error) {
this.errorMessage = error.error || error;
}

export default Controller.extend({
session: service(),

actions: {
async authenticate() {
let { identification, password } = this.getProperties('identification', 'password');
try {
await this.session.authenticate('authenticator:oauth2', identification, password);
} catch(error) {
this.set('errorMessage', error.error || error);
}

if (this.session.isAuthenticated) {
// What to do with all this success?
}
if (this.session.isAuthenticated) {
// What to do with all this success?
}
}
});
}
```

__The session service also provides the
Expand All @@ -239,7 +241,7 @@ into the application route__:
import Route from '@ember/routing/route';
import ApplicationRouteMixin from 'ember-simple-auth/mixins/application-route-mixin';

export default Route.extend(ApplicationRouteMixin);
export default class ApplicationRoute extends Route.extend(ApplicationRouteMixin) {}
```

The `ApplicationRouteMixin` automatically maps the session events to the
Expand All @@ -260,7 +262,7 @@ into the respective route:
import Route from '@ember/routing/route';
import AuthenticatedRouteMixin from 'ember-simple-auth/mixins/authenticated-route-mixin';

export default Route.extend(AuthenticatedRouteMixin);
export default class ProtectedRoute extends Route.extend(AuthenticatedRouteMixin) {}
```

This will make the route (and all of its subroutes) transition to the `login`
Expand Down Expand Up @@ -305,23 +307,22 @@ It can be used as:

```js
// app/adapters/application.js
import DS from 'ember-data';
import JSONAPIAdapter from '@ember-data/adapter/json-api';
import DataAdapterMixin from 'ember-simple-auth/mixins/data-adapter-mixin';
import { computed } from '@ember/object';

const { JSONAPIAdapter } = DS;

export default JSONAPIAdapter.extend(DataAdapterMixin, {
headers: computed('session.data.authenticated.access_token', function() {
export default class ApplicationAdapter extends JSONAPIAdapter.extend(DataAdapterMixin) {
@computed('session.data.authenticated.access_token')
get headers() {
let headers = {};
if (this.session.isAuthenticated) {
// OAuth 2
headers['Authorization'] = `Bearer ${this.session.data.authenticated.access_token}`;
}

return headers;
}),
});
}
}
```

## The Session Service
Expand All @@ -343,7 +344,7 @@ side data that needs to be persisted and synchronized across tabs and windows,
e.g.:

```js
this.get('session').set('data.locale', 'de');
this.session.set('data.locale', 'de');
```

## Authenticators
Expand All @@ -357,7 +358,7 @@ is chosen when authentication is triggered via the name it is registered with
in the Ember container:

```js
this.get('session').authenticate('authenticator:some');
this.session.authenticate('authenticator:some');
```

Ember Simple Auth comes with 4 authenticators:
Expand All @@ -375,14 +376,14 @@ authenticator
// app/authenticators/oauth2.js
import OAuth2PasswordGrantAuthenticator from 'ember-simple-auth/authenticators/oauth2-password-grant';

export default OAuth2PasswordGrantAuthenticator.extend();
export default class OAuth2Authenticator extends OAuth2PasswordGrantAuthenticator {}
```

and invoke the session service's `authenticate` method with the respective
name, specifying more arguments as needed by the authenticator:

```js
this.get('session').authenticate('authenticator:some', data);
this.session.authenticate('authenticator:some', data);
```

### Customizing an Authenticator
Expand All @@ -394,9 +395,9 @@ e.g.:
// app/authenticators/oauth2.js
import OAuth2PasswordGrantAuthenticator from 'ember-simple-auth/authenticators/oauth2-password-grant';

export default OAuth2PasswordGrantAuthenticator.extend({
serverTokenEndpoint: '/custom/endpoint'
});
export default class OAuth2Authenticator extends OAuth2PasswordGrantAuthenticator {
serverTokenEndpoint = '/custom/endpoint';
}
```

### Implementing a custom Authenticator
Expand All @@ -415,17 +416,19 @@ methods:
// app/authenticators/custom.js
import Base from 'ember-simple-auth/authenticators/base';

export default Base.extend({
export default class CustomAuthenticator extends Base {
restore(data) {
},
}

authenticate(options) {
},
}

invalidate(data) {
}
});
}
```

## Session Stores
Expand All @@ -438,7 +441,7 @@ defined in `app/session-stores/application.js`:
// app/session-stores/application.js
import Cookie from 'ember-simple-auth/session-stores/cookie';

export default Cookie.extend();
export default class ApplicationSessionStore extends Cookie {}
```

If the application does not define a session store, the adaptive store which
Expand Down Expand Up @@ -495,9 +498,9 @@ e.g.:
// app/session-stores/application.js
import AdaptiveStore from 'ember-simple-auth/session-stores/adaptive';

export default AdaptiveStore.extend({
cookieName: 'my-apps-session-cookie'
});
export default class ApplicationSessionStore extends AdaptiveStore {
cookieName = 'my-apps-session-cookie';
}
```

### Implementing a custom Store
Expand All @@ -516,15 +519,15 @@ methods:
// app/session-stores/application.js
import Base from 'ember-simple-auth/session-stores/base';

export default Base.extend({
export default class ApplicationSessionStore extends Base {
persist() {
},
}

restore() {
}
});
}
```

## FastBoot
Expand All @@ -537,7 +540,7 @@ the application store:
// app/session-stores/application.js
import CookieStore from 'ember-simple-auth/session-stores/cookie';

export default CookieStore.extend();
export default class ApplicationSessionStore extends CookieStore {}
```

If you are using the
Expand Down
21 changes: 12 additions & 9 deletions addon/authenticators/base.js
Original file line number Diff line number Diff line change
Expand Up @@ -30,25 +30,28 @@ import EmberObject from '@ember/object';
// app/authenticators/oauth2.js
import OAuth2PasswordGrantAuthenticator from 'ember-simple-auth/authenticators/oauth2-password-grant';

export default OAuth2PasswordGrantAuthenticator.extend({
export default class OAuth2Authenticator extends OAuth2PasswordGrantAuthenticator {
...
});
}
```

and can then be used via the name Ember CLI automatically registers for them
within the Ember container.

```js
// app/components/login-form.js
export default Ember.Controller.extend({
session: Ember.inject.service(),
import Component from '@ember/component';
import { inject as service } from '@ember/service';
import { action } from '@ember/object';

export default class LoginFormComponent extends Component {
@service session;

actions: {
authenticate: function() {
this.get('session').authenticate('authenticator:oauth2');
}
@action
authenticate() {
this.session.authenticate('authenticator:oauth2');
}
});
}
```

@class BaseAuthenticator
Expand Down
13 changes: 7 additions & 6 deletions addon/authenticators/torii.js
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,12 @@ import BaseAuthenticator from './base';

```js
// app/authenticators/torii.js
import ToriiAuthenticator from 'ember-simple-auth/authenticators/torii';
import Torii from 'ember-simple-auth/authenticators/torii';
import { inject as service } from '@ember/service';

export default ToriiAuthenticator.extend({
torii: Ember.inject.service()
});
export default class ToriiAuthenticator extends Torii {
@service torii;
}
```

@class ToriiAuthenticator
Expand All @@ -40,11 +41,11 @@ export default BaseAuthenticator.extend({
// app/torii-providers/facebook.js
import FacebookOauth2Provider from 'torii/providers/facebook-oauth2';

export default FacebookOauth2Provider.extend({
export default class FacebookToriiProvider extends FacebookOauth2Provider {
fetch(data) {
return data;
}
});
}
```

@method restore
Expand Down
4 changes: 2 additions & 2 deletions addon/mixins/authenticated-route-mixin.js
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ function runIfUnauthenticated(owner, transition, callback) {
// app/routes/protected.js
import AuthenticatedRouteMixin from 'ember-simple-auth/mixins/authenticated-route-mixin';

export default Ember.Route.extend(AuthenticatedRouteMixin);
export default class ProtectedRoute extends Route.extend(AuthenticatedRouteMixin) {}
```

@class AuthenticatedRouteMixin
Expand Down Expand Up @@ -90,7 +90,7 @@ export default Mixin.create({
the browser after authentication is complete.

__If `beforeModel` is overridden in a route that uses this mixin, the route's
implementation must call `this._super(...arguments)`__ so that the mixin's
implementation must call `super.beforeModel(...arguments)`__ so that the mixin's
`beforeModel` method is actually executed.

@method beforeModel
Expand Down
Loading