Creating a CLIO Activity Type
Overview
All activity types are created using JavaScript, and are defined as a single function designed to manipulate a single container. Using JavaScript or jQuery, you can add containers to this primary container and style them using CSS. Below, you will see the layout of all activity types, with the large gray area being the container.
Understanding an Activity Configuration File
Each Activity’s JSON configuration file follows the same format, allowing the CLIO web application to identify the appropriate activity type and correctly load content. When opened in a JSON editor, you can see that every activity contains the same two objects; ‘Activity’ and ‘Content’. The ‘Activity’ object contains the information about how to describe the activity. This includes which activity type it is, how it should be organized, and general configuration options, such as title or description. The ‘Content’ object contains data that is specific to the activity type.
Understanding Activity Types
Within the CLIO root directory, there is a ‘config’ folder. This folder contains configuration code for the CLIO interface, such as activity types and menus. To create a new activity type, we need to navigate to the “@ActivityTypes” within “config”. Each folder listed here is an activity type. Each activity type folder contains three folders and two files:
| Resource | Type | Description |
|---|---|---|
| @About.json | File | Contains the required information about the activity type. |
| activity_type.js | File | Contains custom functions and events for the activity type. |
| @Libraries | Folder | Contains all of the activity types JS libraries. |
| @Stylesheets | Folder | Contains all of the stylesheets that are loaded. |
| @Templates | Folder | Contains all of the HTML template files. |
When CLIO loads an Activity Configuration File, it will use the “Activity” object to configure the activity screen and load the proper Activity Type to display the activity’s content. The “Content” object stored within an Activity Configuration File is passed directly into the specified Activity Type’s initialize function.
Creating an Activity Type
Within the CLIO Welcome Package ZIP, available on our website, there is a ‘Template’ folder. Navigate here so you can select the “ActivityTypeTemplate” folder and copy it. In order to create a new activity type, we will need to paste this folder into the “@ActivityTypes” folder defined in the last section.
Once the folder is copied, we will need to give it a unique name that cannot contain spaces. This is important as it is how the activity type is defined by CLIO. Rename the folder you just copied to “TestActivity” and hit enter to commit the change.
Creating a Script
Navigate into the TestActivity folder that we created in the previous section. In order to keep our different Activity Type scripts organized, it is recommended that we rename the file “ActivityTypeTemplate.js” to “TestActivity.js”. We will be using this script name in a later section.
Once renamed, we can explore the template script file by opening it in the text editor of your choice. This file will contain the initialization function for the new Test Activity that we are creating, as well as any events for it, such as a user clicking a button or resizing the window.
First, we need to rename our initialization function from “loadActivityTypeTemplate” to “loadTestActivity”. We will not change the “(program, content)” section of the function, as these allow the CLIO web application to pass the currently loaded Program and the “Content” object of an Activity Configuration File into the activity being loaded. For documentation purposes, it is also important to change the comments at the start of the document to better reflect the purposes of this file.
Under the “Activity Events” section, we can add any event-driven interactions for this activity. These events can include changing classes on a button when we click it so we can alter its visual appearance or causing the activity frame to resize along with the browser window. CLIO is all loaded dynamically through JavaScript/jQuery so it is recommended that you use the ‘$(document).on(“click”,”#element”,function())’ event handler, instead of the ‘$(“#element”).click(function())” event handler. For handling metadata attributes, it is recommended that you use “.attr()” instead of “.data()”. This is because “.attr()” will create the metadata attribute if it doesn’t already exist, while “.data()” requires that the metadata tag already exist.
Under the “Activity Function” section, we need to update the initialization function. This is what CLIO will do when an activity with this activity type is loaded. This function is initialized after all JavaScript libraries, stylesheets and templates are already loaded and applied. Once CLIO has run this initialization script, there is no way to retrieve the “Content” object without loading the JSON file again. In most situations, this function will be used to set up the activity for later interactions in a way that do not require reloading content. For example, many CLIO activity types add metadata attributes to interface elements to allow them to be retrieved and utilized as users move through the activity.
Creating a Template
When CLIO loads an activity, it will automatically populate the screen with the HTML template that is defined within the activity type. The HTML templates for an activity type are stored within the “@Template” folder within the root directory of the Activity Type.
There is a “default” template stored in here that can be modified to add additional HTML elements to the activity interface without needing to dynamically create them all through jQuery. Right-click on the “default.html” file and select “Open with…” to open it in a text editor instead of a web browser.
It is highly recommended that all HTML elements for the activity type are within a container that has a unique ID as this makes it easier to theme interface elements through stylesheets. We are going to rename this unique container from “activity_type_template” to “test_activity” to better match the rest of our activity type naming conventions. We will also add the “#important_button” element that we referenced in our previous script.
Now, we can save our new template file.
Defining an Activity Type
Now that we’ve created the necessary folder structure, we need to begin to define the activity type for use by CLIO. This will include the friendly name that is displayed in the interface, its description, and which functions to execute. We need to open the “@About.json” file to make changes. This can be done in a plain text editor, but for the purpose of this manual we will be using jsoneditoronline.org/.
From here, we can begin configuring the required information for our new “Test Activity” type. We can begin to fill in the required fields to define a new activity type within CLIO.
| Object | Description | Expected Parameters |
|---|---|---|
| Name | This is the friendly name for the activity type, that is shown within the interface. | Plain Text |
| Enabled | Whether CLIO should load this activity type. | “True” or “false” |
| Initialize – Script | This is the first script that the activity type will load and must contain the Initialize – Function | This location is relative to the root of the Activity Type folder. |
| Initialize – Function | This is the function that will be passed the activity’s content and used to initialize the activity when run by the user. | This should be the name of a function as defined within the “Initialize – Script” object. |
| Initialize – Template | This is the HTML template that is loaded into the Activity Content container by default. | This location is relative to the root of the @Templates folder.
This option assumes the extension of html. |
| Configuration – Icon | This is the icon that is used by the interface to designate this activity type. | This location is relative to the root of the Activity Type folder. |
| Configuration – Description | This is the description that is used by the interface to describe this activity type. | Plain Text |
| Configuration – Help | This is a brief description of how to use the activity type. | Plain Text |
We can change the “Name” object to have the key “Test Activity”. We need to update the “Initialize” options to reflect the new script, function and template we previously created. For “Script”, we use “TestActivity.js” because it is contained in the root of our activity type directory. For “Function”, we should enter the function “loadTestActivity” we created previously. For “Template”, we can leave this as “default”. Finally, we need to update the description to display within the interface.
Once you are finished, you can download the finished JSON file by clicking ‘Save’ and then ‘Save to Disk’. This file can be copied to the “TestActivity” Activity Type folder, replacing the other “@About.json” file.
Integrated JavaScript Libraries
The CLIO web application already has a collection of JavaScript libraries integrated that can be used when creating new activity types. Documentation for these libraries is available on their website.
| Library | Website | Description |
|---|---|---|
| jQuery | jQuery.com | Library used for HTML document traversal and manipulation, event handling, animation and ajax content. |
| Fancybox v3 | fancyapps.com | Lightbox library used for presenting various types of media. |
| Alertify | alertifyjs.com | Library used to create dynamic and interactive alerts and notifications. |
| mCustomScrollbar | github.com/malihu | Create and theme touch-enabled custom scrollbars. |
| Owl Carousel | owlcarousel2.github.io | Create responsive touch-enabled carousel sliders. |
| Video.js | videojs.com | HTML5 video player framework |
| TimeMe | github.com/jasonzissman | Time user interactions and monitor for idle states. |
| Three.js | threejs.org | General purpose 3D library used for rendering interactive objects and environments. |
| Two.js | two.js.org | General purpose 2D library used for rendering interactive lines and polygons. |
| Popper | popper.js.org | Tooltip and popover positioning engine that is used in conjunction with Tippy to create tooltip notifications. |
| Tippy | atomiks.github.io/ | Create tooltips and popovers based on user interaction and events. |
Custom Functions
There are a collection of functions that have been created for use in the interface or other activity types that were included as part of the CLIO web application, making it so they can be integrated into new activity types.
Integrating JavaScript Libraries
When creating a new activity type, new JavaScript libraries can usually be integrated automatically by copying the desired JavaScript library into the “@Libraries” folder for that activity type.
These libraries will be loaded at the initialization of the CLIO web application. Libraries in this folder are loaded alphabetically, so if it required that they be integrated in a certain order due to dependencies, you can prepend a numerical signifier, such as “1_library.js”.
Styling an Activity Type
When creating a new activity type, new stylesheets can usually be integrated automatically by copying the desired stylesheet into the “@Stylesheets” folder for that activity type.
These stylesheets will be loaded at the initialization of the CLIO web application. For ease of styling, it is highly recommended that all activity type elements be within a container that has a unique ID. For example, the Test Activity type that we’ve been developing uses a template where all interactive and styled elements are contained within a div element with the unique ID of “test_activity”.
When creating a stylesheet, this allows us to reference all elements contained within the ‘test_activity” relatively. For example, we can reference all div elements within the “test_activity” container by using the CSS selector of “#test_activity div” to increase CSS specificity. Depending on whether the activity being loaded as a parent activity or a child (“meta”) activity, the container will change, so it is best to define a unique container for the activity type.
Using CLIO Assets and Icons
There is a collection of icons available within the ‘img’ folder contained within the root directory of the CLIO web application. These icons are available in black, white and green, which are used for different accessibility contrast modes and interface themes.
Within each color group, there are several subgroups used to organize the major icon groups. These icons are sorted relative to how they are used by CLIO, and not with the original organizational scheme of the Material Icons.
Controlling Hardware
When running a web server locally on the hardware that is being used to power the exhibit, such as the prototype Raspberry Pi kiosk, It is possible to control the hardware through the web application interface. During testing, this was used to provide a graphical interface for controlling the kiosk’s screen brightness through the Settings and Accessibility menus. This should only be done when the web server is running on a kiosk that otherwise has no access to the internet.
Hardware control can be achieved through a combination of JavaScript, PHP and Python scripting. By using JavaScript and AJAX/AJAJ, we can asynchronously call a PHP script as part of an event or the initialization script of an activity type. When this PHP script is called, it is used to initialize a Python script stored locally on the hardware. This Python script can be used to manipulate Raspberry Pi hardware, execute console commands or run prepared code to control lights, speakers or other exhibit mechanics attached to a Raspberry Pi GPIO port.
| Documentation | |
|---|---|
| Installation | Look and Feel |
| Interaction Modes | Developing Activity Types |
| Creating an Interactive | Framework |
| Integrating CLIO | Contribute |
