K-Scaffold

Appearance

Utilities ​

These are utility functions that are not directly related to Roll20 systems. They provide easy methods for everything from processing text and numbers to querying the user for input.

k.capitalize

function

Capitalize each word in a string

  • string - string -

    The string to capitalize

  • Returns: stringundefined

Example

js
const capitalized = k.capitalize('a word');
console.log(capitalized);// => "A Word"
const capitalized = k.capitalize('a word');
console.log(capitalized);// => "A Word"

k.commaArray

function

Splits a comma delimited string into an array

  • string - string -

    The string to split.

  • Returns: array- The string segments of the comma delimited list.

k.debug

function

Alias for console.log that only triggers when debug mode is enabled or when the sheet's version is 0. Useful for entering test logs that will not pollute the console on the live sheet.

  • msg - any -

    'See k.log

  • force - boolean -

    Pass as a truthy value to force the debug output to be output to the console regardless of debug mode.

  • Returns: voidundefined

k.escape

function

Encodes data in Base64. This is useful for passing roll information to action buttons called from roll buttons.

  • data - string|object|Array.<any> -

    The data that you want to Base64 encode

  • Returns: string- The encoded data

k.extractQueryResult

function

Extracts a roll query result for use in later functions. Must be awaited as per startRoll documentation. Stolen from Oosh's Adventures with Startroll thread.

  • query - string -

    The query should be just the text as the ?{ and } at the start/end of the query are added by the function.

  • Returns: Promise- Resolves to the selected value from the roll query

Example

js
const rollFunction = async function(){
 //Get the result of a choose from list query
 const queryResult = await extractQueryResult('Prompt Text Here|Option 1|Option 2');
 console.log(queryResult);//=> "Option 1" or "Option 2" depending on what the user selects

 //Get free form input from the user
 const freeResult = await extractQueryResult('Prompt Text Here');
 consoel.log(freeResult);// => Whatever the user entered
}
const rollFunction = async function(){
 //Get the result of a choose from list query
 const queryResult = await extractQueryResult('Prompt Text Here|Option 1|Option 2');
 console.log(queryResult);//=> "Option 1" or "Option 2" depending on what the user selects

 //Get free form input from the user
 const freeResult = await extractQueryResult('Prompt Text Here');
 consoel.log(freeResult);// => Whatever the user entered
}

k.log

function

An alias for console.log.

  • msg - any -

    The message can be a straight string, an object, or an array. If it is an object or array, the object will be broken down so that each key is used as a label to output followed by the value of that key. If the value of the key is an object or array, it will be output via console.table.

k.orderSection

function

Orders a single ID array.

  • repOrder - Array.<string> -

    Array of IDs in the order they are in on the sheet.

  • IDs - Array.<string> -

    Array of IDs to be ordered. Aka the default ID Array passed to the getSectionIDs callback

  • attributes - AttributesProxy -

    The Kscaffold attributes object

  • section - string -

    the name of the section being ordered. If section and attributes are passed, will return an ordered array that does not include IDs for rows that do not exist.

  • casc - object -

    the object describing the default state of the sheet.

  • Returns: Array.<string>- The ordered id array

k.orderSections

function

Orders the section id arrays for all sections in the sections object to match the repOrder attribute.

  • attributes - attributesProxy -

    The attributes object that must have a value for the reporder for each section.

  • sections - Array.<object> -

    Object containing the IDs for the repeating sections, indexed by repeating section name.

k.parseHTMLName

function

Parses out the attribute name from the htmlattribute name.

  • string - string -

    The triggerName property of the event.

  • Returns: stringundefined

Example

js
//Parse a name
const attrName = k.parseHtmlName('attr_attribute_1');
console.log(attrName);// => "attribute_1"
//Parse a name
const attrName = k.parseHtmlName('attr_attribute_1');
console.log(attrName);// => "attribute_1"

k.parseMacro

function

Parses a macro so that it is reduced to the final values of all attributes contained in the macro. Will drill down up to 99 levels deep. If the string was not parseable, string will be returned with as much parsed as possible.

  • mutStr - string -

    The string macro to parse

  • attributes - AttributesProxy -

    The K-scaffold Attributes Proxy

  • sections - Object -

    The K-scaffold sections object

  • Returns: string- The string with all attributes replaced by their values (if possible).

k.parseRepeatName

function

