h2. List Plugin

The List Plugin allows you to handle and create ordered, unordered and definition lists within your contents. You either may select existing contents to be turned into a list, or just click one of the list buttons to start a new one.

endprologue.

NOTE: The list plugin will turn existing paragraphs into list items. Single lines separated by +<br>+ tags will *NOT* be turned into separate list items.


h3. Functional Description

Move the cursor to your desired position and click on the ordered +<ol>+, unordered +<ul>+ or definition +<dl>+ list icon in the Aloha Editor toolbar to start creating a list. Now you can enter list elements and add a new ones by pressing enter on your keyboard. To end adding new list elements press enter twice. Now you are able to enter paragraphs again.
In order to add new elements or edit existing elements just move to cursor to the desired position of the list and add via pressing enter or edit elements.
To delete an element or the whole list mark the element(s) and press backspace.

You can use the tab key to indent unordered and ordered lists or use shift-tab to outdent them if you are inside of a nested list (only unordered and ordered lists). The type of lists and nested lists may be changed between unordered, ordered and definition lists by clicking the corresponding list button from the Aloha toolbar.

You can remove lists by clicking the applied list type a second time, which will turn individual list items back into paragraphs.

NOTE: Although allowed by the HTML specification, Aloha Editor will not allow nesting of paragraphs or headers in list items.

h4. List styles

If you open the dropdown next to the respective list icon, you can choose from a list of pre-defined list styles.
Shipped with Aloha Editor are the following:

h5. Unordered list styles

* disc
* circle
* square

h5. Ordered list styles

* decimal
* decimal-leading-zero
* lower-roman
* upper-roman
* lower-greek
* lower-latin
* upper-latin

h5. Definition list styles

* blue
* green
* red

h3. Configuration settings

Add the available components +'ol', 'ul', 'dl'+ to the editables where you want to use them:

<javascript>
	Aloha.settings.plugins: {
		list: {
			config: [ 'ol', 'ul', 'dl' ],
			editables: {
				'#one': [ 'ul' ],
				'#two': [ ]
			}
		}
	}
</javascript>

To define custom list styles use the following syntax:

<javascript>
    Aloha.settings.plugins.list = {
    	templates: {
    		ul: {
    			classes: ['aloha-list-disc', 'aloha-list-circle', 'aloha-list-square'],
    			template: '<ul class="${cssClass}"><li>${first}<ul class="${cssClass}"><li>${second}<ul class="${cssClass}"><li>${third}</li></ul></li></ul></li></ul>',
    			locale: {
    				fallback: {first: 'first layer', second: 'second layer', third: 'third layer'},
    				de: {first: 'erste Ebene', second: 'zweite Ebene', third: 'dritte Ebene'}
    			}
    		},
    		ol: {
    			classes: ['aloha-list-decimal', 'aloha-list-decimal-leading-zero',
    				'aloha-list-lower-roman', 'aloha-list-upper-roman', 'aloha-list-lower-greek',
    				'aloha-list-lower-latin', 'aloha-list-upper-latin' ],
    			template: '<ol class="${cssClass}"><li>${first}<ol class="${cssClass}"><li>${second}<ol class="${cssClass}"><li>${third}</li></ol></li></ol></li></ol>',
    			locale: {
    				fallback: {first: 'first layer', second: 'second layer', third: 'third layer'},
    				de: {first: 'erste Ebene', second: 'zweite Ebene', third: 'dritte Ebene'}
    			}
    		},
    		dl: {
    			classes: ['aloha-list-blue', 'aloha-list-green', 'aloha-list-red'],
    			template: '<dl class="${cssClass}"><dt>${first}<dt><dd>${second}</dd></dl>',
    			locale: {
    				fallback: {first: 'first item', second: 'second item'},
    				de: {first: 'erstes Element', second: 'zweites Element'}
    			}
    		},
    	},
    	// defaultClasses are optional classes which will be applied to all lists and list items for which they are defined.
    	// The classes to be added are provided as a string or as an array of strings.
    	//
    	// - If defined as a string, then that class (or multiple classes separated by a space) will be applied to all
    	// lists or items of that type.
    	// - If defined as an array of strings, then those classes will be applied according to the nesting level of
    	// the list.
    	//
    	// For example, in the "ol" definition below, the class "my-numbered-list" will be applied to all non-nested OL elements.
    	// Any nested OL lists will have the classes "my-numbered-list" & "my-numbered-list--nested" applied.
    	// The items of the root list will have the class "my-numbered-list__item" applied, and items of list nested 1-level deep
    	// will have the classes "my-numbered-list__item" & "my-numbered-list__item--lvl-1" applied, and so on. The last item in the
    	// list "--lvl-4" will then be used for all further nesting levels beyond that point.
    	defaultClasses: {
    		ul: {
    			list: 'my-bullet-list',
    			item: 'list-item my-bullet-list__item'
    		},
    		ol: {
    			list: ['my-numbered-list', 'my-numbered-list my-numbered-list--nested'],
    			item: [
    				'my-numbered-list__item',
    				'my-numbered-list__item my-numbered-list__item--lvl-1',
    				'my-numbered-list__item my-numbered-list__item--lvl-2',
    				'my-numbered-list__item my-numbered-list__item--lvl-3',
    				'my-numbered-list__item my-numbered-list__item--lvl-4'
    			]
    		},
    		dl: {
    			list: ['my-dl-list'],
    			item: ['my-dl-item']
    		}
    }
</javascript>

h3. Components

The List Plugin provides three components

* ol - for inserting ordered lists
* ul - for inserting unordered lists
* dl - for inserting definition lists
