Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
840 lines (555 sloc) 35.4 KB

Field Definitions

Field definitions in JXT are the entries in the fields section of a definition:

registry.define({
    namespace: 'test',
    element: 'x',
    path: 'example',
    fields: {
        // Field definitions are here
    }
});

Each field can include an importer() and exporter() function, where the importer() function is responsible for converting an XML object into JSON, and exporter() is used to convert JSON to XML:

type FieldImporter = (xml: XMLElement, context: TranslationContext) => any;
type FieldExporter = (xml: XMLElement, data: any, context: TranslationContext) => void;

interface FieldDefinition {
    importer: FieldImporter;
    exporter: FieldExporter;
}

The importer() is given the source XML element, and is expected to return whatever value should be assigned to the field name.

The exporter() object is given the XML element that is being expanded, the current value of the field. The exporter() does not return anything, it is expected to modify the given XML element in-place.

The TranslationContext can be used to access information such as the languages to accept, the current key path, the JXT registry being used, etc.

Custom Field Definitions

In nearly all cases, you will use a function to create field definitions dynamically. Here is an example implementation of a field that gets/sets data from an attribute.

const attributeField = (attrName: string): FieldDefinition => ({
    importer(xml: XMLElement) {
        return xml.getAttribute(attrName);
    },
    exporter(xml: XMLElement, value: string) {
        xml.setAttribute(attrName, value);
    }
});

This attributeField() function can now be used in a JXT definition:

registry.define({
    namespace: 'test',
    element: 'x',
    path: 'example',
    fields: {
        attribute: attributeField('someAttrName')
    }
});

Provided Field Definition Types

JXT comes bundled with a variety of pre-defined field definitions. These definitions come in several flavors:

  • [type]Attribute()

    Map and cast an attribute value to the given type (boolean, integer, etc).

  • namespaced[Type]Attribute

    Same as [type]Attribute, but the attribute also uses an XML namespace.

  • child[Type]Attribute

    The same as [type]Attribute, but the attribute is on a child XML element.

  • child[Type]

    Map a value from a child XML element, and cast to the given type.

  • multipleChild[Type]

    Similar to child[Type], but maps an array of values.

  • childLanguage[Type]

    Similar to child[Type], but the child element that is used is based on the current language.

    The language used when exporting can be found in the lang property of the TranslationContext, and the set of languages to consider when importing can be found in the acceptLanguages property.

  • childAlternateLanguage[Type]

    Alternate language definitions use a dictionary mapping language codes to desired values. This definition kind should be used along side childLanguage[Type] to capture all available language-based values in addition to the "default" provided by childLanguage[Type].

Some of these definitions can accept a defaultValue parameter. When a default value is given, it is only applied when importing from XML to JSON. The default value will not be applied to any exported XML.


Attribute

attribute(name: string, defaultValue?: string, emitEmpty?: boolean)
Parameter Type Description
name string The name of the attribute
defaultValue string | undefined Default value to use if the attribute is not present, or is empty.
emitEmpty boolean | undefined In some cases, the attribute value "" instead of eliding the attribute is desired.

Returns: string

See examples


Boolean Attribute

booleanAttribute(name: string)
Parameter Type Description
name string The name of the attribute

Returns: boolean

See examples


Child Alternate Language RawElement

childAlternateLanguageRawElement(namespace: string | null, element: string, sanitizer?: string)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
element string The name of the child element
sanitizer string The name of a sanitizer function to remove any potentially harmful elements or attribute values (e.g. <script/> elements or javascript: URIs). Sanitizers SHOULD act as whitelists and only pass through approved elements.

Returns: Array<{ lang: string, value: JSONElement }>

NOTE: The named sanitizer MUST be present in the sanitizers property of the TranslationContext in order for any data to be returned.

A JSONElement value is defined as:

interface JSONElement {
    name: string;
    attributes: {
        [key: string]: string;
    };
    children: Array<JSONElement | string>;
}

This interface is slightly different than the XMLElement type used when importing and exporting. It purposefully does not include the parent property so that there are no circular references, making the imported data usable with JSON.stringify().

See examples


Child Alternate Language Text

childAlternateLanguageText(namespace: string | null, element: string)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
element string The name of the child element

Returns: Array<{ lang: string, value: string }>

See examples


Child Attribute

childAttribute(namespace: string | null, element: string, name: string, defaultValue?: string)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
element string The name of the child element
name string The name of the attribute
defaultValue string | undefined Default value to use if the attribute is empty or not present

Returns: string

See examples


Child Boolean

childBoolean(namespace: string | null, element: string)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
element string The name of the child element

Returns: boolean

See examples


Child Boolean Attribute

childBooleanAttribute(namespace: string | null, element: string, name: string)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
element string The name of the child element
name string The name of the attribute

Returns: boolean

See examples


Child Date

childDate(namespace: string | null, element: string, useCurrentDate: boolean = false)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
element string The name of the child element
useCurrentDate boolean | undefined If set to true, the current date will be used when importing if the child element does not contain a date value.

