Documentation

This is the Open-selector documentation :)

What is it?

Open-selector is a piece of Javascript code that will take your existing OpenID login textbox and change it into a Provider selection list, that the user can complement with their username to build their OpenID URL.

It will turn your regular OpenID login box:

OpenID Login box

Into a provider selecion list:

Open-selector

Default Open-selector providers

How it works

It will find your OpenID Login textbox and hide it. Then build the necessary HTML to display an empty providers selection list to display instead of the textbox.

After doing that, it will loop through the providers adding them to the combo box specifing how to behave when each is selected (based on each provider's properties).

Finally, will replace the form's submit method so it builds the OpenID URL based on the provider and username before actually submitting the form.

Installation and usage

You need to add this code in the page that has the OpenID login box:

<script type="text/javascript" src="/js/jquery.js"></script>
<script type="text/javascript" src="/js/open-selector.js"></script>
<script type="text/javascript">

   // ID for the OpenID form 
    open_selector.openid_form_id = 'openid_form';
    // ID for the OpenID URL box
    open_selector.openid_box_id = 'openid_url';
    open_selector.init();
</script>

Note that it currently depends on the Jquery framework.

Needed HTML

Open-selector will work on a regular OpenID login form, that is a <form> tag, with a texbox and a submit button inside, the form and textbox must have IDs.

Something like this should be enough:

<form action="/login/" method="post" id="openid_form">
    <input id="openid_url" type="text" name="openid_url" maxlength="255" />
    <input type="submit" value="Sign in"/>
</form>

Options

openid_form_id

Default value: 'openid_form'

What it does: This parameter should be set to the ID attribute of the OpenID form in order to know what submit action to look for so Open-selector can build the OpenID URL after the username and provider.

openid_box_id

Default value: 'openid_url'

What it does: Open-selector will set the built OpenID URL as the value of the HTML element with this ID. In short, the login textbox's ID.

show_credits

Default value: true

What it does: If set to false will not display the "Powered by Open-selector" paragraph below the Providers list :( .

show_label

Default value: true

What it does: If set to false will not display the "Select your provider" label, only the providers list.

update_openid_url

Default value: true

What it does: Updates(as you type) the OpenID URL displayed underneath the OpenID textbox with your actual username instead of {username}. This can lead to a bit sluggish typing, set it to false to ensure rapid response.

textbox_size

Default value: 20

What it does: Sets the size of the username textbox.

inline

Default value: false

What it does: When True renders the provider list and username textbox in a single line, this is useful when your layout can't handle such a big login box, like topbars and such.

Then your Login box will look like this:

Open-selector

Provider structure

A provider for Open-selector is a Javascript dictionary, should have the following keys:

name: The name of the OpenID Provider, this string will be displayed in the providers list.
label: The text that will be displayed with the username box, in some cases it is better to ask for the specific sites login (whatever they call it) which can be "screenname", "username", "login", whatever.
ask_username: Boolean value, whether to display or not the username box, in cases like Yahoo or Google that to not add the username as part of the OpenID URL this should be set to false.
icon: Where to get the Provider icon from, it should be a 16x16 pixel image, it's safe to use the provider's favicon.
url: Should be set to the OpenID endpoint, use "{username}" to indicate where the username should be replaced. This replaced string will be used as the OpenID URL.
info: It's extra information that will be displayed below the username box, it could contain short instructions preventing how each provider will behave.

Example:

    livejournal: {
        name: 'LiveJournal',
        label: 'Enter your Livejournal username',
        ask_username: true,
        icon: 'http://livejournal.com/favicon.ico',
        url: 'http://{username}.livejournal.com/'
    },

    yahoo: {
        name: 'Yahoo',
        info: 'Continue to Yahoo to login.',
        ask_username: false,
        icon: 'http://yahoo.com/favicon.ico',
        url: 'http://yahoo.com/'
    }

Adding more providers

The providers list is the "providers" variable at document level, so you are free to manipulate this variable before calling the init() method.

You can either redefine the dictionary or add more providers to it.

The structure of the providers variable is the following:

var providers = {
    provider_id: provider
}

Where "provider_id" is the internal ID used for the provider list, and "provider" is the provider dictonary with the above mentioned attributes.