The campaign database tree contains the data from window controls and data sheets. The database exists as a tree format series
of nodes, represented by databasenode objects. Each node (except the root nodes) has a parent, and a number of child
nodes, as well as a name string. The database is preserved between sessions.
Each node has a type, with all the intermediate nodes having the "node" type, and the leaf nodes having a type based on the data
in the leaf node.
Creating window instances and controls bound to the database will automatically create corresponding nodes in the database.
Using the functions of this object, it is possible to also create new nodes and check for their existance explicitly.
Database node identifier strings
Many contexts in which node names are specified also accept database node identifier strings. These can
be used to refer to a node possibly outside the current level (i.e. on a level below individual entries in an entry in a
windowlist).
Depending on the context where the identifiers are used, they can be either absolute or relative. Absolute contexts look for
the specified node under the root of the database. The most common uses for absolute contexts are windowclass and
windowlist data sources. Relative contexts look for the node under the current data source (which is context dependent).
A common example of a relative context is the data source for a window control, which tries to find the named node under the
window data source.
Absolute contexts may have a data source under which a relative lookup could be performed. In such a case, a dot character
at the beginning of the identifier will cause a relative lookup instead. An example of this is the windowlist data
source. Identifiers in a relative context may also include the dot character, but it will be synonymous with the case without it.
Adding further dot characters after the first to the beginning of the identifier will cause a corresponding number of steps
upwards in the tree structure. Steps deeper into the tree can be specified by separating successive nodes with the dot character.
Module data
The data for each active module resides in its own data base tree. This allows more flexible data preparation for module design,
and guarantees that interlinking data inside modules and between modules works predictably.
Global level node listings (such as those found in ordinary windowlist listings) include module data from the
corresponding module trees as well, if such data is present. E.g. a windowlist that takes its data from the "images" node would
also receive all child nodes of any "image" nodes under all activated modules.
To access a particular node in the module data bases, a special identifier string syntax is used. Node identifier strings for
module data are formed by following the procedure above, prefixing the identifier with the at character '@' and following with the
complete name of the module.
Interface
addHolder
function addHolder(
username, owner
)
This function adds the specified user as a holder for this node and all child nodes. If the owner flag is set, the user will
also be able to modify the contents of data nodes. In such a case, any existing ownership is revoked.
Warning
This function will only return valid values if running as the session host. Using
User.isHost to confirm this
is recommended.
Parameters
username (string)
The username of the user gaining the status
owner (boolean)
If true, the user will also be flagged the owner of the node
createChild
function createChild(
[name], [type]
)
Create, or if it already exists fetch, the specified child node under the current node.
Parameters
name (string) [optional]
A relative node identifier specifying the child node to find. If this parameter is omitted,
a new unique node name will be generated.
type (string) [optional]
The type of node to create. If this parameter is omitted, an intermediate node will be created.
Leaf nodes can be of types "number", "string", "formattedtext", "image", "dice" or "windowreference".
Return values
(databasenode)
If the node already exists, the return value is a reference to that node. If it was created, a
reference to the created node is returned. If there was an error, returns nil.
delete
function delete(
)
Delete the database node, removing it from the database tree and deleting all child nodes. Any window instances using this
node as their data source will be closed.
getChild
function getChild(
name
)
Fetches the specified child node under the current node.
Parameters
name (string)
A relative node identifier specifying the child node to find
Return values
(databasenode)
A
databasenode object representing the node, or
nil if the node could
not be found
getChildCount
function getChildCount(
)
Get the number of child nodes belonging to this node.
Return values
(number)
The number of child nodes
getChildren
function getChildren(
)
Get all the child nodes of this node.
Return values
(table)
The child nodes are returned as
databasenode objects in a table with keys corresponding
to the names of the child nodes.
getHolders
function getHolders(
)
This function returns a list of all users registered as holders of this node. Holders will be notified of changes to the node
value. The holder list is automatically updated as a result of window sharing operations.
Warning
This function will only return valid values if running as the session host. Using
User.isHost to confirm this
is recommended.
Return values
(table)
Returns an integer indexed table containing the usernames of all registered holders for this node.
getModule
function getModule(
)
Retrieves the name of the module the data base node was loaded from.
Return values
(string)
Returns the name of the module the node was loaded from, or nil if the node was not loaded from a module
getName
function getName(
)
Get the name of this node.
Return values
(string)
Returns the string containing the node name
getNodeName
function getNodeName(
)
Get the dot separated complete node name, from the root node to the current node.
Return values
(string)
Returns the dot separated complete node name
getOwner
function getOwner(
)
This function returns the username of the client acting as the current owner of the node. The owner can alter the value of the
database node contents. Nodes that do not have an owner will return nil.
Warning
This function will only return valid values if running as the session host. Using
User.isHost to confirm this
is recommended.
Return values
(string)
Returns the username of the user owning the node, or nil if no owner is registered.
getParent
function getParent(
)
Fetches the parent of the current node.
Return values
(databasenode)
A
databasenode object representing the parent node, or
nil if the current
node is a root level node
getRulesetVersion
function getRulesetVersion(
)
Returns the release number of the ruleset used to save the data, as defined by the release attribute of the database definition root element.
The value is defined as a major and a minor version number.
Any database nodes not directly created as a result of a load operation will have the value of the current ruleset release.
Warning
Ruleset release numbers are not preserved between sessions. Any data saved by the application will contain the latest release number.
Return values
(number)
The major version number
(number)
The minor version number
getText
function getText(
)
Returns a textual representation of the value contained in the database node. If the node type is not string, number or formattedtext, then nil will be returned.
Return values
(string)
Returns the string value of the database node value.
getType
function getType(
)
Get the string identifying the type of this node. The possible values are "node" (representing an intermediate node),
"number", "string", "formattedtext", "image", "dice" and "windowreference".
Return values
(string)
The type string
getValue
function getValue(
)
Returns the value contained in the database node. The return value(s) vary depending on the type of the node.
Return values
(...)
Returns data contained in the database node
getVersion
function getVersion(
)
Returns the version number of the database where the data was loaded from, as defined by the database definition root.
The value is defined as a major and a minor version number.
Any database nodes not directly created as a result of a load operation will have the value of the current program version.
Warning
Version numbers are not preserved between sessions. Any data saved by the application will contain the latest version number.
Return values
(number)
The major version number
(number)
The minor version number
isIntact
function isIntact(
)
Database nodes loaded from modules are modifiable unless marked static. These modifications are local to a campaign, and the node may be reverted
back to its original state. This function may be used to check if such a node has any changes applied.
Return values
(boolean)
Returns true if the node has been modified, false if it is identical to the module contents
isOwner
function isOwner(
)
This function can be used to check if the current user is the owner of the database node, allowing the data in the node to be altered.
The host will be allowed to alter all values, and will always receive a return value of true.
Return values
(boolean)
Returns true if the user owns the node, or false otherwise.
isReadOnly
function isReadOnly(
)
Determines whether a database node can be edited. Reasons for database nodes to be non-editable include:
nodes marked as static, nodes from client or common modules, nodes not owned by client (host owns all nodes)
Return values
(boolean)
Returns true if the node is not editable, false otherwise
isStatic
function isStatic(
)
Database nodes may be flagged as static, disabling value editing completely. This flag is generally used for non-alterable
reference data loaded from rules modules. This function can be used to check if a node is part of the static content.
Return values
(boolean)
Returns true if the node is static, false otherwise
onChildAdded
handler
function onChildAdded(
source, child
)
A handler function that will be called when a new child node is added to this node.
Parameters
source (databasenode)
A
databasenode object reference identifying the node receiving a new child node
(databasenode)
A
databasenode object reference identifying the child node added
onChildUpdate
handler
function onChildUpdate(
source
)
A handler function that will be called when the child list changes or data in a child node is updated.
Parameters
source (databasenode)
A
databasenode object reference identifying the node causing the event
onDelete
handler
function onDelete(
source
)
A handler function that will be called when this node is deleted.
Parameters
source (databasenode)
A
databasenode object reference identifying the node causing the event
onIntegrityChange
handler
function onIntegrityChange(
source
)
A handler function that will be called when a node loaded from a module is either reverted back to its original state
or receives a user modification.
Parameters
source (databasenode)
A
databasenode object reference identifying the node causing the event
onObserverUpdate
handler
function onObserverUpdate(
source
)
A handler function that will be called when the observer list for the node is changed, either by removing or adding
users, or changing the node owner.
Parameters
source (databasenode)
A
databasenode object reference identifying the node causing the event
onUpdate
handler
function onUpdate(
source
)
A handler function that will be called when the data in this node is updated.
Parameters
source (databasenode)
A
databasenode object reference identifying the node causing the event
removeAllHolders
function removeAllHolders(
)
This function removes all users from the holder list for this node and all child nodes. The data is deleted from any
client instance and any windows having a deleted node as their data source will be closed.
Warning
This function will only work if running as the session host. Using
User.isHost to confirm this
is recommended.
removeHolder
function removeHolder(
username
)
This function removes the specified user from the holder list for this node and all child nodes. The data is deleted from the
client instance and any windows having a deleted node as their data source will be closed.
Warning
This function will only work if running as the session host. Using
User.isHost to confirm this
is recommended.
Parameters
username (string)
The username of the user losing the holder status
revert
function revert(
)
Return a node loaded from a module back to the state it was when loaded. If the target node was not loaded from a module, or if it does not have
any changes, this operation has no effect.
setStatic
function setStatic(
state
)
Sets the static flag of the database node. The values of static nodes are not modifiable.
Parameters
state (boolean)
A value of true to set the node static, or false to remove the static state.
setValue
function setValue(
value
)
Sets the data in the database node. The format of the parameter(s) depends on the type of the node.
Parameters
value (...)
Data placed in the database node
updateVersion
function updateVersion(
)
Sets the version number value of this node to the current version.
Using this function in conjunction with getVersion allows upgrading field values between different database versions
and marking the update completed.
