Revision as of 18:24, 27 October 2021

Page Updated:   2021-10-27

This article is a stub. You can help the Roll20 Community Wiki by expanding it.

Main Page: Building Character Sheets

Now on Dev Server: jQuery for character sheets! - source

We’ve been working hard to try to make character sheet development more approachable for new sheet authors. Specifically, we’d like to give sheet authors more direct access to the sheet’s HTML elements without having to rely so much on CSS trickery. To this end, we’re exposing some jQuery functionality to sheet workers. For this first iteration, we’re implementing the .on(), .addClass(), .removeClass(), and .toggleClass() functions.

Please note that because of the limitations of how character sheet JavaScript works, there are some significant differences between this implementation of jQuery and the full jQuery library. To emphasize these differences and attempt to reduce confusion, these functions will be called with $20, as opposed to the traditional jQuery $, example:

$20('button.attack').on('mouseenter', (event) => {
    const selector = `#${event.htmlAttributes.id}`;
    $20(selector).toggleClass('active');
});

Note that all selectors for these functions will be automatically scoped to the character sheet.

Limitations

The jQuery functions as they are currently implemented have several limitations:

• The contents of individual repeating items can't be targeted or reacted to
• jQuery occassionally goes unresponsive after uploading new code to the sandbox
• change event has no relation to actual attribute change as it fires as a true "change" event instead of the database change event that other sheetworker listeners fire off of.

Functions

$20(<selector>).on(<event>, <callback (eventinfo)>)

Adds an event handler <callback> to be triggered when the given <event> occurs on elements matching the CSS <selector>

• event: we’re currently supporting the following events: change, click, hover, mouseenter, mouseleave. We may be able to expand this list in the future.

• callback (eventinfo): Because of limitations to how a sheet’s JavaScript is executed, we’re unable to return the full eventinfo object that you’d normally expect from jQuery, nor will this in the context of the callback refer to the triggering element. Instead, the callback function will receive the following object:

{
    // This will include all html attributes of the element that triggered the event,
    // as well as the name of the tag itself
    "htmlAttributes": {
        "class": "green", 
        "id": "test",
        "data-test": "something",
        "tagName": "h4"
    },
    // Whether alt, shift or ctrl keys were down when the event was triggered
    "altKey": false,
    "shiftKey": false,
    "ctrlKey": false,
    // Page coordinates of the triggering event
    "pageX": 70,
    "pageY": 528
}

$20(<selector>).addClass(<class>);

Adds the specified <class> to the elements matching the <selector>, unless the class is already present on the element.

$20(<selector>).removeClass(<class>);

Removes the specified <class> from the elements matching the <selector>, does nothing if the given element does not already have this class.

$20(<selector>).toggleClass(<class>);

Adds the specified <class> to the elements matching the <selector> if the elements do not already have the given class, removes the class if it is already present on the given element.

Examples

Sheets Using jQuery

• Agone v0.9 - menus and subsections using jQuery

Related Pages

• Sheetworker
• BCS/Updates