dojox/editor/plugins/BidiSupport (version 1.10)

dijit/_editor/_Plugin

Summary

This plugin provides some advanced BiDi support for rich text editing widget. It adds several bidi-specific commands, which are not released in native RTE's ('set text direction to left-to-right', 'set text direction to right-to-left', 'change text direction to opposite') and overrides some existing native commands.

Usage

var foo = new BidiSupport(args);
dijit/_editor/_Plugin
Parameter Type Description
args Object
Optional

Initial settings for any of the attributes.

See the dojox/editor/plugins/BidiSupport reference documentation for more information.

Property Summary

Method Summary

Properties

_blockContainers
_indentBy
_lineStyledTextArray
_lineTextArray
_tableContainers
blockMode

This property decides the behavior of Enter key, actually released by EnterKeyHandling plugin. Possible values are 'P' and 'DIV'. Used when EnterKeyHandling isn't included into the list of the base plugins, loaded with the current Editor, as well as in case,
if blockNodeForEnter property of EnterKeyHandling plugin isn't set to 'P' or 'DIV'. The default value is "DIV".

bogusHtmlContent

HTML to stick into a new empty block

button
Defined by: dijit/_editor/_Plugin

Pointer to dijit/form/Button or other widget (ex: dijit/form/FilteringSelect) that is added to the toolbar to control this plugin. If not specified, will be created on initialization according to buttonClass

buttonClass
buttonLtr

Used to set direction of the selected text to left-to-right.

buttonRtl

Used to set direction of the selected text to right-to-left.

command
disabled
Defined by: dijit/_editor/_Plugin

Flag to indicate if this plugin has been disabled and should do nothing helps control button state, among other things. Set via the setter api.

editor
Defined by: dijit/_editor/_Plugin

Points to the parent editor

iconClassPrefix

The CSS class name for the button node icon.

shortcutonly

If this property is set to 'false', plugin handles all text direction commands and its behavior is controlled both by buttons and by shortcut (Ctrl+Shift+X). In opposite case only command 'change text direction to opposite', controlled by shortcut, is supported, and buttons don't appear in the toolbar. Defaults to false.

useDefaultCommand

Methods

_changeState(cmd,arg)

Determines and refines current selection and calls method _changeStateOfBlocks(), where given action is actually done

The main goal of this method is correctly identify the block elements, that are at the beginning and end of the current selection.

Parameter Type Description
cmd undefined
arg undefined
Returns:undefined
_changeStateOfBlocks(startNode,endNode,commonAncestor,cmd,arg,tempRange)

Collects all block elements, containing text, which are inside of current selection, and performs for each of them given action. Possible commands and corresponding actions: - "ltr": change direction to left-to-right - "rtl": change direction to right-to-left - "mirror": change direction to opposite - "explicitdir": explicit direction setting - "left": change alignment to left - "right": change alignment to right - "center": change alignment to center - "preparelists": action should be done before executing native insert[un]orderedlist - "prepareoutdent": action should be done before executing native outdent - "prepareindent": action should be done before executing native indent - "prepareformat": action should be done before executing native formatblock - "insertunorderedlist": action should be done after executing native insertunorderedlist - "insertorderedlist": action should be done after executing native insertorderedlist - "indent": action should be done after executing native indent - "outdent": action should be done after executing native outdent - "normalizeindent": emulate indent done by NormalizeIndentOutdent plugin - "normalizeoutdent": emulate outdent done by NormalizeIndentOutdent plugin - "formatblock": action should be done after executing native formatblock

Parameter Type Description
startNode undefined
endNode undefined
commonAncestor undefined
cmd undefined
arg undefined
tempRange undefined
Returns:object
_checkNewLine()
_cleanLists()

Removes remaining bogus elements, creating by the method _prepareLists()

_collectNodes(startNode,endNode,commonAncestor,tempRange,nodes,origStartContainer,origStartOffset,origEndContainer,origEndOffset,cmd)

Collect all selected block elements, which contain or can contain text. Walk through DOM tree between start and end points of current selection.

