Standard String Representations of Object Values

The NSXML classes provide canonical string representations for a standard set of atomic data types, each of which is represented by a Foundation object as an object value. For example, if you store an NSCalendarDate as a node’s object value and then send stringValue to that node, you get back something like this:

2004-06-23T14:31:04

The canonical string representations for simple and derived types are defined in the W3C XML Schema Data Types specification (http://www.w3.org/TR/xmlschema-2/). Table 1 lists the more important types, along with their associated Foundation class and canonical string representation.

These string representations follow the XML Schema canonical form as a result of a design choice, not because the NSXML classes look at the xsi:type attribute or pick an output format based on an element’s associated type in the validating schema.

Custom String Representations of Object Values

The NSXML classes implement their string representations for the standard W3C types through value transformers—that is, instances of custom subclasses of NSValueTransformer. You can easily create and register value transformers for your own custom objects. You can even override the implementations of the standard value transformers implemented by the NSXML classes.

When requested to render an object value as a string, the NSXML classes scan the global registry of value transformers looking for transformer names in the following format:

• NSXML + Class Name + TransformerName

For example, if your class was named “MyCustomClass”, the proper transformer name would be “NSXMLMyCustomClassTransformerName”. The NSXML classes extract the class name from the transformer name and use it to identify the object value to transform.

For complete details on creating a custom value transformer, see Value Transformer Programming Guide. In summary, you must override the NSValueTransformer class methods transformedValueClass and allowsReverseTransformation and the instance method transformedValue. Listing 1 shows an example of such a transformation for a custom object with a name and a date instance variable.

Listing 1  Implementing a value transformer for an object value

@implementation NSXMLNameDateTransformer

+ (Class)transformedValueClass {

    return [NameDate class];

}

// transformation is oneway

+ (BOOL)allowsReverseTransformation {

    return NO;

}

- (id)transformedValue:(id)value {

    if ( [value isKindOfClass:[NameDate class]] ) {

        NSString *dateStr = [[value date]

            descriptionWithCalendarFormat:@"%Y-%m-%dT%H:%M:%S"];

        NSString *retVal = [NSString stringWithFormat:@"Name: %@ - Date: %@",

            [value name], dateStr];

        return retVal;

    }

    return @"";

}

@end

Your application should register the custom value transformer with the NSValueTransformer class as soon as possible. A good place for registration is in an override of the initialize class method. To register the value transformer, send a setValueTransformer:forName: message to the NSValueTransformer class. Make sure that the transformer name conforms to the requirement for NSXML value transformers. See Listing 2 for an example.

Listing 2  Registering the value transformer

#import “NSXMLNameDateTransformer.h”

+ (void)initialize {

    NSValueTransformer *myTransformer = [[[NSXMLNameDateTransformer alloc]

        init] autorelease];

    [NSValueTransformer setValueTransformer:myTransformer

        forName:@"NSXMLNameDateTransformerName"];

}