42.1. Specifying an element template for use by command formatTextAs

42.1. Specifying an element template for use by command `formatTextAs`
	42. formatTextAs

42.1. Specifying an element template for use by command `formatTextAs`

For example, let's suppose the clipboard contains:

This is→line→#1.
This is→line→#2.

This is→line→#3.
This is→line→#4.

The → symbol represents a tab character.

It is strongly recommended to add a selectable="false" in XMLmind XML Editor - Configuration and Deployment attribute to the element template. Doing this allows not to pollute the list of elements displayed the Edit tool with what is just a special purpose, private to the formatTextAs command, element template.

The element template must contain one or more text nodes referencing one of the following variables:

Variable	Description	Example
`{$line}`	The clipboard contains text lines separated by one or more newline characters. Open lines are ignored. This variable represents one such line.	The variable will be substituted 4 times: This is→line→#1. This is→line→#2. This is→line→#3. This is→line→#4.
`{$lineGroup}`	The clipboard contains groups of consecutive text lines separated by one or more open lines. This variable represents one such group of lines.	The variable will be substituted 2 times: This is→line→#1. This is→line→#2. This is→line→#3. This is→line→#4.
`{$lines}`	This variable represents the textual contents of the clipboard, as is. That is, whitespace is preserved.	The variable will be substituted 1 time: This is→line→#1. This is→line→#2. This is→line→#3. This is→line→#4.
`{$field}`	The clipboard contains text lines separated by one or more newline characters. Open lines are ignored. Each line contains one or more fields separated by tab characters. A field may be empty. That is, two consecutive tab characters may be used to specify an empty field. This variable represents one such field.	The variable will be substituted 12 times: This is line #1. This is ... line #4.

You cannot mix different variables. For example, the same template cannot reference both {$line} and {$field}.

The element which is the parent of the text node referencing the variable is replicated as many times the variable needs to be substituted.

All the elements containing variables are consumed in turn. If there are too many elements containing variables, the extra elements are discarded.

For example (XHTML example), if the element template is:

<elementTemplate name="PAA.ul" selectable="false">
  <ul xmlns="http://www.w3.org/1999/xhtml">
    <li>A) {$line}</li>
    <li>B) {$line}</li>
    <li>C) {$line}</li>
    <li>D) {$line}</li>
    <li>E) {$line}</li>
    <li>F) {$line}</li>
  </ul>
</elementTemplate>

the above clipboard contents may be used to generate:

<?xml version="1.0"?>
<ns:ul xmlns:ns="http://www.w3.org/1999/xhtml">
  <ns:li>A) This is line #1.</ns:li>
  <ns:li>B) This is line #2.</ns:li>
  <ns:li>C) This is line #3.</ns:li>
  <ns:li>D) This is line #4.</ns:li>
</ns:ul>

When the referenced variable is {$field},

the element which is the parent of the text node referencing the variable is replicated as many times as there are tab-separated fields in a given text line,
AND the element which the grand-parent of the text node referencing the variable is replicated as many times as there are text lines in the clipboard.

For example (XHTML example), if the element template is:

<elementTemplate name="PAA.table" selectable="false">
  <table xmlns="http://www.w3.org/1999/xhtml" border="1">
    <tr>
      <td>{$field}</td>
    </tr>
  </table>
</elementTemplate>

the above clipboard contents may be used to generate:

<?xml version="1.0"?>
<ns:table border="1" xmlns:ns="http://www.w3.org/1999/xhtml">
  <ns:tr>
    <ns:td>This is</ns:td>
    <ns:td>line</ns:td>
    <ns:td>#1.</ns:td>
  </ns:tr>
  <ns:tr>
    <ns:td>This is</ns:td>
    <ns:td>line</ns:td>
    <ns:td>#2.</ns:td>
  </ns:tr>
  <ns:tr>
    <ns:td>This is</ns:td>
    <ns:td>line</ns:td>
    <ns:td>#3.</ns:td>
  </ns:tr>
  <ns:tr>
    <ns:td>This is</ns:td>
    <ns:td>line</ns:td>
    <ns:td>#4.</ns:td>
  </ns:tr>
</ns:table>

In some cases you need to replicate an ancestor of the text node referencing the variable rather than its direct parent. In such case, explicitly add attribute cfg:replicate="true" to all the elements that are to be replicated.

For example (DocBook example), if the element template is:

<elementTemplate name="PAA.itemizedlist" selectable="false" 
  xmlns:cfg="http://www.xmlmind.com/xmleditor/schema/configuration">
  <itemizedlist xmlns="">
    <listitem cfg:replicate="true"><para>{$line}</para></listitem>
  </itemizedlist>
</elementTemplate>

the above clipboard contents may be used to generate:

<?xml version="1.0"?>
<itemizedlist>
  <listitem>
    <para>This is line #1.</para>
  </listitem>
  <listitem>
    <para>This is line #2.</para>
  </listitem>
  <listitem>
    <para>This is line #3.</para>
  </listitem>
  <listitem>
    <para>This is line #4.</para>
  </listitem>
</itemizedlist>


42. formatTextAs		42.2. Filtering the text pasted in the document