Role Playing with Adaptation

Table of Contents Adaptation in General Using DOM Adapters in an Editor Adaptation in SimpleDOMEditor Topics in this section

Adaptation in General

Adaptation is one of the most useful techniques in all of ATF and it abounds there.

In particular, DOM adapters employ adaptation to allow a single DomNode to take on many roles. This is what a DOM adapter does: a DomNode can be adapted to any DOM adapter defined for the DomNode's type. The DOM adapter class provides the methods and properties useful to handle the object in that role. It is especially useful to define DOM adapters on the type of the root DomNode so it can be adapted to many different types.

The main adaptation methods provided in the Adapters class are:

• As<T>(): adapt an object to the given type, returning null if no adapter found.
• Cast<T>(): adapt an object to the given type, raising an exception if no adapter found.
• Is<T>(): test if an adapter is available for an object for the given type.

For more information about adaptation in general, see Adaptation in ATF. For information about DOM adapters, see DOM Adapters in the DOM in a Nutshell section.

Using DOM Adapters in an Editor

To use a DOM adapter in an editor or any other ATF application, do the following:

• Define DOM adapters for types, usually in the type schema loader. For details on doing this, see Defining DOM Adapters for Types.
• Design DOM adapter classes for the types, deriving from DomNodeAdapter. These can be very basic, simply containing a few properties, or quite comprehensive. For a description of various things DOM adapters can do, see:
  • DOM Adapters Adapt: general capabilities of DOM adapters.
  • Wrapping Attributes and Elements in Properties: access attributes through C# properties.
  • DOM Adapters Listen: listen for events on DomNodes.
  • DOM Adapters Validate: validate the data in a DomNode.

Adaptation in SimpleDOMEditor

If you look for all the occurrences of the adaptation methods in the ATF Simple DOM Editor Sample, you find that all of them are used with DOM adapters! Consider the IDocumentClient.Show() method in the Editor class:

public void Show(IDocument document)
{
    EventSequenceContext context = Adapters.As<EventSequenceContext>(document);
    m_controlHostService.Show(context.ListView);
}

The document parameter implements IDocument. In SimpleDOMEditor, the IDocument implementer is EventSequenceDocument:

public class EventSequenceDocument : DomDocument, ISearchableContext

As noted in IDocument Interface Implementation, DomDocument implements IDocument. Because the EventSequenceDocument class derives from DomDocument, the IDocument document parameter refers to an EventSequenceDocument instance.

Show() is attempting to adapt this IDocument to the EventSequenceContext DOM adapter. Here is a partial list of DOM adapters defined for types in SimpleDOMEditor (see Define DOM Extensions for the entire list):

Schema.eventSequenceType.Type.Define(new ExtensionInfo<EventSequenceDocument>());
Schema.eventSequenceType.Type.Define(new ExtensionInfo<EventSequenceContext>());

So both the DOM adapters EventSequenceDocument and EventSequenceContext are defined on the type "eventSequenceType". A DomNode can always be adapted to all DOM adapters defined for its type. For an explanation of why this is so, see Adapting to All Available Interfaces in Adaptation in ATF. In particular, this means that an EventSequenceDocument instance can be adapted to EventSequenceContext, just as Show() does.

Other uses of As<T>(), Cast<T>(), and Is<T>() in SimpleDOMEditor employ similar adaptations. These adaptations make it easier to access all the different kind of objects you need to implement an editor.

In summary, DOM adapters make it easier to implement the interfaces you need in an editor.

Topics in this section