Extracts the section (e.g. repeating_equipment), rowID (e.g -;lkj098J:LKj), and field name (e.g. bulk) from a repeating attribute name.

  • string - string -

    The string to parse

  • Returns: array- Array of matches. Index 0: the section name, e.g. repeating_equipment | Index 1:the row ID | index 2: The name of the attribute

  • Returns: Array.<string>undefined

Example

js
//Extract info from a full repeating name
const [section,rowID,attrName] = k.parseRepeatName('repeating_equipment_-8908asdflkjZlkj23_name');
console.log(section);// => "repeating_equipment"
console.log(rowID);// => "-8908asdflkjZlkj23"
console.log(attrName);// => "name"

//Extract info from just a row name
const [section,rowID,attrName] = k.parseRepeatName('repeating_equipment_-8908asdflkjZlkj23');
console.log(section);// => "repeating_equipment"
console.log(rowID);// => "-8908asdflkjZlkj23"
console.log(attrName);// => undefined
//Extract info from a full repeating name
const [section,rowID,attrName] = k.parseRepeatName('repeating_equipment_-8908asdflkjZlkj23_name');
console.log(section);// => "repeating_equipment"
console.log(rowID);// => "-8908asdflkjZlkj23"
console.log(attrName);// => "name"

//Extract info from just a row name
const [section,rowID,attrName] = k.parseRepeatName('repeating_equipment_-8908asdflkjZlkj23');
console.log(section);// => "repeating_equipment"
console.log(rowID);// => "-8908asdflkjZlkj23"
console.log(attrName);// => undefined

k.parseTriggerName

function

Parses out the components of a trigger name similar to parseRepeatName. Aliases: parseClickTrigger.

Aliases: k.parseClickTrigger

  • string - string -

    The triggerName property of the

  • Returns: array- For a repeating button named `repeating_equipment_-LKJhpoi98;lj_roll`, the array will be `['repeating_equipment','-LKJhpoi98;lj','roll']`. For a non repeating button named `roll`, the array will be `[undefined,undefined,'roll']`

  • Returns: Array.<string>undefined

Example

js
//Parse a non repeating trigger
const [section,rowID,attrName] = k.parseTriggerName('clicked:some-button');
console.log(section);// => undefined
console.log(rowID);// => undefined
console.log(attrName);// => "some-button"

//Parse a repeating trigger
const [section,rowID,attrName] = k.parseTriggerName('clicked:repeating_attack_-234lkjpd8fu8usadf_some-button');
console.log(section);// => "repeating_attack"
console.log(rowID);// => "-234lkjpd8fu8usadf"
console.log(attrName);// => "some-button"

//Parse a repeating name
const [section,rowID,attrName] = k.parseTriggerName('repeating_attack_-234lkjpd8fu8usadf_some-button');
console.log(section);// => "repeating_attack"
console.log(rowID);// => "-234lkjpd8fu8usadf"
console.log(attrName);// => "some-button"
//Parse a non repeating trigger
const [section,rowID,attrName] = k.parseTriggerName('clicked:some-button');
console.log(section);// => undefined
console.log(rowID);// => undefined
console.log(attrName);// => "some-button"

//Parse a repeating trigger
const [section,rowID,attrName] = k.parseTriggerName('clicked:repeating_attack_-234lkjpd8fu8usadf_some-button');
console.log(section);// => "repeating_attack"
console.log(rowID);// => "-234lkjpd8fu8usadf"
console.log(attrName);// => "some-button"

//Parse a repeating name
const [section,rowID,attrName] = k.parseTriggerName('repeating_attack_-234lkjpd8fu8usadf_some-button');
console.log(section);// => "repeating_attack"
console.log(rowID);// => "-234lkjpd8fu8usadf"
console.log(attrName);// => "some-button"

k.pseudoQuery

function

Simulates a query for ensuring that async/await works correctly in the sheetworker environment when doing conditional startRolls. E.g. if you have an if/else and only one of the conditions results in startRoll being called (and thus an await), the sheetworker environment would normally crash. Awaiting this in the condition that does not actually need to call startRoll will keep the environment in sync.

  • value - string|number -

    The value to return. Optional.

  • Returns: Promise- Resolves to the value passed to the function

Example

js
const rollFunction = async function(){
 //Get the result of a choose from list query
 const queryResult = await pseudoQuery('a value');
 console.log(queryResult);//=> "a value"
}
const rollFunction = async function(){
 //Get the result of a choose from list query
 const queryResult = await pseudoQuery('a value');
 console.log(queryResult);//=> "a value"
}

k.registerFuncs

