Aliases

Aliases can be assigned during element creation and can also be changed for existing assignments. However, it is not necessary to perform subsequent structure walk-throughs by calling the aliased name (albeit possible).

Example: Create a type "TEST" having a property "NAME" with the aliased name "firstname". This will lead to an XPATH assignment of "TEST/FIRSTNAME" for the given property assignment.

new GroovyTypeBuilder().test {
    name(alias: "firstname")
}
                

The label can then be changed by employing

def builder = new GroovyTypeBuilder("TEST")
builder {
    name(label: new FxString("First name"))
}
                

Any derived assignments MUST consider the aliased name (or its XPath, respectively):

def builder = new GroovyTypeBuilder("TEST")
builder {
    lastname(assignment: "TEST/FIRSTNAME")
}
                

As mentioned above, an alias can also be changed for existing elements:

def builder = new GroovyTypeBuilder("TEST")
builder {
    name(alias: "name")
}
                

.. which would alter the XPath of the above property assignment to "TEST/NAME"

Aliased assignments from other types

A word of caution: Calling aliased assignments from other types will not work (this mainly has to do with the way the GTB has to "guess" where it is within a structure and what it is looking for & also due to the way that structure traversal works).

Example: A structure with an aliased assignment from "ROOT/CAPTION"

new GroovyTypeBuilder().test {
    caption(assignment: "ROOT/CAPTION", alias: "caption_alias")
}
                

Now we try to call the same structure again:

def builder = new GroovyTypeBuilder("TEST")
builder {
    caption()
}
                

This yields a NEW property within "TEST" by the name of "CAPTION"

Q: How can I go about changing an aliased assignmnent (from another type)?

A: Use the alias instead of the property's name! Example:

def builder = new GroovyTypeBuilder("TEST")
builder {
    caption_alias(label: new FxString("My derived caption"))
}
                

AutoUniquePropertyName / Alias Caveats

Due to the inherent "update-feature" of the GTB, it is of utmost importance to understand how the Builder handles the creation of properties having the SAME name within a given structure. This is best explained by the following examples.

def builder = new GroovyTypeBuilder().test {
    prop1()
    prop1()
}
                    

The above example will create "Prop1" having the default attribute values, the second call to prop1() will NEITHER create a new property (unique name: "PROP_1") NOR update the existing one.

def builder = new GroovyTypeBuilder().test {
    prop1()
    prop1(dataType: FxDataType.Text)
}
                        

In the above example, an attempt is made to create a second property with the autoUniquePropertyName "PROP1_1" This, however, will fail since the generated XPATH for the respective property assignment will be equal to the XPath of the original "PROP1" assignment (XPaths provide a UNIQUE way to address assignments, therefore no equal XPaths can exist within the same hierarchical level).

Hence the correct way to go about this is to use an alias (which will also set the XPath accordingly):

def builder = new GroovyTypeBuilder().test {
    prop1()
    prop1(dataType: FxDataType.Text, alias: "prop1alias")
}
                        

If, on the other hand, the new property (having the same name as an existing one) resides within a different hierarchical level of the given structure, the alias attribute (i.e. setting a different XPath) can be omitted:

def builder = new GroovyTypeBuilder().test {
    prop1()
    Group1 {
        prop1()
    }
}
                        

Assignment Paths

When creating assignments from properties / groups, either the full XPath or a relative XPath can be used to denote the base assignment. Where "relative" implies, that type names can be omitted.

Example 1: full XPath (capitalising the XPath is not necessary)

def builder = new GroovyTypeBuilder().test {
    prop1()
    Group1 {
        prop1(assignment: "TEST/PROP1")
    }
}
                        

Example 2: "relative" XPath

def builder = new GroovyTypeBuilder().test {
    prop1()
    Group1 {
        prop1(assignment: "/prop1")
    }
}
                        

The type's name is "PERSON", the label will be "Person Type"

first name property: name: firstname label: "First name"

last name property: name lastname label: "Last name"

middle name property: derived from first name

note property: text area, multiple languages

address group: contains "postcode", "streetname"

                            ... structureOptions: Eval.me("""[code goes here...]""")...