Merge branch 'auth-docs' into devel

docs/client/api.html

@@ -1643,22 +1643,87 @@ XXX intro text
 
 {{> api_box user}}
 
-- {_id: foo} if not userLoaded.
-- schema / common fields
+Retreives the user record for the current user from
+the <a href="#meteor_users">`Meteor.users`</a> collection.
 
+On the client this will be a subset of the fields in the document, only
+those that are published from the server are available on the client. By
+default the server publishes `username`, `emails`, and
+`profile`. See <a href="#meteor_users">`Meteor.users`</a> for more on
+the fields used user documents.
+
+If the user is logged in but the user's database record is not fully
+loaded yet, this returns an object with only the `_id` field set. During
+this period <a href="#meteor_userloaded">`userLoaded`</a> will return
+`false`.
 
 {{> api_box userId}}
 
 {{> api_box users}}
 
-- on the client, current user. on the server all users.
-- examples of usage?
-- schema
-- default publish and allow for profile
+This collection contains one document per user. Example user document:
+
+    {
+      _id: "bbca5d6a-2156-41c4-89da-0329e8c99a4f" // userId
+      username: "cool_kid_13", // unique name
+      emails: [
+        // each email address can only belong to one user.
+        { address: "cool@example.com", verified: true },
+        { address: "another@different.com", verified: false }
+      ],
+      profile: {
+        // The profile is writable by the user by default.
+        name: "Joe Schmoe"
+      },
+      services: {
+        facebook: {
+          id: "709050", // facebook id
+          accessToken: "AAACCgdX7G2...AbV9AZDZD"
+        },
+        resume: {
+          loginTokens: [
+            { token: "97e8c205-c7e4-47c9-9bea-8e2ccc0694cd",
+              when: 1349761684048 }
+          ]
+        }
+      }
+    }
+
+
+Like all <a href='#collections'>Meteor.Collection</a>s, you can access all documents on the
+server, but only those specifically published by the server are
+available on the client.
+
+By default, the current user's `username`, `emails` and `profile` are
+published to the client. You can publish additional fields for the
+current user with:
+
+    Meteor.publish("userData", function () {
+      return Meteor.users.find({_id: this.userId},
+                               {fields: {'other': 1, 'things': 1}});
+    });
+
+If the `autopublish` package is installed, the `username` and `profile` fields for all users are published to all clients. To publish specific fields from all users:
+
+    Meteor.publish("allUserData", function () {
+      return Meteor.users.find({}, {fields: {'nested.things': 1}});
+    });
+
+Users are by default allowed to specify their own `profile` field with <a href="#accounts_createuser">`Accounts.createUser`</a> and modify it with `Meteor.users.update`. To allow users to edit additional fields, use <a href="#allow">`Meteor.users.allow`</a>. To forbid users from making any modifications to their user document:
+
+    Meteor.users.deny({update: function () { return true; }});
+
 
 {{> api_box userLoaded}}
 
