Documentation Center

An example- a lookup for inserting images

A step-by-step description of how to configure a lookup.

A lookup is a dialog where the author can pick a value from a list of items. A lookup dialog consists of any HTML page that is displayed in an iframe.

Lookups are used for retrieving values from external systems, such as URL's for included images. You must make sure that the selected value(s) is/are passed to Knowledge Center by calling the top.choose function from the html page. Lookups can be configured for any attribute or element, as long as it is specified as simpleType in the schema.

You'll often use a lookup for a required attribute since it will help you to be certain

  • to obtain required information from the user
  • that lookup dialogs will be triggered when appropriate.

Simplify matters for your users

In the example below, instead of using a lookup you could have left users to manually insert images. In the manual option, it is a multi-step process including these steps:

  1. Add a image (img) element
  2. Click on the element and open the Property Panel
  3. Find the lookup element or attribute, in this case the source (src)
  4. Type in the value for the image attribute in the Property Panel.

The lookup opens a dialog for ease of selection. This way you have more control and possibilities to configure the lookup behavior as desired, and thus providing a better user experience.

Configuring a lookup dialog for image insertion

This example instructs Knowledge Center to pop up a lookup when the author inserts an image:
<x:nodeConfig>
	<x:node match="img/@src">
		<x:lookup
			url="../lookup/images/index.html"
			forceLookup="false" autoOpen="true"/>
			...
	</x:node>
...
<x:nodeConfig>

The configuration example above offers two options for the behavior of Knowledge Center when an image is inserted into the document, by setting the following lookup attributes:

  • forceLookup prevents the value from being typed, and therefore forces the author to choose from the options your provide in the lookup dialog.
  • autoOpen means that the lookup will be opened automatically when the image is inserted; this works as long as the lookup target is a required element.
In this example, the lookup target is the src attribute, so you need to ensure this attribute is required in the XML Schema:
<xs:attribute name="src" use="required" type="xs:string"/>
Information about the lookup target can be accessed from the lookup HTML page using the top. dialogArguments object:
// The attribute node and value
var node = top.dialogArguments.node;
var value = top.dialogArguments.value;
Finally, and most importantly, the top.choose function is used to close the lookup and set the value. Multiple attributes can be set at the same time with top.choose. The following example sets three attributes on the current element, whereas the lookup was only opened for the src attribute:
top.choose({src: "image.jpg", width: 200, height: 100});