Using CLIO Functions

Overview

There are several 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.

Interface

These functions are used to control various underlying parts of the CLIO Interface.

getCurrentURL

Description: Returns an object with information about the current URL.

Arguments: none

Example:

getCurrentURL();

Output:

{

    "url": "http://10.0.0.50//clio/development/?program=NICOToothSleuth&activity=pathfinder",

    "base": "http://10.0.0.50//clio/development/",

    "hash": "",

    "program": "NICOToothSleuth",

    "activity": "pathfinder",

    "menu": ""

}

removeBodyClassByPrefix

Description: Removes all classes from body that begin with a prefix.

Arguments: prefix

Argument	Description	Expected Parameter
prefix	The prefix for the classes to be removed from the body element.	String

Example:

removeBodyClassByPrefix("theme_");

Output:

(All classes that start with “theme_” will be removed from the “body” object.)

removeSelectorClassByPrefix

Description: Removes all classes from the selector that begin with a prefix.

Arguments: selector, prefix

Argument	Description	Expected Parameter
selector	An ID (“#unique_id”) or class (“.class”) selector.	Valid element class or id
prefix	The prefix for the classes to be removed from the selected element.	String

Example:

removeBodyClassByPrefix("#menu_content_wrapper", "menu_");

Output:

(All classes beginning with “menu_” will be removed from the element with the id of “menu_content_wrapper”)

applyTheme

Description: Loads the selected theme from the CLIO theme folder and applies it, unless there is an accessibility contrast mode enabled.  This does not automatically remove existing theme classes and should be used in conjunction with removeBodyClassByPrefix(“theme_”).

Arguments: theme

Argument	Description	Expected Parameter
theme	The name of the theme, not including the “theme_” prefix.	String

Example:

applyTheme("default");

Output:

(Loads the “theme_default.css” stylesheet from the CLIO web application’s “theme” folder, contained within the “css” folder.  Then, CLIO will verify that an accessibility contrast mode is not enabled before applying the “theme_default” class to the “body” element.)

AJAX

These functions are used to asynchronously load and parse various types of data without needing to reload the web application through the use of AJAX (or AJAJ).

parseJSONContent

Description: Returns an object parsed from a JSON file.

Arguments: file

Argument	Description	Expected Parameter
file	The JSON file to be loaded and parsed.	Relative location from the CLIO JS directory.

Example:

parseJSONContent(“test.json”);

Output:

{

    “Test”: “Content”

}

loadHTML

Description: Returns an HTML string parsed from an HTML file.

Arguments: file

Argument	Description	Expected Parameter
file	The HTML file to be loaded and parsed.	Relative location from the CLIO JS directory.

Example:

var template = loadHTML(“template.html”);

$(“#activity_content”).html(template)

Output:

(Creates a variable containing the contents of the “template.html” file, and uses it to replace the HTML content of the “activity_content” container.)

parseDirectory

Description: Returns an array of strings containing the name of each file in a directory.

Arguments: directory

Argument	Description	Expected Parameter
directory	The directory to be parsed.	Relative location from the CLIO JS directory.

Example:

var directory_contents = parseDirectory(“contents/”);

Output:

[

    “Test”,

    “Test2”,

    “Test3”

]

loadScript

Description: Loads a script from a URL before adding it to the DOM and initializing it for use.

Arguments: url

Argument	Description	Expected Parameter
url	The JavaScript file to be loaded.	Relative location from the CLIO JS directory.

Example:

loadScript(“test.js”);

Output:

(The “test.js” JavaScript file is loaded and appended to the “Head” element.)

Rich Text

These functions are used to parse the BBCode-like format that the interface uses to encode rich text into plain text.

BBCodeParser.process

Description: Decodes the BBCode-like tag system into more usable HTML.

Arguments: content

Argument	Description	Expected Parameter
content	A string to be decoded into HTML.	Text with embedded BBCode tags

Example:

BBCodeParser.process(“[p][b]Title[/b][i]This[/i] is a test.[/p]”)

Output:

<p><b>Title</b><i>This</i> is a test.</p>

Settings

These functions are used to get and set various settings in LocalStorage.  These are use specifically by the Settings menu.

clearSettings

Description: Resets all settings by clearing the HTML5 LocalStorage cache.

Arguments: none

Example:

clearSettings();

Output:

(The LocalStorage cache is emptied.)

getSetting

Description: Retrieves a setting from the LocalStorage cache by its name, or returns a default if field is empty.

Arguments: setting_name, setting_default

Argument	Description	Expected Parameter
setting_name	A unique identifier used to store a string in the LocalStorage cache.	String
setting_default	Value returned when there is nothing found in the LocalStorage cache.	String

Example:

setSetting(“setting__theme”,”aqua”)

getSetting(“setting__theme”,”default”)

Output:

aqua

setSetting

Description: Saves a setting in the LocalStorage cache by a unique name.

Arguments: setting_name, user_setting

Argument	Description	Expected Parameter
setting_name	A unique identifier used to store a string in the LocalStorage cache.	String
user_setting	A string to be in the LocalStorage cache under the above name.	String

Example:

setSetting(“setting__theme”,”aqua”)

getSetting(“setting__theme”,”default”)

Output:

aqua

Accessibility

These functions are used to get and set various accessibility settings in SessionStorage.  These are use specifically by the Accessibility menu.

clearAccessability

Description: Manually resets accessibility options by returning them to defaults.  This is used by the Accessibility menu "Reset Accessibility button" to reset options without reloading the page.

Arguments: none

Example:

clearAccessibility();

Output:

(All accessibility settings are returned to their default states and the dropdown menus are updated.)

getAccessibility

Description: Retrieves an accessibility setting from the SessionStorage cache by its name, or returns a default if field is empty.

Arguments: setting_name, setting_default

Argument	Description	Expected Parameter
setting_name	A unique identifier used to store a string in the SessionStorage cache.	String
setting_default	Returned when there is nothing found in the SessionStorage cache.	String

Example:

setAccessibility(“accessibility__colorblind”,”true”)

getAccessibility(“accessibility__colorblind”,”false”)

Output:

true

setAccessibility

Description: Saves an accessibility setting in the SessionStorage cache by a unique name.

Arguments: setting_name, user_setting

Argument	Description	Expected Parameter
setting_name	A unique identifier used to store a string in the SessionStorage cache.	String
user_setting	A string to be in the SessionStorage cache under the above name.	String

Example:

setAccessibility(“accessibility__colorblind”,”true”)

getAccessibility(“accessibility__colorblind”,”false”)

Output:

true

LocalStorage

These functions are used to get and set strings and JSON objects from the HTML LocalStorage cache.  The LocalStorage cache persists between different sessions, even if the web browser is closed.

getLocal

Description: Retrieves a string from the LocalStorage cache by a unique name, or returns a default if there is nothing found in the cache.

Arguments: name, setting_default

Argument	Description	Expected Parameter
name	A unique identifier used to store a string in the LocalStorage cache.	String
setting_default	Returned when there is nothing found in the LocalStorage cache.	String

Example:

setLocal(“test_setting”,”true”)

getLocal(“test_setting”,”false”)

Output:

true

setLocal

Description: Saves a string to the LocalStorage cache by a unique name.

Arguments: name, user_setting

Argument	Description	Expected Parameter
name	A unique identifier used to store a string in the LocalStorage cache.	String
user_setting	A string to be saved to the LocalStorage cache by the unique identifier entered above.	String

Example:

setLocal(“test_setting”,”true”)

getLocal(“test_setting”,”false”)

Output:

true

getLocalObject

Description: Retrieves an object from the LocalStorage cache by a unique name, or returns a default if there is nothing found in the cache.

Arguments: name, setting_default

Argument	Description	Expected Parameter
name	A unique identifier used to store a string in the LocalStorage cache.	String
setting_default	A default string that is returned when there is nothing found in the LocalStorage cache.	String

Example:

var object_variable = {“key”:”value”};

setLocalObject(“test_object”,object_variable);

getLocalObject(“test_object”,””);

Output:

{“key”:”value”}

setLocalObject

Description: Saves an object to the LocalStorage cache by a unique name.

Arguments: name, user_setting

Argument	Description	Expected Parameter
name	A unique identifier used to store a string in the LocalStorage cache.	String
user_setting	An object to be saved to the LocalStorage cache under the unique name selected above.	String

Example:

var object_variable = {“key”:”value”};

setLocalObject(“test_object”,object_variable);

getLocalObject(“test_object”,””);

Output:

{“key”:”value”}

SessionStorage

These functions are used to get and set strings and JSON objects within the HTML SessionStorage cache.  The SessionStorage cache exists only for the current session of the application, such as a single tab or window, and is cleared when ended.

getSession

Description: Retrieves a string from the SessionStorage cache by a unique name, or returns a default if there is nothing found in the cache.

Arguments: name, setting_default

Argument	Description	Expected Parameter
name	A unique identifier used to store a string in the SessionStorage cache.	String
setting_default	A default string that is returned when there is nothing found in the SessionStorage cache.	String

Example:

setSession(“test_setting”,”true”)

getSession(“test_setting”,”false”)

Output:

true

setSession

Description: Saves a string to the SessionStorage cache by a unique name.

Arguments: name, user_setting

Argument	Description	Expected Parameter
name	A unique identifier used to store a string in the SessionStorage cache.	String
user_setting	A string to be saved to the SessionStorage cache by the unique identifier entered above.	String

Example:

setSession(“test_setting”,”true”)

getSession(“test_setting”,”false”)

Output:

true

getSessionObject

Description: Retrieves an object from the SessionStorage cache by a unique name, or returns a default if there is nothing found in the cache.

Arguments: name, setting_default

Argument	Description	Expected Parameter
name	A unique identifier used to store a string in the SessionStorage cache.	String
setting_default	A default string that is returned when there is nothing found in the SessionStorage cache.	String

Example:

var object_variable = {“key”:”value”};

setSessionObject(“test_object”,object_variable);

getSessionObject(“test_object”,””);

Output:

{“key”:”value”}

setSessionObject

Description: Saves an object to the SessionStorage cache by a unique name.

Arguments: name, user_setting

Argument	Description	Expected Parameter
name	A unique identifier used to store a string in the SessionStorage cache.	String
user_setting	An object to be saved to the SessionStorage cache under the unique name selected above.	String

Example:

var object_variable = {“key”:”value”};

setSessionObject(“test_object”,object_variable);

getSessionObject(“test_object”,””);

Output:

{“key”:”value”}

Program

These functions are used to load new CLIO programs and information about them.

requestPrograms

Description: Retrieves an array with the name of each Program available within the CLIO “content” folder.

Arguments: none

Example:

requestPrograms();

Output:

[“Default”,”Examples”,”ScienceProgram”]

loadProgramDetails

Description: Retrieves an object containing the information stored within a Program’s “@About.json” file.

Arguments: program

Argument	Description	Expected Parameter
program	Unique name of a Program contained within the CLIO “content” folder.	String

Example:

loadProgramDetails(“Default”);

Output:

{

"Institution":"CLIO Museums",

"Program":"Getting Started",

"Description":"Learn more about the different types of activities available on the kiosk.",

"About":"The CLIO kiosk can be used to create pop-up exhibits with interactive activities.",

"DefaultMenu":"Exhibit"

}

Activity

These functions are used to load activities and the information about them.  They can also be used to create new types of meta activities.

requestActivities

Description: Retrieves an array containing the name of all non-hidden activities within a Program’s “@Activities” folder.

Arguments: program

Argument	Description	Expected Parameter
program	Unique name of a Program contained within the CLIO “content” folder.	String

Example:

requestActivities(“Default”);

Output:

[

“future”,

”hardware”,

”kioskimages”,

”meta”,

”microcomputers”,

”microcomputertype”,

”micromania”,

”protoparts”,

”prototype”,

”raspberrypi”,

”richtext”,

”theteam”,

”types”,

”videoexample”

]

loadActivityDetails

Arguments: program, activity

Description: Retrieves an object containing the data within an Activity’s configuration JSON file.

Argument	Description	Expected Parameter
program	Unique name of a Program contained within the CLIO “content” folder.	String
activity	Unique name of an Activity contained within the Programs “@Activity” folder.	String

Example:

loadActivityDetails(“Default”,”meta”);

Output:

{

"Activity":{

"Type":"Meta",

"Audience":"newbie",

"Grouping":{

"Section":"CLIO",

"Exhibit":"MuseWeb 2020"

},

"Configuration":{

"Hidden":"false",

"Theme":"default",

"Accessibility":"true",

"Subheader":"false"

},

"Info":{

"Title":"Meta Activity",

"Preview":"milkyway.jpg",

"Description": "Link different activities together into one meta activity.",

"Video":""

}

},

"Content":{

"1":{

"Preview":"clio_bg.png",

"Description":"Custom Description 1",

"Program":"Default",

"Activity":"future"

},

"2":{

"Preview":"clio_bg.png",

"Description":"Custom Description 2",

"Program":"Default",

"Activity":"hardware"

},

"3":{

"Preview":"clio_bg.png",

"Description":"Custom Description 3",

"Program":"Default",

"Activity":"kioskimages"

},

"4":{

"Preview":"clio_bg.png",

"Description":"Custom Description 4",

"Program":"Default",

"Activity":"kioskobjects"

}

}

}

loadActivity

Description: Configures the CLIO interface to display a fullscreen interactive activity, used for both Facilitator Mode and Exhibit Mode.

Arguments: program, activity

Argument	Description	Expected Parameter
program	Unique name of a Program contained within the CLIO “content” folder.	String
activity	Unique name of an Activity contained within the Programs “@Activity” folder.	String

Example:

loadActivity(“Default”,”meta”);

Output:

(The CLIO Interface menu is configured to show a Home button on the left side, as well as an info and accessibility button on the right.  If the interface is in Facilitator Mode, there is also a quick button to add and remove the activity from Exhibit Mode.  The activity is loaded into the “activity_content” container which fills the rest of the screen.)

returnHome

Description: Clears and hides the activity container before returning to the appropriate interface for either Facilitator Mode or Exhibit Mode.

Arguments: none

Example:

returnHome();

Output:

(The CLIO Interface returns to the appropriate interface for the current Mode.  If in Exhibit Mode, the carousel is displayed.  If in Facilitator Mode, the Activities menu is displayed.)

getActivityTypes

Description: Returns an object containing the unique identifier of each available Activity Type, which also contains the friendly title and its description.

Arguments: none

Example:

getActivityTypes();

Output:

{

    "AnnotatedImage": {

        "Name": "Annotated Image",

        "Description": "[p]This activity superimposes two images over each other, with a divider that can be dragged to show the visual difference between them. By default, this activity will generate small buttons at the specified coordinates that can be used to open full screen pop-up displays with rich text content.  The buttons can also be hidden, creating customizable hot areas that open the corresponding informational pop-up when touched.  You can also choose to enable a ‘hint’ button that will reveal these hot areas to the user if touched.  This activity can be used to compare two disparate images, overlay new information on an image, or show different views of the same object.[/p]"

    }

}

Audience

These functions are used to load information about the audiences that are tied to a Program.

getAudiences

Description: Returns an object containing the unique identifier of each available Audience for the selected Program, which also contains the friendly title and its description.

Arguments: program

Argument	Description	Expected Parameter
program	Unique name of a Program contained within the CLIO “content” folder.	String

Example:

getAudiences(“Default”);

Output:

{

    "newbie": {

        "Name": "New to Tech",

        "Description": "[p]Activities are designed for people who don't have much previous experience with technology.[/p]"

    },

    "techie": {

        "Name": "Tech Enthusiast",

        "Description": "[p]Activities are designed for people who have a foundational understanding of collection of difference technologies.[/p]"

    },

    "coder": {

        "Name": "Tech Developer",

        "Description": "[p]Activities are designed for people who have written code and developed programs.[/p]"

    }

}

Discussions

These functions are used to load discussions that are displayed in the Facilitation menu when in Facilitator Mode.

requestFacilitationDiscussions

Description: Retrieves an array containing the name of all non-hidden activities within a Program’s “@Activities” folder.

Arguments: program

Argument	Description	Expected Parameter
program	Unique name of a Program contained within the CLIO “content” folder.	String

Example:

requestActivities(“Default”);

Output:

[

    "1_Hardware.json",

    "2_Software.json",

    "3_Interface.json",

    "4_FacilitatorMode.json",

    "5_Activities.json",

    "6_Settings.json",

    "7_Accessibility.json",

    "8_ExhibitMode.json"

]

loadDiscussionDetails

Description: Retrieves an object containing the data stored within the specific Discussions JSON file.

Arguments: program, discussion

Argument	Description	Expected Parameter
program	Unique name of a Program contained within the CLIO “content” folder.	String
discussion	Unique name of a discussion JSON file contained within the Programs “@Activity” folder.	String

Example:

loadDiscussionDetails(“Default”,”1_Hardware”);

Output:

{

    "Name": "Hardware",

    "Description": "[p]What kind of hardware went into making this kiosk?[/p]",

    "Discussion": {

        "Basic": "[p]This is a basic explainer of open hardware.  3D printing was also used to make the case, which is a combination of open source software and open hardware.[/p]",

        "Advanced": "[p]This is a more indepth explainer of the filament used; PLA and TPU.  They are biodegradable.   We use parts provided primarily by Raspberry Pi and Adafruit.[/p]"

    }

}

Scrollbars

These functions are used to load the custom scrollbar.

initializeContainerScrollBar

Description: Initializes the custom interface scrollbar on the selected container.

Arguments: container, show_scrollbar, auto_dragger_length, show_scroll_buttons

Argument	Description	Expected Parameter
container	ID of the container to create the scrollbar.	String
show_scrollbar	Enable the scrollbar by default, even when not in use.	"true" or "false"
auto_dragger_length	Enable the scrollbar to resize based on the amount of content in the container.	"true" or "false"
show_scroll_buttons	Enable the scroll buttons at the top and bottom of the scroll bar.	"true" or "false"

Example:

initializeContainerScrollBar("#activity_content",true,true,true)

Output:

(A scrollbar is added to the "#activity_content" container with a scroll bar, automatically sized dragger bar and scroll buttons.)

destroyScrollbar

Description: Destroys the custom interface scrollbar around the selected container.

Arguments: container

Argument	Description	Expected Parameter
container	ID of the container to destroy the scrollbar.	String

Example:

destroyScrollbar(“#activity_content”);

Output:

(The vertical scrollbar around the container with the ID of “activity_content” is destroyed.)

Look Closer

These functions are used to create and destroy Look Closer pop-ups, which are used within the interface for prompts and modal windows, as well as by activity types to display rich text and media.

createLookCloserPopUp

Description: Creates a Look Closer pop-up window that covers the full screen.

Arguments: options

Argument	Description	Expected Parameter
options	An object containing the configuration settings for the Look Closer window.	Object

Header

Argument	Description	Expected Parameter
Style	Configure the display of the header.	"default", "success", "warning", or "error"
Text	A plain text string to display at the top of the pop-up.	String

Scrollbar

Argument	Description	Expected Parameter
Scrollbar	Configure the scrollbar.	“true”,”false”, or ”auto”

Interaction

Argument	Description	Expected Parameter
Type	What is the interaction paradigm?	"acknowledge", "accept_cancel", "confirm_deny", "custom"
Prefix	A prefix to be added to the ID of all toolbar buttons, allowing for specialized events for Look Closer toolbar buttons.	String
HTML	When Type is set to ‘custom’, this can be used to place HTML into the Look Closer toolbar to add custom buttons or displays.	HTML String
Close	Enable or disable a close button in the top right corner.	"true" or "false"
Swipe	Enable or disable swipe/drag to close.	"true" or "false"

Content

Argument	Description	Expected Parameter
Type	What is the type of content for this pop-up?	"html", "richtext", or "gallery"
Data	The content to be displayed.	This required content of this variable is dependent on the type defined above.

Data

Argument	Description	Expected Parameter
html	What is the type of content for this pop-up?	A string containing HTML code.
richtext	The content to be displayed.	A string containing the BBCode-like rich text encoding.
gallery		An array of objects, each containing a “src” and “caption”. [ {   "src": “relative”/location.jpg”,   "caption": “Plain Text” }, {   "src": “relative”/location.jpg”,   "caption": “Plain Text” } ]

Example:

var options =

{

  "Header":

  {

    "Style":"error",

    "Text":"Test"

  },

  "Scrollbar":false,

  "Interaction":

  {

    "Type”:”confirm_deny”,

    "Prefix":"error_”,

    “Swipe”:”false”,

    “Close”:”true”

  },

  "Content":

  {

    "Type":"html",

    "Data":'<b>Test</b>'

  }

};

Output:

destroyLookCloserPopUp

Description: Destroys any open Look Closer pop-ups.

Arguments: none

Example:

destroyLookCloserPopUp();

Output:

(Any open Look Closer pop-ups are destroyed.)