HTML5 Roles: Enhancing Elements

In HTML5 the role attribute is used to help browsers understand the logic of your page allowing blind people to have the page read aloud. Google might also choose to interpret the role like they do the tag name.

An element can have one or more roles describing the nature of the element. 20+ ARIA roles are defined already, but you are free to define your own.

role = dialog

Programatic creation of a dialog

var dialog = HTMLElement("div",{
  "role":"dialog",
  "data-role": { 'template':'#test-dialog','content-template':'#test-content','inline':false }
});
document.body.appendChild( dialog );
DescriptorQuery(document.body).enhance();

Declare a dialog in HTML

<div role="dialog" data-role="'template':'#test-dialog','content-template':'#test-content','inline':false"></div>

The config.template is used to specify how to render the dialog. Without it whatever content is already in the element is what will be enhanced. If you add a header element in the template it will enable the user to drag and activate the dialog.

If you put role dialog on a form it will take over the form functionality. On other elements it will add functions like form.submit and form.reset.

Button elements are enhanced by default.

Choosing the content

If an element in the dialog template is given role="content" the element will be replaced with the configured content. Otherwise content is appended to the dialog element.

A class attribute of "dialog-content" is appended to the content element. Specify content-class to change the appended class.

You can specify a template to be rendered as the content using content-template:#someId.

Alternately you can create custom content.

Custom content

If you want to embed a custom element as the dialog content pick a content-role and specify content-config. content-role can be any enabled role other than popups. content-config is the configuration passed when enhancing the content-role.

Positioning

The dialogs are placed in a stacked fashion from the top left moving down and right by default. If "tile":true is added to the config they are placed side by side like game cards. The height is restricted if it is higher than the document body squeezing it inside the full height of the body.

To place a dialog at a specific location set placement in config. E.G. 'placement':{'right':50,'bottom':50}

role = toolbar

The toolbar is like dialogs but inline.

role = spinner

role = template

This allows you to add HTML5 template compatible elements.

more ...

role = scrolled

This allows you to add custom scrollbars to an element by putting an element inside it to hold the content. By having three elements nested, you can add non-scrolling elements easily.

<section><div><div role="scrolled"> scrolled content </div></div></section>

By default the scroll bars are placed inside the box on top of the scrolled content. Scrolled Element

role = sheet

role = application

config.template config.variant config.generator

Custom Enhanced Role

The minimum for making an enhanced custom role is the following call.

Resolver("page").set("handlers.enhance.my-role-name",function(el,role,config) {
  // role will be == "my-role-name"
  // tweak the element here
});