Skip to content

JavaScript

Jump to bottom Edit New page
Thomas Neumann edited this page Dec 5, 2024 · 23 revisions

Inline JavaScript, which is used for framework plugins and widgets (e.g., slideshows, events, tabs, etc.), should be wrapped in the following code:

<script>
  window.addEventListener('inlineJSReady', function() {
    // Your JavaScript goes here.
  }, false);
</script>

Audio/Video Players

We suggest that you make use of the media hosting service MediaHub, which provides embed codes that integrate some very useful accessibly features such as searchable captions. Media hosted outside of MediaHub can still use the same player as follows.

To embed a video on your page so that it will work across browsers, use the mediaelement_wdn plugin. To use this plugin, you will need to do the following:

  1. Embed the video on your page with either the <audio> or the <video> element.
  2. Give the <audio> or the <video> element a class of wdn_player.
  3. Load the mediaelement_wdn plugin with <script>WDN.initializePlugin('mediaelement_wdn');</script>. Please note: You only need to run this script once per page. Putting it at the bottom of your content ensure that all players get loaded when ready.

There are many things to consider when it comes to accessibility and media.

  1. All media must have captions. UNL MediaHub makes this easy.
  2. Avoid auto-playing media: Media that automatically plays when a page is loaded can be confusing and unwanted.
  3. Keep flashes of light to a minimum. Excessive flashes and/or strobing effects can cause issues for people who are prone to seizures.

Media should be hosted on the unl.edu domain whenever possible (as opposed to YouTube, etc.) to ensure that it is available to all visitors. Some locations such as China or K–12 schools will block popular media hosting platforms such as YouTube or Vimeo. To ensure that everyone who visits your site can watch media, please host the content on unl.edu. An easy solution for hosting media at UNL is UNL MediaHub.

Button Toggles

Button Toggles allow buttons to toggle other elements when clicked. This component is the base for other components. This component rely on specific CSS classes and does have CSS animations that will take place during the toggling.

Options Data Attribute Default value Description
Controls data-controls '' This will be the id of the element that we are going to toggle (required)
Label On data-label-on '' This will control the aria label for the button for when the element is off/collapsed, not needed if there is text inside the button
Label Off data-label-off '' This will control the aria label for the button for when the element is on/expanded, not needed if there is text inside the button
Start Expanded data-start-expanded 'true' This will allow us to define the starting state of the toggle, this should be pared with the hidden attribute on the toggled element to avoid bad content paints before the javascript loads
Events Dispatches/Listens Description
toggleButtonOn Dispatches This event is dispatched when the button is toggled to the on/expanded state
toggleButtonOff Dispatches This event is dispatched when the button is toggled to the off/collapsed state
toggleElementOn Dispatches This event is dispatched when the element is toggled to the on/expanded state
toggleElementOff Dispatches This event is dispatched when the element is toggled to the off/collapsed state
commandClose Listens The component will listen for this event on both the button and toggled element, when the event is heard it will try to toggle the button off/collapsed
commandOpen Listens The component will listen for this event on both the button and toggled element, when the event is heard it will try to toggle the button on/expanded
commandToggle Listens The component will listen for this event on both the button and toggled element, when the event is heard it will try to toggle the button state
Keys Actions
space Toggles the state
escape Tries to toggle off/collapsed

These keys only work when focus is on the button

<!-- Starting Expanded Example -->
<div id="my-div">
  My First Div
</div>

<button
  class="dcf-btn-toggle dcf-btn dcf-btn-primary"
  data-controls="my-div"
  data-label-on="Open My First Div"
  data-label-off="Close My First Div"
  data-start-expanded="true"
>
  Toggle My First Div (Starts On)
</button>

<!-- This is only required once per page with button-toggles -->
<script>
  window.addEventListener('inlineJSReady', function() {
    WDN.initializePlugin('button-toggles');
  }, false);
</script>
<!-- Starting Collapsed Example -->
<div id="my-div-with-id" hidden>
  My Second Div
</div>

<button
  id="my-div-with-id-toggle-button"
  class="dcf-btn-toggle dcf-btn dcf-btn-primary"
  data-controls="my-div-with-id"
  data-label-on="Open My Second Div"
  data-label-off="Close My Second Div"
  data-start-expanded="false"
>
  Toggle My Second Div (Starts Off)
</button>

<!-- This is only required once per page with button-toggles -->
<script>
  window.addEventListener('inlineJSReady', function() {
    WDN.initializePlugin('button-toggles');
  }, false);
</script>

