FEATURE: Table functions

[Jagged]

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:

Code: Select all

getTableNames()
getTableNames(delim)

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:

Code: Select all

[r:getTableNames()]
[r:getTableNames("<br>")]
[r:getTableNames("json")]

createTable() function
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)

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:

Code: Select all

[r:createTable("tableX",1,1)]
[r:createTable("tableY",1,1,getTableImage("tableZ"))]

deleteTable() function
Removed the specified table from the campaign. May only be used by GM or a trusted macro.
Usage:

Code: Select all

deleteTable(tableName)

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:

Code: Select all

addTableEntry(tableName,rangeStart,rangeEnd,result)
addTableEntry(tableName,rangeStart,rangeEnd,result,imageId)

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:

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","")]

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:

Code: Select all

deleteTableEntry(tableName,roll)

tableName specifies the table from which the row will be removed.
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","")]

[wolph42]

Woot! coolbeans, that would mean I can finally scratch the xls sheet I have for this.

Now the *only* thing this lacks is 'addTableColumn'... and I know, that would require an entire new table system. But still one keeps dreaming...

somehow that reminds me of this conversation

[Jagged]

getTableRoll() function
Returns the roll expression for the specified table. May only be used by GM or a trusted macro.
Usage:

Code: Select all

getTableRoll(tableName)

tableName specifies the table from which the roll expression will be returned.

setTableRoll() function
Returns the roll expression for the specified table. May only be used by GM or a trusted macro.
Usage:

Code: Select all

getTableRoll(tableName, roll)

tableName specifies the table from which the roll expression will be returned.
roll contains the new roll expression. If the value is "" the roll will be set to a default expression that should cover all table entries.
Examples:

Code: Select all

[r:setTableRoll("test","")]
[r:setTableRoll("test","1d6+1")]

clearTable() function
Removes all rows from the specified table. May only be used by GM or a trusted macro.
Usage:

Code: Select all

clearTable(tableName)

getTableVisible () function
Returns either 1 (true) or 0 (false) depending upon whether or not the table is visible to players.
Usage:

Code: Select all

getTableVisible (tableName)

setTableVisible() function
Sets whether or not the specified table is visible to players. May only be used by GM or a trusted macro.
Usage:

Code: Select all

setTableVisible(tableName, 0)

getTableAccess () function
Returns either 1 (true) or 0 (false) depending upon whether or not the table may be accessed by players.
Usage:

Code: Select all

getTableAccess(tableName)

setTableAccess() function
Sets whether or not the specified table may be accessed by players. May only be used by GM or a trusted macro.
Usage:

Code: Select all

setTableAccess(tableName, 0)

[Jagged]

Now the *only* thing this lacks is 'addTableColumn'... and I know, that would require an entire new table system. But still one keeps dreaming...

That will come

Although it will probably be a different system for compatibility reasons.

[aliasmask]

How do we know how many rows there are in a table? I suppose we can create our own index to keep track.

I'm guessing in your example to remove a row that if the value falls in to a ranges value that the range will be removed but all the values will remain. When adding a row I imagine it fills in the first empty range found and then overwrites the result and image. Is that correct?

Btw, this is epic for MT. Now we have access to essentially global variables. We can now store an image library without having to actually have tokens on a map somewhere.

[Full Bleed]

Thanks for this.


Can we get a sortTable() function? Some of my tables are quite out of sorts.

And a couple other suggestions:

getGMTableNames()
copyTable() or duplicateTable()

[Jagged]

copyTable() function
Creates a new table based upon an existing table. May only be used by GM or a trusted macro.
Usage:

Code: Select all

copyTable(oldTable, newTable)

oldTable specifies the table which will be copied.
newTable is the name of the new table.

setTableEntry() function
Sets the result for a specified roll value. Returns true (1) if update successful and false (0) if not. May only be used by GM or a trusted macro.
Usage:

Code: Select all

setTableEntry(tableName, roll, result)

tableName specifies the table to be updated.
roll is the value that specifies the row to be updated.
result is the new result for the specified row.

[wolph42]

Btw, this is epic for MT. Now we have access to essentially global variables. We can now store an image library without having to actually have tokens on a map somewhere.

nice thought!

this makes me wonder: would it also be possible to store an entire table structure as a property on a token (without the images, just the data?). Reason I ask, maptool is still easiest to work with with drag and drop and it would be great to have a token which you drop onto a map, run a macro and you have all your tables set up. Way less hassle and way more control than import export table!

[aliasmask]

yeah, the result table holds any data. Could be a single value or a complicated json. Any string really. You can put macro code in there if you wanted.

[Jagged]

I think token libraries or code libraries are definitely things we want to add. But we will do that through a dedicated db tool, rather than by extending the table function.

[Jagged]

I'm guessing in your example to remove a row that if the value falls in to a ranges value that the range will be removed but all the values will remain.

If you imaging the table UI, the "deleteTableEntry" command removes one row from the table. It finds the row that would be returned for the roll value, and then removes that row. It does not change the values for any other row. There is no data integrity here

Sorry I missed this question.

When adding a row I imagine it fills in the first empty range found and then overwrites the result and image. Is that correct?

This works exactly the same as the table UI. "addTableEntry" just adds a new row. There is no data integrity and there is nothing to stop you entering values that would cause potential errors when the table is used.

Just like the UI

[Full Bleed]

Since you've been knee-deep in the table code recently, I was wondering if it made sense to give MT some options for a table lookup path.

Right now, tables are always embedded in a campaign file. And that makes a lot of sense for core tables... but it might end up being a bit of a hurdle when trying to use tables for larger database type usage (i.e. an image/token repository for a bestiary).

Having a way to access tables outside the campaign file (in a local directory or something like dropbox) would be a way to keep core campaign files smaller while still allowing the creation and usage of some massive tables. The time it takes to save a campaign file (or auto backup), for example, is reflective of the size of a campaign file. So while it would be nice to be able to quickly deploy any monster from a massive bestiary table, increasing the size of the campaign file to accommodate that could have some significant downsides (i.e. more chance of corrupted campaign files, longer save/load times, etc.)

[Jagged]

I (and the other current developers) have been putting a lot of thought into these very issues

No designs decisions have yet been made. For example it may be easier to achieve the same kind of thing using better import/export tools. But we are definitely considering how best to handle external data. We are still at the very early stages of thought.

If we do come to any conclusions, we will post here before we commit to anything.

[celestian]

These are some very useful functions!

Question: does ROLL have to be a integer? Can it be a string?

[RPTroll]

Btw, this is epic for MT. Now we have access to essentially global variables. We can now store an image library without having to actually have tokens on a map somewhere.

That's brilliant.