12. convert
Prev | Chapter 6. Commands written in the Java™ programming language | Next

## 12. convert

Parameter syntax:

    [ implicit_selection ]? [ S argument_node ]?

Converts text selection or selected nodes to argument node.

Unlike replace which creates an empty new element, convert transfers the content of the selection to the new element which is the result of the conversion.

More precisely, in the case of node selection:

- When a single element is selected, all its children, and also all compatible attributes, are transferred to the result of the conversion.

  Example:

  <simpara id="p1">the <emphasis>little</emphasis> girl.</simpara>

  converted to `para` gives

  <para id="p1">the <emphasis>little</emphasis> girl.</para>

- When several nodes or a single non-element node are selected, all these nodes are given a new parent element which is the result of the conversion.

  Example:

  <simpara>Once upon a time.</simpara>

  plus

  <simpara id="p1">the <emphasis>little</emphasis> girl.</simpara>

  can be converted to `blockquote` and that gives us

  <blockquote>
  <simpara>Once upon a time.</simpara>
  <simpara id="p1">the <emphasis>little</emphasis> girl.</simpara>
  </blockquote>

Note that when argument node is an element template, command `convert` copies the attributes of the element template and ignores its child nodes.

Examples:

    convert emphasis
    convert [implicitElement] #text
    convert #template({http://www.w3.org/1999/xhtml}span,highlight)

See also command wrap, a variant of command convert which has a different behavior in the case of single element selection.

Prev | Up | Next
11. contextualMenu | Home | 13. convertCase