Parameter Type Description
startNode undefined
endNode undefined
commonAncestor undefined
tempRange undefined
nodes undefined
origStartContainer undefined
origStartOffset undefined
origEndContainer undefined
origEndOffset undefined
cmd undefined
Returns:object
_createButton(direction)

Initialize specific button.

Parameter Type Description
direction undefined
Returns:undefined
_execDirAndAlignment(nodesInfo,cmd,arg)

Change direction and/or alignment of each node from the given array.

Parameter Type Description
nodesInfo undefined
cmd undefined
arg undefined
_execFormatBlocks(nodesInfo,arg)
Parameter Type Description
nodesInfo undefined
arg undefined
_execIndent(nodesInfo)
Parameter Type Description
nodesInfo undefined
_execInsertLists(nodesInfo)
Parameter Type Description
nodesInfo undefined
_execNativeCmd(cmd,arg,info)

Call native command for nodes inside selection

Sometimes native commands "insertorderedlist", "insertunorderedlist", "indent", "outdent" and "formatblocks" are the cause of various problems. These problems have different levels of severity - from crashing of their executing or damage of the editor's content to creating visually correct results, which however can cause the future problems,
not always bidi-specific. For example, Webkit fails with insertlist commands, if selection
contains some block element (like

or
), followed by the table, and few cells of
this table.IE fails,when try to handle insertlist command for list items, containing
.
Mozilla and IE produce wrong results for selection,containing more then one cell. Mozilla
merges contents of some listitems with "formatblock" command. Safari places DIV's in the same list with newly created list items. Webkit creates multilevel blocks to format the text.
IE adds to the list lines of the text,which are outside the selection. Webkit put whole table
into list item. All browsers lose direction and alignment styles with outdent command,
executed for items from one-level list. Etc. We try to avoid these problems and produce correct (and more or less similar) results for
all supported browsers. This is achieved by separating the each above-mentioned command into three parts. The first ("preparelist","prepareindent","prepareoutdent" and "prepareformat") is performed before corresponding native call. It prepares selected region of the editor's content by rebuilding it with strong block structure and keeps info about each group of selected
elements. Separate groups are created for contents of each table cell, as well as for lines of text that are before, after and between tables. In case of webkit and insertlist or formatblocks commands, each selected block element is placed into separate "group". The second part of the command is native call itself. Native calls are executed separately for each group of nodes. This requires to reset a selection, each time limiting it to only
the elements of the current group. The third part is perfomed after native call. Its role is to restore missing styles,
to delete bogus elements, created in the previous steps, to merge sibling lists etc.
Corresponding commands have the same names, as native (e.g., "insertorderedlist',
"insertunorderedlist", "indent", "outdent" and "formatblocks"), because just they produce the final result. For IE and Mozilla we call one "post" command per native call. For webkit we call one "post" command per group of elements.

Parameter Type Description
cmd undefined

Name of the command (like "insertorderedlist" or "indent")

arg undefined

Arguments of the command

info undefined

Object containing nodes: array of all block nodes, which should be handled by this command groups: array containing groups of nodes. Nodes from each group should be handled by separate execution of current command cells: array of cells, contents of which should be handled by current command

Returns:boolean

_execNormalizedIndent(nodesInfo)
Parameter Type Description
nodesInfo undefined
_execNormalizedOutdent(nodesInfo)
Parameter Type Description
nodesInfo undefined
_execOutdent(nodesInfo)
Parameter Type Description
nodesInfo undefined
_formatBlocks(arg)

Overrides native formatblock command.

Overrides native formatblock command with the goal to avoid some bidi-specific problems that arise when this command is executed. Performed in three steps: 1) prepares selected fragment of the document to execution of native command (Mozilla only). 2) executes native command 3) updates contents of selected fragment of the document after execution of native comand.

Parameter Type Description
arg undefined

Tag name of block type, like H1, DIV or P.

Returns:boolean
_getAttrNames(name)

Helper function for get() and set(). Caches attribute name values so we don't do the string ops every time.

Parameter Type Description
name undefined
Returns:undefined | object
_getBlockAncestor(node)
Parameter Type Description
node undefined
Returns:undefined
_getClosestBlock(node,point,tempRange)

Searches for a closest block element containing the text which is at a given point of current selection. Refines current selection, if text element from start or end point was merged with its neighbors.

