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.

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

Updating the documentation to make selection of elements clear. #148

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

Updating the documentation to make selection of elements clear. #148

Show file tree
Hide file tree
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
88 changes: 46 additions & 42 deletions google-signin-aware.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -486,48 +486,52 @@

AuthEngine.init();

/**
`google-signin-aware` is used to enable authentication in custom elements by
interacting with a google-signin element that needs to be present somewhere
on the page.

The `scopes` attribute allows you to specify which scope permissions are required
(e.g do you want to allow interaction with the Google Drive API).

The `google-signin-aware-success` event is triggered when a user successfully
authenticates. If either `offline` or `offlineAlwaysPrompt` is set to true, successful
authentication will also trigger the `google-signin-offline-success`event.
The `google-signin-aware-signed-out` event is triggered when a user explicitly
signs out via the google-signin element.

You can bind to `isAuthorized` property to monitor authorization state.
##### Example

<google-signin-aware scopes="https://www.googleapis.com/auth/drive"></google-signin-aware>


##### Example with offline
<template id="awareness" is="dom-bind">
<google-signin-aware
scopes="https://www.googleapis.com/auth/drive"
offline
on-google-signin-aware-success="handleSignin"
on-google-signin-offline-success="handleOffline"></google-signin-aware>
<\/template>
<script>
var aware = document.querySelector('#awareness');
aware.handleSignin = function(response) {
var user = gapi.auth2.getAuthInstance().currentUser.get();
console.log('User name: ' + user.getBasicProfile().getName());
};
aware.handleOffline = function(response) {
console.log('Offline code received: ' + response.detail.code);
// Here you would POST response.detail.code to your webserver, which can
// exchange the authorization code for an access token. More info at:
// https://developers.google.com/identity/protocols/OAuth2WebServer
};
<\/script>
*/
/**
`<google-signin-aware>` is used to enable authentication in custom elements.

The `scopes` attribute allows you to specify which scope permissions are required
(e.g do you want to allow interaction with the Google Drive API).

The `google-signin-aware-success` event is triggered when a user successfully
authenticates. If either `offline` or `offlineAlwaysPrompt` is set to true, successful
authentication will also trigger the `google-signin-offline-success`event.
The `google-signin-aware-signed-out` event is triggered when a user explicitly
signs out via the google-signin element.

You can bind to `isAuthorized` property to monitor authorization state.

The `<google-signin>` element provides the standard Google signin button UI and should be placed
within the application to allow the user to trigger the authentication. When opting to use a
custom signin UI, trigger the authentication by calling the `signin()` method of the
`<google-signin-aware>` component.

#### Example

<google-signin-aware scopes="https://www.googleapis.com/auth/drive"></google-signin-aware>

#### Example with offline

<template id="awareness" is="dom-bind">
<google-signin-aware
scopes="https://www.googleapis.com/auth/drive"
offline
on-google-signin-aware-success="handleSignin"
on-google-signin-offline-success="handleOffline"></google-signin-aware>
<\/template>
<script>
var aware = document.querySelector('#awareness');
aware.handleSignin = function(response) {
var user = gapi.auth2.getAuthInstance().currentUser.get();
console.log('User name: ' + user.getBasicProfile().getName());
};
aware.handleOffline = function(response) {
console.log('Offline code received: ' + response.detail.code);
// Here you would POST response.detail.code to your webserver, which can
// exchange the authorization code for an access token. More info at:
// https://developers.google.com/identity/protocols/OAuth2WebServer
};
<\/script>
*/
Polymer({

is: 'google-signin-aware',
Expand Down
94 changes: 47 additions & 47 deletions google-signin.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,73 +118,73 @@
WIDE: 'wide'
};

/**
&lt;google-signin&gt; is used to authenticate with Google, allowing you to interact
with other Google APIs such as Drive and Google+.

<img style="max-width:100%;" src="https://cloud.githubusercontent.com/assets/107076/6791176/5c868822-d16a-11e4-918c-ec9b84a2db45.png"/>

If you do not need to show the button, use companion `<google-signin-aware>` element to declare scopes, check authentication state.
/**
`<google-signin>` is used to authenticate with Google, allowing you to interact
with other Google APIs such as Drive and Google+.

#### Examples
<img style="max-width:100%;" src="https://cloud.githubusercontent.com/assets/107076/6791176/5c868822-d16a-11e4-918c-ec9b84a2db45.png"/>

<google-signin client-id="..." scopes="https://www.googleapis.com/auth/drive"></google-signin>
#### Examples

<google-signin label-signin="Sign-in" client-id="..." scopes="https://www.googleapis.com/auth/drive"></google-signin>
<google-signin client-id="..." scopes="https://www.googleapis.com/auth/drive"></google-signin>

<google-signin theme="dark" width="iconOnly" client-id="..." scopes="https://www.googleapis.com/auth/drive"></google-signin>
<google-signin label-signin="Sign-in" client-id="..." scopes="https://www.googleapis.com/auth/drive"></google-signin>

<google-signin theme="dark" width="iconOnly" client-id="..." scopes="https://www.googleapis.com/auth/drive"></google-signin>

#### Notes
#### Notes
Copy link
Contributor

@ebidel ebidel Jun 7, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why the indentation? For the doc viewer, this is read as markdown, so 4-space indents will make this a code block.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't it use the spacing of the opening comment as the base for all of the lines?
If that is not true then I'll have to change it back.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's probably easier if we just make the docs a html comment like https://github.com/GoogleWebComponents/google-sheets/blob/master/google-sheets.html#L7.


The attribute `clientId` is provided in your Google Developers Console
(https://console.developers.google.com).
If you do not want to display the signin button, use the `<google-signin-aware>` element to
declare scopes and listen for authentication events. If there is no `<google-signin>` element on
the page the `<google-signin-aware>.signIn()` will need to be manually triggered.

The `scopes` attribute allows you to specify which scope permissions are required
(e.g do you want to allow interaction with the Google Drive API). Many APIs also
need to be enabled in the Google Developers Console before you can use them.
The attribute `clientId` is provided in your Google Developers Console
(https://console.developers.google.com).

The `requestVisibleActions` attribute is necessary if you want to write app
activities (https://developers.google.com/+/web/app-activities/) on behalf of
the user. Please note that this attribute is only valid in combination with the
plus.login scope (https://www.googleapis.com/auth/plus.login).
The `scopes` attribute allows you to specify which scope permissions are required
(e.g do you want to allow interaction with the Google Drive API). Many APIs also
need to be enabled in the Google Developers Console before you can use them.

The `offline` attribute allows you to get an auth code which your server can
redeem for an offline access token
(https://developers.google.com/identity/sign-in/web/server-side-flow).
You can also set `offline-always-prompt` instead of `offline` to ensure that your app
will re-prompt the user for offline access and generate a working `refresh_token`
even if they have already granted offline access to your app in the past.
The `requestVisibleActions` attribute is necessary if you want to write app
activities (https://developers.google.com/+/web/app-activities/) on behalf of
the user. Please note that this attribute is only valid in combination with the
plus.login scope (https://www.googleapis.com/auth/plus.login).

Use label properties to customize prompts.
The `offline` attribute allows you to get an auth code which your server can
redeem for an offline access token
(https://developers.google.com/identity/sign-in/web/server-side-flow).
You can also set `offline-always-prompt` instead of `offline` to ensure that your app
will re-prompt the user for offline access and generate a working `refresh_token`
even if they have already granted offline access to your app in the past.

The button can be styled in using the `height`, `width`, and `theme` attributes.
These attributes help you follow the Google+ Sign-In button branding guidelines
(https://developers.google.com/+/branding-guidelines).
Use label properties to customize prompts.

The `google-signin-success` event is triggered when a user successfully authenticates
and `google-signed-out` is triggered when user signs out.
You can also use `isAuthorized` attribute to observe user's authentication state.
The button can be styled in using the `height`, `width`, and `theme` attributes.
These attributes help you follow the Google+ Sign-In button branding guidelines
(https://developers.google.com/+/branding-guidelines).

Additional events, such as `google-signout-attempted` are
triggered when the user attempts to sign-out and successfully signs out.
The `google-signin-success` event is triggered when a user successfully authenticates
and `google-signed-out` is triggered when user signs out.
You can also use `isAuthorized` attribute to observe user's authentication state.

When requesting offline access, the `google-signin-offline-success` event is
triggered when the user successfully consents with offline support.
Additional events, such as `google-signout-attempted` are
triggered when the user attempts to sign-out and successfully signs out.

The `google-signin-necessary` event is fired when scopes requested via
google-signin-aware elements require additional user permissions.
When requesting offline access, the `google-signin-offline-success` event is
triggered when the user successfully consents with offline support.

#### Testing
The `google-signin-necessary` event is fired when scopes requested via
google-signin-aware elements require additional user permissions.

By default, the demo accompanying this element is setup to work on localhost with
port 8080. That said, you *should* update the `clientId` to your own one for
any apps you're building. See the Google Developers Console
(https://console.developers.google.com) for more info.
#### Testing

@demo
*/
By default, the demo accompanying this element is setup to work on localhost with
port 8080. That said, you *should* update the `clientId` to your own one for
any apps you're building. See the Google Developers Console
(https://console.developers.google.com) for more info.

@demo
*/
Polymer({

is: 'google-signin',
Expand Down