Aloha Editor GuidesAloha Editor Guides: List Plugin

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.

The list plugin will turn existing paragraphs into list items. Single lines separated by
tags will NOT be turned into separate list items.

1 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.

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

2 Configuration settings

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


Aloha.settings.plugins: {
	list: {
		config: [ 'ol', 'ul', 'dl' ],
		editables: {
			'#one': [ 'ul' ],
			'#two': [ ]
		},
		// Explained below
		defaultClasses: {},
		templates: {},
	}
};

3 Class lists

Class lists are either string or string[], and define which classes are to be applied on which nesting level. If it’s a simple string, it will be treated like an array with the string as single value.

The index within the array determines which nesting level it will be applied to. If the nesting is deeper than what the array has defined, it will use the last value in the array.

4 Default classes

Default classes can be defined for each list type, and will be applied to all lists. The default classes can be set for the list itself aswell as for it’s items.


Aloha.settings.plugins.list = {
	defaultClasses: {
		ul: {
			list: ['my-bullet-list', 'my-nested-list'],
			item: 'list-item my-bullet-list__item'
		},
	},
};


<ul class="my-bullet-list">
	<li class="list-item my-bullet-list__item">First level item</li>
	<li class="list-item my-bullet-list__item">First level item</li>

	<ul class="my-nested-list">
		<li class="list-item my-bullet-list__item">Second level item</li>
		<li class="list-item my-bullet-list__item">Second level item</li>

		<ul class="my-nested-list">
			<li class="list-item my-bullet-list__item">Third level item</li>
			<li class="list-item my-bullet-list__item">Third level item</li>
		</ul>
	</ul>
</ul>

5 Templates

Templates can be selected by an editor and define which classes are to be applied to the list items. Multiple templates can be defined, but an editor may only choose one at a time.


Aloha.settings.plugins.list = {
	templates: {
		dl: [
			{
				label: 'Symbols',
				classes: ['aloha-list-disc', 'aloha-list-circle', 'aloha-list-square'],
			},
			{
				label: 'Colors',
				classes: ['aloha-list-blue', 'aloha-list-green', 'aloha-list-red'],
			},
		],
	},
};


<dl class="aloha-list-disc">
	<dt>First level item title<dt>
	<dd>First level item description</dd>

	<dt>First level item title<dt>
	<dd>First level item description</dd>

	<dl class="aloha-list-circle">
		<dt>Second level item title<dt>
		<dd>Second level item description</dd>

		<dt>Second level item title<dt>
		<dd>Second level item description</dd>

		<dl class="aloha-list-square">
			<dt>Second level item title<dt>
			<dd>Second level item description</dd>

			<dt>Second level item title<dt>
			<dd>Second level item description</dd>
		</dl>
	</dl>
</dl>

6 Combining both

When both default classes and templates are used, then both classes are merged and applied.


Aloha.settings.plugins.list = {
	defaultClasses: {
		ol: {
			list: ['my-list', 'nested-list'],
			item: ['generic-item', 'generic-nested-item']
		},
	},
	templates: {
		ol: [
			{
				label: 'Numbers',
				classes: [
					'aloha-list-decimal',
					'aloha-list-roman',
					'aloha-list-greek',
				]
			}
		]
	}
};


<ol class="my-list aloha-list-decimal">
	<li class="generic-item">First level item</li>
	<li class="generic-item">First level item</li>

	<ol class="nested-list aloha-list-roman">
		<li class="generic-nested-item">Second level item</li>
		<li class="generic-nested-item">Second level item</li>

		<ol class="nested-list aloha-list-greek">
			<li class="generic-nested-item">Third level item</li>
			<li class="generic-nested-item">Third level item</li>
		</ol>
	</ol>
</ol>

7 Components

The List Plugin provides three components

ol – for inserting ordered lists
ul – for inserting unordered lists
dl – for inserting definition lists