Attribute names are case-sensitive. Unlike previous versions, User [sic] attributes can be renamed and re-data-typed after creation. System attributes can not be renamed or have their data type changed. A rename might be to use a completely different term, e.g. $Cost renamed to $Price, or it might be a change of case, $cost to $Cost.
Simply select the attribute in the Document Inspector's User tab, select the name, enter a new value and press Return. Attribute listings and Displayed Attributes entries will update. However, any explicit references to the old name in action or export code, templates, boilerplate code, etc., will be unaffected. Such references must be manually edited to reflect the change but do not overlook agents as a help to find such references for correction. Places where you may need to manually change attribute names:
- Action-type system attributes.
- Action code in code notes.
- Stamps.
- Export templates, e.g. in or value()calls.
Changing attribute name or data type & existing values
Do not assume renaming an attribute will retain the values used under the old name. Although values may persist in some cases, do not rename attribute based on that premise. If the attribute you wish to rename already has values in some notes, do not rename but rather make a new attribute, transfer the values and then delete the old attribute. For example, an existing Number-type user attribute $Price needs to be renamed to $TotalPrice but $Price already has values. The process advised is as follows (it only looks long as it is given in a lot of detail) it is actually very quick to do:
- Work on a copy of the data: make a copy of the TBX before starting this process
- Make a new Number-type user attribute 'TotalPrice'
- Disable any rules/agents that might be alter values of $Price while making this attribute change.
- Create an agent with the query
hasLocalValue("Price"). This will match all notes that have a (local, not inherited) value set for the existing Price attribute. If you have a prototype that sets a value inherited b other notes, only the prototype will match as well as notes that have a value set deliberately in that note. - Check the agent matches to sort of notes expected: this is good to do before diving straight in to copying any values. If all looks good…
- Set an agent action
$TotalPrice = $Price. For each matched note—and only matched notes—the value of the $TotalPrice attribute is set to the notes existing $Price value. - At this point both attributes in matching notes have a value, and the same one. This is another opportunity to check things look good if trying this for the first time (Outline column view can help). Assuming all looks good…
- Delete the agent. Do not forget this step!
- Open the Document Inspector's User tab, and select the 'Price' attribute. Using the gear-wheel button (at right) from the pop-up choose the 'Delete user attribute' option. The 'Price' attribute is deleted along with any data.
- Other tidy-up issues:
- KeyAttributes. If $Price was used as a Displayed Attribute you will need to use an agent to find and remove the old name and add the new one.
- Action code. Review code in Stamps and any Action-type attributes (e.g. $Rule, $AgentAction, etc.) to find and remove the old name and add the new one.
Changing data type
If changing the data type of an attribute, consider coercion effects:
- To Boolean. No value: false. All other values: true.
- String-based to Number. Strings of number characters: numbers. All other strings: no value.
- Number to string-based. Numbers become literal strings.
- To/from Date. Date to String will likely give the date in string form as would be shown in Displayed Attributes in the current TBX. Other type conversions may have variable effects, e.g. Date to Number which is not a sensible change, anyway.
- List/Set to String. A semi-colon concatenated string of list values.
- String to List/Set. The current string will split to list values at any semi-colons in the original value.
- To/From Interval. Not documented.
Bear in mind that Colour, URL and File types are essentially String type with a special form of handling