Parameter Type Description
node undefined
point undefined
tempRange undefined
Returns:undefined
_getIntStyleValue(node,style)
Parameter Type Description
node undefined
style undefined
Returns:undefined
_getLIIndent(node)
Parameter Type Description
node undefined
Returns:number
_getLILevel(node)
Parameter Type Description
node undefined
Returns:number
_getListMargins(node)
Parameter Type Description
node undefined
Returns:number
_getMargins(level)
Parameter Type Description
level undefined
Returns:number
_getParentFrom(node,arr)
Parameter Type Description
node undefined
arr undefined
Returns:null | undefined
_handleNoFormat(editor,command,choice)
Parameter Type Description
editor undefined
command undefined
choice undefined
Returns:Array | undefined
_hasStyledTextLineTag(node)
Parameter Type Description
node undefined
Returns:undefined
_hasTag(node,tag)
Parameter Type Description
node undefined
tag undefined
Returns:undefined
_hasTagFrom(node,arr)
Parameter Type Description
node undefined
arr undefined
Returns:undefined
_indentAndOutdent(cmd)

Overrides native indent and outdent commands.

Overrides native indent and outdent commands with the goal to avoid some bidi-specific problems that arise when these commands are executed. Performed in three steps: 1) prepares selected fragment of the document to execution of native command (outdent only). 2) executes corresponding native command 3) updates contents of selected fragment of the document after execution of native comand.

Parameter Type Description
cmd undefined

Name of the command, of of "indent" or "outdent"

Returns:boolean
_initButton()

Override _Plugin._initButton(). Creates two buttons, used for setting text direction to left-to-right and right-to-left.

_insertLists(cmd)

Overrides native insertorderlist and insertunorderlist commands.

Overrides native insertorderlist and insertunorderlist commands with the goal to avoid some bidi-specific problems that arise when these commands are executed. Performed in three steps: 1) prepares selected fragment of the document to execution of native command. 2) executes corresponding native command 3) updates contents of selected fragment of the document after execution of native comand.

Parameter Type Description
cmd undefined

Name of the command, one of "insertorderedlist" or "insertunorderedlist"

Returns:boolean
_isBlockElement(node)
Parameter Type Description
node undefined
Returns:boolean
_isBlockWithText(node)
Parameter Type Description
node undefined
Returns:boolean
_isElement(node)
Parameter Type Description
node undefined
Returns:undefined
_isInlineOrTextElement(node)
Parameter Type Description
node undefined
Returns:boolean
_isListTypeChanged(node,cmd)

Returns true, if command "insertorderedlist" executed for item from unordered list and if command "insertunorderedlist" executed for item from ordered list

Parameter Type Description
node undefined
cmd undefined
Returns:boolean | undefined
_isSimpleInfo(info)

returns true, if all nodes, for which current action should be executed, may be handled in the same time (so, all nodes are in the same group)

Parameter Type Description
info undefined
Returns:boolean
_mergeLists()

In some cases (like "formatblocks" for list items) lists of the the same type are created as a siblings inside the same parent. These lists should be merged.

_preFilterNewLines(html)
Parameter Type Description
html undefined
Returns:undefined
_prepareFormat(nodesInfo,arg)
Parameter Type Description
nodesInfo undefined
arg undefined
_prepareIndent(nodesInfo)
Parameter Type Description
nodesInfo undefined
_prepareLists(nodesInfo,arg)

Perform changes before native insertorderedlist and insertunorderedlist commands for each node from the given array.

Parameter Type Description
nodesInfo undefined
arg undefined
_prepareOutdent(nodesInfo)
Parameter Type Description
nodesInfo undefined
_rebuildBlock(block)

Finds a sequences of inline elements that are placed within a top-level block element or have block siblings. Calls _repackInlneElements(), which moves this sequences into newly created block.

Parameter Type Description
block undefined
_recountLIMargins(node,addValue)
Parameter Type Description
node undefined
addValue undefined
_refineAlignment(dir,align)

Refine the value, which should be used as textAlign style.

This method allows to keep textAlign styles only for cases, when it is defined explicitly.