Returns: Date

NOTE: The date value in the XML MUST be parsable by the JavaScript Date constructor. The exported data value will be in ISO format.

See examples


Child Date Attribute

childDateAttribute(namespace: string | null, element: string, name: string, useCurrentDate: boolean = false)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
element string The name of the child element
name string The name of the attribute
useCurrentDate boolean | undefined If set to true, the current date will be used when importing if the child element does not contain a date value.

Returns: Date

NOTE: The child element's text value MUST be parsable by the JavaScript Date constructor. The exported data value will always be in ISO format.

See examples


Child Enum

childEnum(namespace: string | null, elements: Array<string | [string, string]>, defaultValue?: string)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
elements `Array<string [string, string]>`
defaultValue string | undefined Default value to use if there are no child elements whose name is in elements

Returns: string

See examples


Child Float

childFloat(namespace: string | null, element: string, defaultValue?: number)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
element string The name of the child element
defaultValue number | undefined Default value to use if the attribute is empty or not present

Returns: number

See examples


Child Float Attribute

childFloatAttribute(namespace: string | null, element: string, name: string, defaultValue?: number)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
element string The name of the child element
name string The name of the attribute
defaultValue number | undefined Default value to use if the attribute is empty or not present

Returns: number

See examples


Child Integer

childInteger(namespace: string | null, element: string, defaultValue?: number)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
element string The name of the child element
defaultValue number | undefined Default value to use if the attribute is empty or not present

Returns: number

NOTE: When importing, the child element text is parsed using parseInt() with a radix of 10.

See examples


Child Integer Attribute

childIntegerAttribute(namespace: string | null, element: string, name: string, defaultValue?: number)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
element string The name of the child element
name string The name of the attribute
defaultValue number | undefined Default value to use if the attribute is empty or not present

Returns: number

NOTE: When importing, the child attribute text is parsed using parseInt() with a radix of 10.

See examples


Child JSON

childJSON(namespace: string | null, element: string)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
element string The name of the child element

Returns: any

The JSON object assigned to the field will be serialized and set as the child element's text content.

See examples


Child Language Attribute

childLanguageAttribute(namespace: string | null, element: string)

Returns: string

This definition is specifically for getting or setting the value of the xml:lang attribute of a child element.

If no xml:lang attribute is present on the child element when importing, it will search up the XML tree until an xml:lang is found. If none is found, the lang value provided in the TranslationContext will be used.

The current language when exporting data is normally controlled by defining a field named lang whose field type is languageAttribute(). You can assign the field type childLanguageAttribute() to the lang field instead if you wish to change the current language based on the child element's language:

registry.define({
    namespace: 'test',
    name: 'alt-lang-location',
    fields: {
        lang: childLanguageAttribute(null, 'child-with-lang')
    }
});

In most cases, you will want to use the field name lang so that the current language in the TranslationContext is correctly set during export. However, if you need to use a different field name, set the languageField property when creating the JXT definition to the alternate field name:

registry.define({
    namespace: 'test',
    name: 'alt-lang-location',
    languageField: 'theLanguageToUse',
    fields: {
        theLanguageToUse: childlanguageAttribute(null, 'child-with-lang')
    }
});

See examples


Child Language RawElement

childLanguageRawElement(namespace: string | null, element: string, sanitizer?: string)

See examples


Child RawElement

childRawElement(namespace: string | null, element: string, sanitizer?: string)

See examples


Child Text

childText(namespace: string | null, element: string, defaultValue?: string)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
element string The name of the child element
defaultValue string The default value to use when there is no text content for the element

Returns: string

If there are multiple child elements with the given name, the following will be checked:

  1. If the acceptLanguages property of the TranslationContext is set, the first child element whose language value appears earliest in the list will be used.
  2. If there is no acceptLanguages set, or no child elements have a language matching acceptLanguages, the first child whose language matches the current language in the context (lang in TranslationContext) will be used.
  3. If no child has a matching language, the first child will be used.
  4. If there are no children, the default value will be used.

NOTE: It is advisable to also use childAlternateLanguageText() to capture all available language data.

See examples


Child Text Buffer

childTextBuffer(namespace: string | null, element: string, encoding: string = 'utf8')
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
element string The name of the child element
encoding string The encoding to use for the buffer

Returns: Buffer

See examples


Child Timezone Offset

childTimezoneOffset(namespace: string | null, element: string)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
element string The name of the child element

Returns: number

The timezone offset is the provided as the number of minutes (positive or negative) from UTC.

The child element text MUST be formatted as +HH:MM or -HH:MM.

See examples


Date Attribute

dateAttribute(name: string, useCurrentDate: boolean = false)
Parameter Type Description
name string The name of the attribute
useCurrentDate boolean | undefined If set to true, the current date will be used when importing if the child element does not contain a date value.

Returns: Date

NOTE: The date value in the XML MUST be parsable by the JavaScript Date constructor. The exported data value will be in ISO format.

