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 GM’s and co-GM’s 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 computer 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 Profile, then to Manage Favorites.  Then find your campaign in your Favorites, and click on "Deny Custom JavaScript" next to the campaign's name.  This will prevent the Custom JavaScript from running on your computer, so you can then access your Campaign Settings Advanced tab and fix the bug in your JavaScript.  Then return to your Manage Favorites and click "Allow Custom JavaScript" to allow the Custom JavaScript to run on your computer 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 Custom 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 link to the section below called "How to Allow Custom JavaScript".  There will also be a link for the visitor to dismiss the message and to not allow the Custom JavaScript to run on their computer.  So, 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);});

How to Allow Custom JavaScript

NOTE: Custom JavaScript can be used to hack your computer.  Make sure you fully trust the GM of the campaign before you allow the campaign's Custom JavaScript to run on your computer.

To allow a campaign's Custom JavaScript to run on your computer, you must first Favorite the campaign by going to the campaign's Front Page (in the left hand menu), and clicking the "Become a Fan" button in the right hand column.

Then go to your Profile by hovering over your avatar in the upper left hand corner, and clicking on the "My Profile" menu item.

Then scroll down near the bottom on the left to "Favorite Campaigns", and click the Edit icon.

Then find the name of the campaign in your list of Favorites and click the "Allow Custom JavaScript" link.  It will then change to "Deny Custom JavaScript" to show that Custom JavaScript is now allowed for that campaign.  (Click the link again to toggle Custom JavaScript back off.  If you Delete a campaign from your Favorites, the Custom JavaScript for that campaign will also no longer run on your computer.)

Then click the name of the campaign to be taken back to the campaign and see the Custom JavaScript in action.

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