diff --git a/docs/bundled-models.md b/docs/bundled-models.md deleted file mode 100644 index 48d12d1f..00000000 --- a/docs/bundled-models.md +++ /dev/null @@ -1,236 +0,0 @@ -## Bundled Models - -The Loopback library is unopinioned in the way you define your app's data and logic. Loopback also bundles useful pre-built models for common use cases. - - - User - register and authenticate users of your app locally or against 3rd party services. - - Email - send emails to your app users using smtp or 3rd party services. - -Defining a model with `loopback.createModel()` is really just extending the base `loopback.Model` type using `loopback.Model.extend()`. The bundled models extend from the base `loopback.Model` allowing you to extend them arbitrarily. - -### User Model - -Register and authenticate users of your app locally or against 3rd party services. - -#### Define a User Model - -Extend a vanilla Loopback model using the built in User model. - -```js -// create a data source -var memory = loopback.memory(); - -// define a User model -var User = loopback.User.extend('user'); - -// attach to the memory connector -User.attachTo(memory); - -// also attach the accessToken model to a data source -User.accessToken.attachTo(memory); - -// expose over the app's api -app.model(User); -``` - -**Note:** By default the `loopback.User` model uses the `loopback.AccessToken` model to persist access tokens. You can change this by setting the `accessToken` property. - -**Note:** You must attach both the `User` and `User.accessToken` model's to a data source! - -#### User Creation - -Create a user like any other model. - -```js -// username and password are not required -User.create({email: 'foo@bar.com', password: 'bar'}, function(err, user) { - console.log(user); -}); -``` - -#### Login a User - -Create an `accessToken` for a user using the local auth strategy. - -**Node.js** - -```js -User.login({username: 'foo', password: 'bar'}, function(err, accessToken) { - console.log(accessToken); -}); -``` - -**REST** - -You must provide a username and password over rest. To ensure these values are encrypted, include these as part of the body and make sure you are serving your app over https (through a proxy or using the https node server). - -``` -POST - - /users/login - ... - { - "email": "foo@bar.com", - "password": "bar" - } - - ... - - 200 OK - { - "sid": "1234abcdefg", - "uid": "123" - } -``` - -#### Logout a User - -**Node.js** - -```js -// login a user and logout -User.login({"email": "foo@bar.com", "password": "bar"}, function(err, accessToken) { - User.logout(accessToken.id, function(err) { - // user logged out - }); -}); - -// logout a user (server side only) -User.findOne({email: 'foo@bar.com'}, function(err, user) { - user.logout(); -}); -``` - -**REST** - -``` -POST /users/logout -... -{ - "sid": "" -} -``` - -#### Verify Email Addresses - -Require a user to verify their email address before being able to login. This will send an email to the user containing a link to verify their address. Once the user follows the link they will be redirected to `/` and be able to login normally. - -```js -// first setup the mail datasource (see #mail-model for more info) -var mail = loopback.createDataSource({ - connector: loopback.Mail, - transports: [{ - type: 'smtp', - host: 'smtp.gmail.com', - secureConnection: true, - port: 465, - auth: { - user: 'you@gmail.com', - pass: 'your-password' - } - }] -}); - -User.email.attachTo(mail); -User.requireEmailVerfication = true; -User.afterRemote('create', function(ctx, user, next) { - var options = { - type: 'email', - to: user.email, - from: 'noreply@myapp.com', - subject: 'Thanks for Registering at FooBar', - text: 'Please verify your email address!' - template: 'verify.ejs', - redirect: '/' - }; - - user.verify(options, next); -}); -``` - -#### Send Reset Password Email - -Send an email to the user's supplied email address containing a link to reset their password. - -```js -User.reset(email, function(err) { - console.log('email sent'); -}); -``` - -#### Remote Password Reset - -The password reset email will send users to a page rendered by loopback with fields required to reset the user's password. You may customize this template by defining a `resetTemplate` setting. - -```js -User.settings.resetTemplate = 'reset.ejs'; -``` - -#### Remote Password Reset Confirmation - -Confirm the password reset. - -```js -User.confirmReset(token, function(err) { - console.log(err || 'your password was reset'); -}); -``` - -### AccessToken Model - -Identify users by creating accessTokens when they connect to your loopback app. By default the `loopback.User` model uses the `loopback.AccessToken` model to persist accessTokens. You can change this by setting the `accessToken` property. - -```js -// define a custom accessToken model -var MyAccessToken = loopback.AccessToken.extend('MyAccessToken'); - -// define a custom User model -var User = loopback.User.extend('user'); - -// use the custom accessToken model -User.accessToken = MyAccessToken; - -// attach both AccessToken and User to a data source -User.attachTo(loopback.memory()); -MyAccessToken.attachTo(loopback.memory()); -``` - -### Email Model - -Send emails from your loopback app. - -```js -// extend a one-off model for sending email -var MyEmail = loopback.Email.extend('my-email'); - -// create a mail data source -var mail = loopback.createDataSource({ - connector: loopback.Mail, - transports: [{ - type: 'smtp', - host: 'smtp.gmail.com', - secureConnection: true, - port: 465, - auth: { - user: 'you@gmail.com', - pass: 'your-password' - } - }] -}); - -// attach the model -MyEmail.attachTo(mail); - -// send an email -MyEmail.send({ - to: 'foo@bar.com', - from: 'you@gmail.com', - subject: 'my subject', - text: 'my text', - html: 'my html' -}, function(err, mail) { - console.log('email sent!'); -}); -``` - -> NOTE: the mail connector uses [nodemailer](http://www.nodemailer.com/). See -> the [nodemailer docs](http://www.nodemailer.com/) for more info.