Parameter Type Description
dir undefined
align undefined
Returns:string
_refineLIMargins(node)

Line items, orientation of which is differ from their parents, arn't shown correctly by all browsers. Problem is solved by adding corresponding margins.

Parameter Type Description
node undefined
_repackInlineElements(firstSibling,lastSibling,parent)

Moves sequences of inline elements into newly created blocks

This method handles sequences of inline elements, which are recognized by the user as separate line(s) of the text, but are not placed into their own block element. Text direction or alignment can't be set for such lines. Possibles cases: a) sequence directly belongs to editor's editNode; b) sequence has block-level siblings; c) sequence has BR in the start or in the middle of it. For all these cases we create new block and move elements from the sequence into it. We try to preserve explicitly defined styles, which have effect on this line. In case of sequences, which directly belong to editNode, it is only direction of the text.

Parameter Type Description
firstSibling undefined
lastSibling undefined
parent undefined
Returns:Array
_set(name,value)

Helper function to set new value for specified attribute

Parameter Type Description
name String
value anything
_setDisabledAttr(disabled)

Function to set the plugin state and call updateState to make sure the button is updated appropriately.

Parameter Type Description
disabled undefined
_tag(node)
Parameter Type Description
node undefined
Returns:undefined
connect(o,f,tf)

Deprecated. Use this.own() with dojo/on or dojo/aspect.instead.

Make a connect.connect() that is automatically disconnected when this plugin is destroyed. Similar to dijit/_Widget.connect().

Parameter Type Description
o undefined
f undefined
tf undefined
destroy()
get(name)

Get a property from a plugin.

Get a named property from a plugin. The property may potentially be retrieved via a getter method. If no getter is defined, this just retrieves the object's property. For example, if the plugin has a properties "foo" and "bar" and a method named "_getFooAttr", calling:

plugin.get("foo");

would be equivalent to writing:

plugin._getFooAttr();

and:

plugin.get("bar");

would be equivalent to writing:

plugin.bar;
Parameter Type Description
name undefined

The property to get.

Returns:undefined
getLabel(key)

Returns the label to use for the button

Parameter Type Description
key String
Returns:undefined
own()
Defined by dijit/Destroyable

Track specified handles and remove/destroy them when this instance is destroyed, unless they were already removed/destroyed manually.

Returns:any | undefined

The array of specified handles, so you can do for example:

var handle = this.own(on(...))[0];
set(name,value)

Set a property on a plugin

Sets named properties on a plugin which may potentially be handled by a setter in the plugin. For example, if the plugin has a properties "foo" and "bar" and a method named "_setFooAttr", calling:

plugin.set("foo", "Howdy!");

would be equivalent to writing:

plugin._setFooAttr("Howdy!");

and:

plugin.set("bar", 3);

would be equivalent to writing:

plugin.bar = 3;

set() may also be called with a hash of name/value pairs, ex:

plugin.set({
    foo: "Howdy",
    bar: 3
})

This is equivalent to calling set(foo, "Howdy") and set(bar, 3)

Parameter Type Description
name attribute

The property to set.

value anything

The value to set in the property.

Returns:function | string

Set a property on a plugin

setEditor(editor)

Override _Plugin.setEditor().

Sets editor's flag 'advancedBidi' to true, which may be used by other plugins as a switch to bidi-specific behaviour. Adds bidi-specific filters, including postDom filter, which provides explicit direction settings for the blocks of the text, direction of which isn't defined. Overrides some native commands, which should be changed or expanded in accordance with bidi-specific needs. Loads EnterKeyHandling plugin, if it was not loaded, and changes its blockNodeForEnter property, if it is needed. Defines shortcut, which will cause execution of 'change text direction to opposite' ('mirror') command.

Parameter Type Description
editor dijit.Editor
setToolbar(toolbar)

Override _Plugin.setToolbar(). Adds buttons so, that 'ltr' button will appear from the left of 'rtl' button regardless of the editor's orientation.

Parameter Type Description
toolbar dijit.Toolbar
updateState()

Override _Plugin.updateState(). Determines direction of the text in the start point of the current selection. Changes state of the buttons correspondingly.

Error in the documentation? Can’t find what you are looking for? Let us know!