Custom JavaScript Basics

JavaScript is a scripting language that enables you to dynamically change HTML and CSS. You can use it to add functionality above and beyond the defaults that Obsidian Portal provides to custom fit the experience for you and your gaming group.

Please Note:       

  • Custom JavaScript is an Ascendant Only feature that is available for GMs and co-GMs of a campaign on the Campaign Settings Advanced tab.
  • This is an advanced feature. It allows for maximum flexibility, but like any coding project, it may require you to experiment and look for solutions. You can ask for help here on our forums by searching for topics or by clicking the “New Discussion” button to ask your question.
  • JavaScript can be extremely powerful and can be used to hack the device of someone that is visiting your campaign.  Please be sure that you fully understand the effects of any JavaScript code you include in your campaign, especially if you are copying it from someone else.  If you have any questions or concerns, feel free to ask any questions in the Community Forums.
  • If you accidentally add JavaScript code that makes your campaign difficult or impossible to use (like creating an infinite loop), you can go to "<your campaign slug>.obsidianportal.com/reset-custom-js".  This will prevent the Custom JavaScript from running on your device, so you can then access your Campaign Settings Advanced tab and fix the bug in your JavaScript.  Then you can click "Allow Custom JavaScript" to allow the Custom JavaScript to run on your device again.

Getting Started

To start customizing your campaign, log in to Obsidian Portal, navigate to the campaign you want to work on, and click on your “Settings” tab on the left sidebar menu (the gears icon). Click on the “Advanced” tab on the upper right of the screen and scroll down until you see the fields labeled “Custom JavaScript - Campaign Members Only” and "Custom JavaScript - Public".

If these fields are locked out, it means you need to upgrade to an Ascendant membership in order to access them.

The "Custom JavaScript - Campaign Members Only" section will only be applied to members of the campaign: GM, co-GMs, and players. Other visitors to the campaign will not have access to the scripts in this section, so you can use API urls and other data here that you might want to keep private from the public.

The "Custom JavaScript - Public" section will be applied to all visitors to the campaign, including campaign members.

If you’re brand new to JavaScript, you can look up tutorials, templates, syntax, code definitions, examples, and advanced concepts here: w3schools.com.

After you add some Custom JavaScript to your campaign, and Save it, all visitors to your campaign that would be affected by that JavaScript (including you) will get an alert window, at the top of the campaign on all pages of the campaign, telling them that Custom JavaScript has been added to the campaign.  There will be a button to "Allow Custom JavaScript" and a button to "Deny Custom JavaScript".

Until one button or the other is chosen, the campaign's Custom CSS will not be applied. This is meant to prevent someone from maliciously using the Custom CSS to alter the Allow/Deny popup for the Custom JavaScript.

Since the visitor can choose "Deny Custom JavaScript", be aware that some visitors to your campaign may choose not to run your Custom JavaScript.

(Note: this means that if you only have JavaScript in the "Custom JavaScript - Campaign Members Only" section, and the "Custom JavaScript - Public" section is blank, then visitors to the campaign will not be shown the alert window at the top of the campaign.)

How to Work with Insertable JavaScript

Insertable JavaScript are the buttons on the side of the Wiki and Adventure Log editing windows that enable inserting carousels, accordions, random generators, and tooltips.

Using these will insert JavaScript into the page to make these features work.  But if you want your Custom JavaScript to affect these features, then the features need to exist on the page before your code can interact with them.

To help with this we've added an event that gets fired on the "document" called "opJsInitializedEvent".

For example, the default behavior for the accordions is that all sections are initially collapsed/closed.  But if you instead want the accordions in your campaign to always have the first section initially open, then you can use Custom JavaScript to do that.  But you will need to set that parameter after the accordion has been created in the life-cycle of the page, which will be after the "opJsInitializedEvent" has been fired.

Here is the code that would always open the first section of all the accordions in your campaign:

$( document ).on("opJsInitializedEvent", function( event, ui ) {  $( 'div[class^="op_accordion_"]' ).accordion("option", "active", 0);});

Final Note:

Don’t forget - if you get stuck, the best place to ask for help is in our forums, where expert gamers and coding pros are always happy to assist.

Still need help? Contact Us Contact Us