FEATURE: Table functions
Posted: Thu Apr 21, 2016 7:45 am
As a group we have been talking about including some database functionality into Maptool and as a precursor to that, we realised that from the point of view of the macro scripting language, table functionality was woefully inadequate. So the following functions will be coming soon to a Maptool near you!
getTableNames() function
Returns a list containing the names of the tables in the campaign. The type of the value returned depends on the delimiter parameter. The function can be used by players or from a non-trusted macro, but it will only return player-visible tables. When used by a GM or a trusted macro it returns all tables.
Usage:
If the delimiter is not specified then a string list is returned with the default value of "," is used.
If the delimiter json then a JSON Array is returned.
Otherwise a string list is returned with the delimiter passed in.
Examples:
createTable() function
Creates an empty table, specifying its access levels and optional image. May only be used by GM or a trusted macro.
Usage:
TableName is the identifier for the table.
Visible specifies whether or not the table can be seen by players in the Table Window. Values may be either 1 (true) or 0 (false).
Accessible specifies whether or not the table can be used by players to lookup values. Values may be either 1 (true) or 0 (false).
ImageId is optional and is the asset id of an image that will be used for the table in the Table Window. If an invalid or missing asset id is used, the table will display a red "X".
Examples:
deleteTable() function
Removed the specified table from the campaign. May only be used by GM or a trusted macro.
Usage:
tableName specifies the table to be deleted.
addTableEntry() function
Adds a new row to the specified table. May only be used by GM or a trusted macro.
Note: adding a row to a table will not automatically change the table row value, so this should be updated to avoid possible errors.
Usage:
tableName specifies the table to which the row will be added.
rangeStart is the lowest integer value that will return the row when the table is accessed by a "table" function call.
rangeEnd is the highest integer value that will return the row when the table is accessed by a "table" function call.
result is the value to be returned by a "table" function call.
ImageId is optional and is the asset id of an image that will be returned by a "tableImage" function call.
Examples:
deleteTableEntry() function
Removes a row from the specified table. May only be used by GM or a trusted macro.
Note: deleting a row from a table will not automatically change the table row value, so this should be updated to avoid possible errors.
Usage:
tableName specifies the table from which the row will be removed.
roll is the value that specifies the row to be removed.
Examples:
getTableNames() function
Returns a list containing the names of the tables in the campaign. The type of the value returned depends on the delimiter parameter. The function can be used by players or from a non-trusted macro, but it will only return player-visible tables. When used by a GM or a trusted macro it returns all tables.
Usage:
Code: Select all
getTableNames()
getTableNames(delim)
If the delimiter json then a JSON Array is returned.
Otherwise a string list is returned with the delimiter passed in.
Examples:
Code: Select all
[r:getTableNames()]
[r:getTableNames("<br>")]
[r:getTableNames("json")]
Creates an empty table, specifying its access levels and optional image. May only be used by GM or a trusted macro.
Usage:
Code: Select all
createTable(tableName, visible, accessible)
createTable(tableName, visible, accessible, imageId)
Visible specifies whether or not the table can be seen by players in the Table Window. Values may be either 1 (true) or 0 (false).
Accessible specifies whether or not the table can be used by players to lookup values. Values may be either 1 (true) or 0 (false).
ImageId is optional and is the asset id of an image that will be used for the table in the Table Window. If an invalid or missing asset id is used, the table will display a red "X".
Examples:
Code: Select all
[r:createTable("tableX",1,1)]
[r:createTable("tableY",1,1,getTableImage("tableZ"))]
Removed the specified table from the campaign. May only be used by GM or a trusted macro.
Usage:
Code: Select all
deleteTable(tableName)
addTableEntry() function
Adds a new row to the specified table. May only be used by GM or a trusted macro.
Note: adding a row to a table will not automatically change the table row value, so this should be updated to avoid possible errors.
Usage:
Code: Select all
addTableEntry(tableName,rangeStart,rangeEnd,result)
addTableEntry(tableName,rangeStart,rangeEnd,result,imageId)
rangeStart is the lowest integer value that will return the row when the table is accessed by a "table" function call.
rangeEnd is the highest integer value that will return the row when the table is accessed by a "table" function call.
result is the value to be returned by a "table" function call.
ImageId is optional and is the asset id of an image that will be returned by a "tableImage" function call.
Examples:
Code: Select all
[r:addTableEntry("test",1,3,"bert")]
[r:addTableEntry("test",4,4,"fred")]
[r:addTableEntry("test",5,5,"alf", getTokenImage())]
[r:setTableRoll("test","")]
Removes a row from the specified table. May only be used by GM or a trusted macro.
Note: deleting a row from a table will not automatically change the table row value, so this should be updated to avoid possible errors.
Usage:
Code: Select all
deleteTableEntry(tableName,roll)
roll is the value that specifies the row to be removed.
Examples:
Code: Select all
[r:addTableEntry("test",1,3,"bert")]
[r:deleteTableEntry("test",2)]
[r:setTableRoll("test","")]