This is a continuation of a previous blog post about best practices for improving the XML editing experience in Xopus. If you haven't read that, please do that as well to get an overview of what other methods can be used, next to the topic of this blogpost: placeholders.

The primary use case of placeholders is to give the author more information about the content that is expected in this element. This will show for example the element name in grey text, and allows the user to click on that text and start entering content. This encourages the author to replace the placeholder text with real data.

How to use placeholders

First of all, you need to decide which elements ought to have placeholders. This depends on the element. For the most common elements you won't need to use a placeholder, since the styling is enough to make it clear to the author what content is expected. For most other elements a placeholder will be beneficial. For example lists, whether ordered or unordered, do not benefit much from a placeholder, while a table caption will greatly benefit from a placeholder.

On the other hand, some elements need more explanation than you can provide with placeholders alone. As the placeholder text will disappear when the author writes text into the element, the value of the placeholder is gone for elements that have content already. So for elements that really need a descriptive text on what kind of value is expected there, you can consider to treat the document as if it is a form, and add a label next to the element using the XSLT stylesheet (as discussed in the previous blogpost). This will make sure that even after filling in the data, it is clear what that part of the document is about.

Once you have decided that you want to use placeholders, and for which elements you want to use placeholders, you can start to configure Xopus to show these at the correct places. For this, you need to reference the elements you want to see placeholders for in the nodeConfig.

In the example below you can see how to configure all placeholders at once. The {name} will make sure that the placeholder will display the name of the element as configured elsewhere in your nodeConfig. If you have configured translated names for your elements, this will use the element name that matches the chosen UI language.

<x:nodeConfig>
...
<x:node match="title">
<x:name xml:lang="en">Title</x:name>
<x:name xml:lang="fr">Titre</x:name>
</x:node>
<x:node match="title | footer | caption | td | th">
<x:placeholder>{name}</x:placeholder>
</x:node>
...
</x:nodeConfig>

The example below shows how to define a placeholder for one particular element. By specifying different placeholders for different languages this way, you can show a placeholder specific to the document language. This is different from the approach above, where the name shown in the placeholder will change with the chosen UI language instead.

<x:nodeConfig>
...
<x:node match="title">
<x:placeholder xml:lang="en">Type your title here</x:placeholder>
<x:placeholder xml:lang="fr">Écrivez votre titre ici</x:placeholder>
</x:node>
...
</x:nodeConfig>

Some of our customers use Xopus together with other XML editing tools like XMetal. In XMetal placeholders are configured in a different way, by placing a processing instruction in the document itself. To support these cases, this is also possible in Xopus since Xopus 5.3. See our documentation for more information about this.

<title><?xm-replace_text Write your title here?></title>

Element placeholders

The placeholders discussed above are used for elements that are already in the document. Perhaps these are in the document because you have specified them in a template. Or the user has just inserted the element, but has not yet typed content in it. The main concept is that there is an empty element, and the placeholders are there to help entering content. The same concept of placeholders can however also be extended to elements that are not yet in the document.

This can help authors with inserting optional elements, especially in cases where the order of the elements is dictated by the XML schema. Instead of having to dig through the menu to insert elements, they can just click in a placeholder, and it is inserted automatically. An example for this would be an image with an optional caption. You can output a caption placeholder when no caption element exists, and with some javascript you can add the element automatically when it is clicked.

You can see this principle in action on the following XopusFiddle: http://xopusfiddle.net/PqWY/. There is no empty caption element in the document, but you can see a placeholder below the image. Click on it and the element is inserted and a real placeholder is shown.

To make this work, we first need to define a regular placeholder for this element (Xopus Config line 179).

<x:placeholder>Caption</x:placeholder>

Then in the XSL, we can output some html in the case the element does not exist (XSL line 410).

<xsl:if test="count(legend) = 0"><span class="legend xopus-placeholder" onclick="addLegend(node);">Caption</span></xsl:if>

And finally in the XSLT we refer to a javascript method, so we need to define that as well, to tell Xopus what to do when the placeholder is clicked (Javascript lines 6-14).

function addLegend(node) {
var legend = node.getOwnerDocument().createElement("legend");
node.appendChild(legend);
node.makeValid();
var sel = Editor.Selection.getRange();
sel.selectNodeContents(legend);
sel.collapse(true);
Editor.Selection.setRange(sel);
}

Conclusion

To conclude the topic of placeholders, the main takeaway is that you need to go through all elements in your XML Schema and think about what kind of mechanism will improve the authoring experience for those elements. The most common elements most likely do not need placeholders. Lesser known elements can greatly benefit from placeholders, although some of those may need additional methods for improving the UX like labels as well. Finally, consider placeholders for optional elements in a sequence, to make it easier to discover what kind of content is expected in the document as well.

You can find more information about placeholders in our documentation about this subject.
And as always, if you need help with implementing things like this, please ask for assistance on the forum, we are happy to help out.

Anonymous