Collapsible Field Set

Collapsible field set's are field sets that can be collapsed. This will add a toggle button in the legend and allow the contents within the field set to be collapsible. This component builds on the button toggles component. This component rely on specific CSS classes and does have CSS animations that will take place during the toggling.

Items inside the fieldset tag will be moved into an internal div tag which is used for the collapsing of the content. This will result in event listeners and other javascript variables to not work since the original elements would be deleted. As a result there is a fieldsetReady event that is fired after this process takes place, so any event listeners or variables will need to be re-created after the event has been dispatched.

Options Data Attribute Default value Description
Start Expanded data-start-expanded 'true' This will allow us to define the starting state of the toggle, this should be pared with the hidden attribute on the toggled element to avoid bad content paints before the javascript loads
Events Dispatches/Listens Description
toggleButtonOn Dispatches This event is dispatched when the button is toggled to the on/expanded state
toggleButtonOff Dispatches This event is dispatched when the button is toggled to the off/collapsed state
toggleElementOn Dispatches This event is dispatched when the element is toggled to the on/expanded state
toggleElementOff Dispatches This event is dispatched when the element is toggled to the off/collapsed state
commandClose Listens The component will listen for this event on both the button and toggled element, when the event is heard it will try to toggle the button off/collapsed
commandOpen Listens The component will listen for this event on both the button and toggled element, when the event is heard it will try to toggle the button on/expanded
commandToggle Listens The component will listen for this event on both the button and toggled element, when the event is heard it will try to toggle the button state
fieldsetReady Dispatches Once the fieldset is ready and initialized this event will be dispatched
Keys Actions
space Toggles the state
escape Tries to toggle off/collapsed

These keys only work when focus is on the button

<!-- Starts Expanded Example -->
<form class="dcf-form">
  <fieldset class="dcf-collapsible-fieldset">
    <legend>Checkboxes</legend>
    <div class="dcf-input-checkbox">
      <input id="dcf-components-form-checkbox1A" type="checkbox" value="0">
      <label for="dcf-components-form-checkbox1A">Checkbox 1</label>
    </div>
    <div class="dcf-input-checkbox">
      <input id="dcf-components-form-checkbox2A" type="checkbox" value="1">
      <label for="dcf-components-form-checkbox2A">Checkbox 2</label>
    </div>
  </fieldset>
</form>

<!-- This is only required once per page with collapsible fieldset -->
<script>
  window.addEventListener('inlineJSReady', function() {
    WDN.initializePlugin('collapsible-fieldsets');
  }, false);
</script>
<!-- Starts Collapsed Example -->
<form class="dcf-form">
  <fieldset class="dcf-collapsible-fieldset" data-start-expanded="false" hidden>
    <legend>Checkboxes (Starts collapsed)</legend>
    <div class="dcf-input-checkbox">
      <input id="dcf-components-form-checkbox1B" type="checkbox" value="0">
      <label for="dcf-components-form-checkbox1B">Checkbox 1</label>
    </div>
    <div class="dcf-input-checkbox">
      <input id="dcf-components-form-checkbox2B" type="checkbox" value="1">
      <label for="dcf-components-form-checkbox2B">Checkbox 2</label>
    </div>
  </fieldset>
</form>

<!-- This is only required once per page with collapsible fieldset -->
<script>
  window.addEventListener('inlineJSReady', function() {
    WDN.initializePlugin('collapsible-fieldsets');
  }, false);
</script>

Events

Pulling data from the UNL Events system is available with a number of widgets, each with their own styling and interactions.

The events plugin provides a vertically rendered list of upcoming events. The monthwidget plugin provides a tabular month calendar rendering of events for the current month. The events-band plugin provides a horizontal block grid of upcoming events. Each of these plugins work by providing a placeholder element on your page and adding a script to inject the content loaded asynchronously from the events system.

How to Configure the Widgets

All of the events widgets are initialized via JavaScript with the WDN.initializePlugin('plugin-name', {configuration object}) function. A JavaScript object can be passed as the second parameter to customize the widgets.