-- more text
+There are some cases when the client knows the id of the logged in user
+but has not yet received the user data from the server. For example, if
+the user is logged in and reloads the page the user data will be
+unavailable during initial page load.
+
+During these periods, `userLoaded` will return false
+and <a href="#meteor_user">`user`</a> will return an object with only
+the `_id` key.
 
 {{#note}}
 We realize this is inconvenient. It is a temporary solution. In the
@@ -1672,47 +1737,157 @@ general mechanism.
 
 {{> api_box loginWithOAuth}}
 
-- example scopes
+These functions initiate the login process with a third party OAuth
+provider (eg: Facebook, Google, etc). When called they open a new pop-up
+window that loads the provider's login page. Once the user has logged in
+with the provider, the pop-up window is closed and the Meteor client
+logs in to the Meteor server with the information provided by the OAuth
+provider.
+
+If the user has not already granted all the permissions requested they
+will be prompted to grant access to their account in the pop-up
+dialog. Values for the `requestPermissions` parameter differ for each login service:
+
+- Facebook: <a href="http://developers.facebook.com/docs/authentication/permissions/">http://developers.facebook.com/docs/authentication/permissions/</a>
+- GitHub: <a href="http://developer.github.com/v3/oauth/#scopes">http://developer.github.com/v3/oauth/#scopes</a>
+- Google: <a href="https://developers.google.com/accounts/docs/OAuth2Login#scopeparameter">https://developers.google.com/accounts/docs/OAuth2Login#scopeparameter</a>
+
+Currently, `loginWithTwitter` and `loginWithWeibo` do not support
+`requestPermissions`.
+
 
 {{> api_box accounts_createUser}}
 
-- logs you in on the client
-- diff between client and server
-- username and/or email. which are optional.
-- default user hook adds profile, override w/ onCreateUser
-- not for oauth
+On the client this function logs in as the newly created user on
+successful completion. On the server, it returns the newly created user
+id.
+
+On the client, you must pass `password` and one of `username` or `email`
+&mdash; enough information for the user to be able to log in again
+later. On the server, you can pass any subset of these options, but the
+user will not be able to log in until it has an identifier and a
+password.
+
+To create an account without a password on the server and still let the
+user pick their own password, call `createUser` with the `email` option
+and then
+call <a href="#accounts_sendenrollmentemail">`Accounts.sendEnrollmentEmail`</a>. This
+will send the user an email with a link to set their initial password.
+
+By default the `profile` option is added directly to the new user
+document. To override this behavior, use <a href="#accounts_createuser">`Accounts.onCreateUser`</a>.
+
+This function is only used for creating users with passwords. The OAuth
+login flows do not use this function.
+
 
 {{> api_box accounts_changePassword}}
 
 {{> api_box accounts_forgotPassword}}
 
-- triggers sendResetPasswordEmail
-- document where the token goes in Accounts._whatever?
-- youre responsibility to get it into resetPassword
+This triggers a call
+to <a href="#accounts_sendresetpasswordemail">`Accounts.sendResetPasswordEmail`</a>
+on the server. Pass the token the user receives in this email
+to <a href="#accounts_resetpassword">`Accounts.resetPassword`</a> to
+complete the password reset process.
+
+If you are using the <a href="#pkg_accounts_ui">`accounts-ui`
+  package</a>, this is handled automatically. Otherwise, it is your
+responsiblity to prompt the user for the new password and call `resetPassword`.
+
+- XXX token goes to `Accounts._resetPasswordToken`.
 
 {{> api_box accounts_resetPassword}}
 
-- don't need to call if you have accounts-ui
+This function accepts tokens generated
+by <a href="#accounts_sendresetpasswordemail">`Accounts.sendResetPasswordEmail`</a>
+and
+<a href="#accounts_sendenrollmentemail">`Accounts.sendEnrollmentEmail`</a>
 
 {{> api_box accounts_setPassword}}
 
 {{> api_box accounts_verifyEmail}}
 
-- pass token from sendVerificationEmail
-- what changes in the schema
+This function accepts tokens generated
+by <a href="#accounts_sendverificationemail">`Accounts.sendVerificationEmail`</a>. It
+sets the `emails.verified` field in the user record.
+
 
 {{> api_box accounts_sendResetPasswordEmail}}
+
+The token in this email should be passed
+to <a href="#accounts_resetpassword">`Accounts.resetPassword`</a>.
+
+To customize the contents of the email, see <a href="#accounts_emailtemplates">`Accounts.emailTemplates`</a>.
+
 {{> api_box accounts_sendEnrollmentEmail}}
+
+The token in this email should be passed
+to <a href="#accounts_resetpassword">`Accounts.resetPassword`</a>.
+
+To customize the contents of the email, see <a href="#accounts_emailtemplates">`Accounts.emailTemplates`</a>.
+
 {{> api_box accounts_sendVerificationEmail}}
+
+The token in this email should be passed
+to <a href="#accounts_verifyemail">`Accounts.verifyEmail`</a>.
+
+To customize the contents of the email, see <a href="#accounts_emailtemplates">`Accounts.emailTemplates`</a>.
+
 {{> api_box accounts_emailTemplates}}
 
 {{> api_box accounts_config}}
 {{> api_box accounts_ui_config}}
+
 {{> api_box accounts_validateNewUser}}
+
+This can be called multiple times. If any of the functions return
+`false` the new user creation is aborted.
+
+Example:
+
+    // All users must have a username longer than 3 characters.
+    Accounts.validateNewUser(function (user) {
+        return user.username && user.username.length >= 3;
+    });
+
 {{> api_box accounts_onCreateUser}}
 
-- takes `options`, `user`
+Use this when you need to do more than simply accept or reject new user
+creation. With this function you can programatically control the
+contents of new user documents.
 
+The function you pass will be called with two arguments: `options` and
+`user`. The `options` argument comes
+from <a href="#accounts_createuser">`Accounts.createUser`</a> for
+password-based users or from the OAuth login flow. `options` may come
+from an untrusted client so make to validate any values you read from
+it. The `user` argument is created on the server and contains a
+proposed user object with all the automatically generated fields
+required for the user to log in.
+
+The function should return a new user object with whatever modifications
+are desired. The returned object is inserted directly into
+the <a href="#meteor_users">`Meteor.users`</a> collection.
+
+The default create user function simply copies `options.profile` into
+the new user document. Calling `onCreateUser` overrides the default
+hook. This can only be called once.
+
+Example:
+
+    // Make members of the GitHub 'meteor' group into admins.
+    Accounts.onCreateUser(function(options, user) {
+      // http://developer.github.com/v3/orgs/members/#get-member
+      if (!Meteor.http.get(
+            "https://api.github.com/orgs/meteor/members/" +
+            user.services.github.username +
+            "?access_token=" + user.services.github.accessToken
+           ).error) {
+        user.admin = true;
+      }
+      return user;
+    });
 
 
 <h2 id="timers"><span>Timers</span></h2>

docs/client/api.js

@@ -1034,7 +1034,7 @@ Template.api.accounts_onCreateUser = {
     {
       name: "func",
       type: "Function",
-      descr: "Called whenever a new user is created. Return the new user ojbject, or throw an `Error` to abort the creation."
+      descr: "Called whenever a new user is created. Return the new user object, or throw an `Error` to abort the creation."
     }
   ]
 };

docs/client/packages/accounts-ui.html

@@ -2,9 +2,26 @@
 {{#better_markdown}}
 ## `accounts-ui`
 
-A full featured login interface.
+A turn-key user interface for Meteor Accounts.
+
+To add Accounts and a set of login controls to an application add the
+`accounts-ui` package and one or more login provider package:
+`accounts-password`, `accounts-facebook`, `accounts-github`,
+`accounts-google`, `accounts-twitter`, and `accounts-weibo`.
+
+Then simply add the `{{dstache}}loginButtons}}` helper to an HTML
+file. This will place a login widget on the page. If there is only one
+OAuth provider configured, this will add one login/logout button. If you
+use `accounts-password` or have more than one OAuth provider, this will
+add a 'Sign in' link which opens a dropdown menu with login options. To
+make the login dropdown right aligned, use `{{dstache}}loginButtons halign=right}}`.
+
+`accounts-ui` also includes modal popup dialogs to handle links from
+<a href="#accounts_sendresetpasswordemail">`sendResetPasswordEmail`</a>, <a href="#accounts_sendverificationemail">`sendVerificationEmail`</a>,
+and <a href="#accounts_sendenrollmentemail">`sendEnrollmentEmail`</a>. These
+do not have be manually placed in HTML, they are automatically activated
+when the URLs are loaded.
 
-`XXX loginButtons` and `XXX loginButtonsRight`.
 
 
 {{/better_markdown}}

examples/leaderboard/leaderboard.js

@@ -1,5 +1,5 @@
 // Set up a collection to contain player information. On the server,
-// it is backed by a MongoDB collection named "players."
+// it is backed by a MongoDB collection named "players".
 
 Players = new Meteor.Collection("players");