See examples


Float Attribute

floatAttribute(name: string, defaultValue?: number)
Parameter Type Description
name string The name of the attribute
defaultValue number | undefined Default value to use if the attribute is empty or not present

Returns: number

See examples


Integer Attribute

integerAttribute(name: string, defaultValue?: number)
Parameter Type Description
name string The name of the attribute
defaultValue number | undefined Default value to use if the attribute is empty or not present

Returns: number

NOTE: When importing, the attribute text is parsed using parseInt() with a radix of 10.

See examples


Language Attribute

languageAttribute();

Returns: string

This definition is specifically for getting or setting the value of the xml:lang attribute.

If no xml:lang attribute is present when importing, it will search up the XML tree until an xml:lang is found. If none is found, the lang value provided in the TranslationContext will be used.

In most cases, you will want to use the field name lang with this definition type so that the current language in the TranslationContext is correctly set during export.

However, if you need to use a different field name for language, set the languageField property when creating the JXT definition to the alternate field name:

registry.define({
    namespace: 'test',
    name: 'alt-lang-location',
    languageField: 'theLanguageToUse',
    fields: {
        theLanguageToUse: languageAttribute()
    }
});

See examples


Multiple Child Alternate Language Text

multipleChildAlternateLanguageText(namespace: string | null, element: string)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
element string The name of the child element

Returns: Array<{ lang: string, value: string[]}>

See examples


Multiple Child Attribute

multipleChildAttribute(namespace: string | null, element: string, name: string)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
element string The name of the child element
name string The name of the attribute

Returns: string[]

See examples


Multiple Child Enum

multipleChildEnum(namespace: string | null, elements: Array<string>)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
elements `Array<string [string, string]>`

Returns: string[]

See examples


Multiple Child Text

multipleChildText(namespace: string | null, element: string)
Parameter Type Description
namespace string | null The namespace of the child element. If null, the parent namespace will be used.
element string The name of the child element

Returns: string[]

If there are multiple child elements with the given name, but different languages, the following will be checked:

  1. If the acceptLanguages property of the TranslationContext is set, the children whose language value appears earliest in the list will be used.
  2. If there is no acceptLanguages set, or no child elements have a language matching acceptLanguages, the children whose language matches the current language in the context (lang in TranslationContext) will be used.
  3. Otherwise, an empty list is returned.

NOTE: It is advisable to also use multipleChildAlternateLanguageText() to capture all available language data.

See examples


Namespaced Attribute

namespacedAttribute(prefix: string, namespace: string, name: string, defaultValue?: string)
Parameter Type Description
prefix string The namespace prefix to use if the namespace has not already been declared
namespace string The namespace of the attribute
name string The name of the attribute
defaultValue string The default value to use when there is no text content for the element

Returns: string

See examples


Namespaced Boolean Attribute

namespacedBooleanAttribute(prefix: string, namespace: string, name: string)
Parameter Type Description
prefix string The namespace prefix to use if the namespace has not already been declared
namespace string The namespace of the attribute
name string The name of the attribute

Returns: boolean

See examples


Namespaced Date Attribute

namespacedDateAttribute(prefix: string, namespace: string, name: string, useCurrentDate: boolean = false)
Parameter Type Description
prefix string The namespace prefix to use if the namespace has not already been declared
namespace string The namespace of the attribute
name string The name of the attribute
useCurrentDate boolean The default value to use when there is no text content for the element

Returns: Date

NOTE: The date value in the XML MUST be parsable by the JavaScript Date constructor. The exported data value will be in ISO format.

See examples


Namespaced Float Attribute

namespacedFloatAttribute(prefix: string, namespace: string, name: string, defaultValue?: number)
Parameter Type Description
prefix string The namespace prefix to use if the namespace has not already been declared
namespace string The namespace of the attribute
name string The name of the attribute
defaultValue number The default value to use when there is no text content for the element

Returns: number

See examples


Namespaced Integer Attribute

namespacedIntegerAttribute(prefix: string, namespace: string, name: string, defaultValue?: number)
Parameter Type Description
prefix string The namespace prefix to use if the namespace has not already been declared
namespace string The namespace of the attribute
name string The name of the attribute
defaultValue number The default value to use when there is no text content for the element

Returns: number

NOTE: When importing, the child element text is parsed using parseInt() with a radix of 10.

See examples


Splice Path

splicePath(namespace: string | null, element: string, path: string, multiple?: boolean)

See examples


Static Value

staticValue(value: any)
Parameter Type Description
value any The value to always return

Returns: string

The staticValue() type is used to inject a value into the imported data, but has no effect when exporting.

See examples


Text

text(defaultValue?: string)
Parameter Type Description
defaultValue string The default value to use when there is no text content for the element

Returns: string

See examples


Text Buffer

textBuffer(encoding: string = 'utf8')
Parameter Type Description
encoding string The encoding to use for the buffer

Returns: Buffer

See examples

You can’t perform that action at this time.