For example, all of the widgets will use the main UNL calendar by default, but you can use your calendar by passing a url option in the configuration object (the second parameter of the WDN.initializePlugin function). Note that the url option has to be the base URL for your calendar (use https://events.unl.edu/yourcalendar/ and not https://events.unl.edu/yourcalendar/upcoming). For example:

<script>
  window.addEventListener('inlineJSReady', function() {
    WDN.initializePlugin('events', {url: 'https://events.unl.edu/yourcalendar/', limit: 5});
  });
</script>

Events Month Widget

Options Type Default Description
url String 'https://events.unl.edu/' URL of the events calendar you'd like to pull from
container Selector '#monthwidget' A CSS selector for loading the widget into 
<div id="monthwidget"></div>
<script>
  window.addEventListener('inlineJSReady', function() {
    WDN.initializePlugin('monthwidget');
  });
</script>

Events List Widget

Options Type Default Description
url String 'https://events.unl.edu/' URL of the events calendar you'd like to pull from
title String '' Label for the More Events link
container Selector '#wdn_calendarDisplay' A CSS selector for loading the widget into
limit Integer 10 Maximum number of upcoming events to show
rooms Boolean false A flag to designate if event location rooms should be shown 
<div id="events"></div>
<script>
  window.addEventListener('inlineJSReady', function() {
    WDN.initializePlugin('events', {limit: 5});
  });
</script>

Events Band Widget

Options Type Default Description
url String 'https://events.unl.edu/' URL of the events calendar you'd like to pull from
title String '' Label for the More Events link
container Selector '#events-band' A CSS selector for loading the widget into
limit Integer 10 Maximum number of upcoming events to show
rooms Boolean false A flag to designate if event location rooms should be shown 
<div id="events-band"></div>
<script>
  window.addEventListener('inlineJSReady', function() {
    WDN.initializePlugin('events-band', {limit: 6, rooms: true});
  });
</script>

Extended Fonts

To load the optional brand serif font (Source Serif), apply the unl-font-serif class to desired text, then add this snippet of JavaScript to either your page or your site's JavaScript:

<script>
  window.addEventListener('inlineJSReady', function() {
    WDN.initializePlugin('font-serif');
  }, false);
</script>

GSAP

Framework animations use GreenSock Animation Platform (GSAP) version 3.x. You can use framework classes for scroll animations or create your own custom animations by beginning with the following JavaScript:

<script>
  window.addEventListener('DOMContentLoaded', function() {
    require(['plugins/gsap/gsap.min'], function() {
      // Custom GSAP goes here
    });
  }, false);
</script>

Scroll Animations

Pair the following JavaScript with CSS classes to animate elements on page scroll.

<script>
  window.addEventListener('DOMContentLoaded', function() {
    WDN.initializePlugin('scroll-animations');
  }, false);
</script>

Using RequireJS and jQuery

The UNLedu framework uses a tool called RequireJS to load JavaScript libraries and dependencies. This guide will walk you through some RequireJS basics, including how to load JavaScript dependencies safely. At first glance, this might seem needlessly complex, but it is actually pretty simple. RequireJS has some great documentation on how to use it. We won’t dive into the details here, only the basics.

Loading jQuery

Simply use the require function. The first parameter should be an array of dependencies, and the second parameter should be an anonymous function to run after the dependencies have loaded. The parameters for the anonymous function are mapped to the first parameter of the require function.

require(['jquery'], function($) {
    //place any code that relies on $ here
});

Loading Multiple and Custom Libraries

See the loading jQuery example for details on how the require function works

require(['absolute path to library', 'jquery'], function(loadedLib, $) {
    //place any code that relies on $ and loadedLib here
});

Configuring RequireJS

So now that you're convinced that RequireJS is awesome, let's cover how to configure it to work with your dependencies that are not a part of the framework. By default, we set the baseUrl configuration value to the base JavaScript directory for framework bundled dependencies. It should be no surprise that this won't work for module dependencies that you want to host in your own directory structure. To work around this, you should set a paths configuration value for each local dependency.

require.config({
    paths: {
    "local-module-name": "url/to/local-module-name"
    }
});

If your website or project has a lot of javascript dependencies, it might be worth configuring RequireJS to search certain paths on your server for the correct JavaScript file. See the RequireJS documentation for details on how to accomplish this.

Dealing with Dependencies That Are Not AMD Loader Friendly/Ready

While many JavaScript plugins and modules are adopting AMD loaders, there is a chance you will come across something that still uses the old way of relying on variables in the global scope. We’ve prepared a common jQuery dependency wrapper that can be put around these scripts so they work with the module loader.

header:

(function(factory) {
    if (typeof define === 'function' && define.amd) {
    // AMD
    define(['jquery'], factory);
    } else if (typeof module === 'object' && module.exports) {
    factory(require('jquery'));
    } else {
    // Browser globals
    factory(jQuery);
    }
}(function(jQuery) {

footer:

}));
Add a custom footer
Add a custom sidebar
Clone this wiki locally