function

Function that registers a function for being called via the funcs object. Returns true if the function was successfully registered, and false if it could not be registered for any reason.

  • funcObj - object -

    Object with keys that are names to register functions under and values that are functions.

  • optionsObj - object -

    Object that contains options to use for this registration.

  • optionsObj.type - Array.<string> -

    Array that contains the types of specialized functions that apply to the functions being registered. Valid types are "opener", "updater", and "default". "default" is always used, and never needs to be passed.

  • Returns: boolean- True if the registration succeeded, false if it failed.

Example

js
//Basic Registration
const myFunc = function({trigger,attributes,sections,casc}){};
k.registerFuncs({myFunc});

//Register a function to run on sheet open
const openFunc = function({trigger,attributes,sections,casc}){};
k.registerFuncs({openFunc},{type:['opener']})

//Register a function to run on all events
const allFunc = function({trigger,attributes,sections,casc}){};
k.registerFuncs({allFunc},{type:['all']})
//Basic Registration
const myFunc = function({trigger,attributes,sections,casc}){};
k.registerFuncs({myFunc});

//Register a function to run on sheet open
const openFunc = function({trigger,attributes,sections,casc}){};
k.registerFuncs({openFunc},{type:['opener']})

//Register a function to run on all events
const allFunc = function({trigger,attributes,sections,casc}){};
k.registerFuncs({allFunc},{type:['all']})

k.sanitizeForRegex

function

Replaces problem characters to use a string as a regex

  • text - string -

    The text to replace characters in

  • Returns: stringundefined

Example

js
const textForRegex = k.sanitizeForRegex('.some thing[with characters]');
console.log(textForRegex);// => "\.some thing\[with characters\]"
const textForRegex = k.sanitizeForRegex('.some thing[with characters]');
console.log(textForRegex);// => "\.some thing\[with characters\]"

k.send

function

Sends data to another character sheet to cause a change on that sheet. WARNING, this function should not be used in response to an attribute change to avoid spamming the chat with api messages.

k.send.gif

  • characterName - string -

    The character to connect to

  • funcName - string -

    Name of the function to call similar to function name used in callFunc.

  • args - any -

    The arguments to pass to the function call no the other sheet. These are passed after the normal destructure object for a K-scaffold function call.

Example

js
//Function that is called by the source sheet
const dispatchPartner = async function({trigger,attributes,sections,casc}){
 const partnerName = await (
   attributes.partner_name ?
     k.pseudoQuery(attributes.partner_name) :
     k.extractQueryResult('Partner name')
 );
 attributes.partner_name = partnerName;
 //passing the attributes of the source sheet
 k.send(partnerName,'receivePartner',attributes);
 attributes.set();
};
k.registerFuncs({dispatchPartner});

//Function called on target sheet. Partner is the attributes from the source sheet
const receivePartner  = function({trigger,attributes,sections,casc},partner){
  attributes.from_partner = partner.for_partner;
  attributes.partner_name = partner.character_name;
};
k.registerFuncs({receivePartner });
//Function that is called by the source sheet
const dispatchPartner = async function({trigger,attributes,sections,casc}){
 const partnerName = await (
   attributes.partner_name ?
     k.pseudoQuery(attributes.partner_name) :
     k.extractQueryResult('Partner name')
 );
 attributes.partner_name = partnerName;
 //passing the attributes of the source sheet
 k.send(partnerName,'receivePartner',attributes);
 attributes.set();
};
k.registerFuncs({dispatchPartner});

//Function called on target sheet. Partner is the attributes from the source sheet
const receivePartner  = function({trigger,attributes,sections,casc},partner){
  attributes.from_partner = partner.for_partner;
  attributes.partner_name = partner.character_name;
};
k.registerFuncs({receivePartner });

k.unescape

function

Decodes Base64 encoded strings that were created by the K-scaffold

  • string - string|object|Array.<any> -

    The string of encoded data to decode. If this is not a string, or is not a string that was encoded by the K-scaffold, it will be returned as is.

  • Returns: string|object|Array.<any>undefined

k.value

function

Converts a value to a number, it's default value, or 0 if no default value passed.

  • val - string|number -

    Value to convert to a number

  • def - number -

    The default value, uses 0 if not passed

  • Returns: number|undefinedundefined

Example

js
const num = k.value('100');
console.log(num);// => 100
const num = k.value('100');
console.log(num);// => 100

Released under the MIT License

Copyright ©2023 Scott Casey