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:

Into a provider selecion list:

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.

If the user has logged in before using open-selector, then the provider and username will be selected the following times he or she visits.

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">

    // Set here any other attribute
    //open_selector.sprite = 'http://mysite.com/sprite.png';
    //open_selector.sprite_size = 22;
    //open_selector.inline = true;

    // 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:

sprite

Default value: undefined

What it does: should have a valid path to a sprite image containing the providers icons, the position of each provider icon should be specified on the sprite_pos attribute on each provider. It should be a vertical sprite. You can use this one for 22x22 pixel sprites.

sprite_size

Default value: undefined

What it does: Contains the size of each icon, this is used to set the left alignment and height of the combo options, only needed if a sprite is specified.

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.

sprite_pos

The vertical position of the provider icon on the sprite (if used), the topmost provider should have 0. If no sprite is used, you do not need to set this attribute.

Example:

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

    yahoo: {
        name: 'Yahoo',
        info: 'Continue to Yahoo to login.',
        ask_username: false,
        icon: 'http://yahoo.com/favicon.ico',
        sprite_pos: 22, // 2nd provider for a 22 size icon
        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.