desc: |
    A basic library of common functions, available everywhere.
funs:
    cssEscape:
        summary: |
            Escapes a string for CSS text.
        desc: |
            <p>
                Note that on most browsers, this is just a shortcut to the browser's build in CSS escaping function.
                However IE does not have one, so an implementation has been written to cover visitors using IE.
            </p>
        returns: |
            The escaped string.
    defined:
        summary: |
            Checks whether a value is defined.
        returns: |
            Returns true if the value is not <code>undefined</code> or <code>null</code>.
    engToBoolean:
        summary: |
            Converts strings such as "yes", "no", "true", "false", "on" and "off" to a 0 or a 1.
        returns: |
            Either a 0 or a 1.
    extensionOf:
        summary: |
            This function deals with class inheritance in JavaScript, and allows you to create a new class as an extension of an existing one.
        params:
            parent: The parent class. If you don't prove one, this function will create a class that does not extend anything.
            initFun: The constructor function. If you don't provide one, the inherited class' constructor function will be used instead.
        returns: |
            The new class.
    get:
        summary: |
            A shortcut for the document.getElementById() function.
        returns: |
            The DOM-element with the id specified.
    has:
        summary: |
            A shortcut for the hasOwnProperty() method.
        desc: |
            <p>
                Note that you might not see this function called much if you read out source code,
                but the minifier automatically adds calls to this function when it rewrites a <code>foreach</code> loop.
            </p>
        returns: |
            Returns whether the object has the key requested.
    htmlspecialchars:
        summary: |
            Replaces any special characters in a string with html entities.
        desc: |
            <p>E.g. "<span class="code">&lt;</span>" would be replaced with "<span class="code">&amp;lt;</span>" and "<span class="code">&amp;</span>" would be replaced by "<span class="code">&amp;amp;</span>"</p>
        params:
            text: |
                A string containing plain text to escape.
            preserveLineBreaks: |
                If this is set to true, line breaks will be replaced by <span class="code">&lt;br/&gt;</span> tags.
        returns: An escaped string.
    jsEscape:
        summary: |
            Replaces any special or multilingual characters in a string with character escape sequences.
        desc: |
            <p>E.g. "<span class="code">\</span>" would be replaced by "<span class="code">\x5C</span>"</p>
        params:
            text: |
                A string containing plain text to escape.
        returns: An escaped string.
    jsUnescape:
        summary: |
            Attempts to unescape a string that was previously escaped using the zenario.jsEscape() function.
    lib:
        summary: |
            This function can be used to wrap around library definitions.
        desc: |
            <p>
                It provides shortcut variables to several commonly used functions, and has lots of
                properties that our minifiers take advantage of to reduce the filesize of the
                wrapped libraries.
            </p>
    methodsOf:
        summary: |
            Given a class declaration, this function gives access to its methods so you can add or overwrite them.
        returns: |
            The class' method object.

    actAfterDelayIfNotSuperseded:
        summary: |
            This calls the provided function after the specified delay.
        desc: |
            <p>
                If you make another call of the same type, and the previous call will be cancelled if it has not yet run.
            </p>
    addAmp:
        summary: |
            Given a request string, this will add a & onto the start if needed.
        desc: |
            <p>
                This is useful for joining two different request strings together.
            </p>
    addBasePath:
        summary: |
            This function converts relative URLs into an absolute URLs.
        desc: |
            <p>
                It leaves URLs that are already absolute URLs alone so it is safe to use as a filter.
            </p>
        returns: |
            The URL, with the URL base path prepended if needed.
    addClassesToColorbox:
        summary: |
            This function adds CSS class names to the currently open/opening colorbox.
    addJQueryElements:
        summary: |
            This function enables various jQuery widgets (such as colorbox links and tooltips) on the page.
    addStyles:
        summary: |
            Use this to add CSS rules onto the page.
        desc: |
            <p>
                Zenario will create a <code>&lt;style&gt;</code> block with the HTML you specify.
            </p><p>
                If you call this function a second time with the same id, the block that was created previously will be overridden.
            </p>
    ajax:
        summary: |
            Launches an AJAX request to the server.
        desc: |
            <p>
                This function deals with class inheritance in JavaScript, and allows you to create a new class as an extension of an existing one.
            </p>
            <h2>Parameters</h2>
            <h3><code>url</code></h3>
            <p style="margin-left: 40px;">The URL of the request</p>
            <h3><code>post</code></h3>
            <p style="margin-left: 40px;">Pass some POST requests in here to use POST. Or set to true to use POST without any POST requests.</p>
            <h3><code>json</code></h3>
            <p style="margin-left: 40px;">Set this to true if you're expecting a JSON response, and it will be automatically decoded for you.</p>
            <h3><code>useCache</code></h3>
            <p style="margin-left: 40px;">Store the response from this URL in the session cache, and use the cached results next time. Works for GET requests only.</p>
            <p style="margin-left: 40px;">Works for GET requests only.</p>
            <p style="margin-left: 40px;">The cache results are cleared automatically if the data_rev in the database changes.</p>
            <h3><code>retry</code></h3>
            <p style="margin-left: 40px;">In admin mode, if there is an error, an error message will be displayed.</p>
            <p style="margin-left: 40px;">If you set this variable to true, then the CMS will add a retry button that tries the request again.</p>
            <p style="margin-left: 40px;">Alternately you can pass a function that should be called instead..</p>
            <h3><code>continueAnyway</code></h3>
            <p style="margin-left: 40px;">In admin mode, whether to enable the "continue anyway" if there is a PHP notice or var_dump() on a JSON response,
                but the response looks valid otherwise.</p>
            <h3><code>settings</code></h3>
            <p style="margin-left: 40px;">This function acts as a wrapper to the <code>$.ajax()</code> function.
                Use this to parameter in any advanced options you may need that the other parameters do not cover.</p>
            <h3><code>timeout</code></h3>
            <p style="margin-left: 40px;">Set a timeout on the request. If the request takes longer than this it will be aborted,
                then either cancelled or retried if the <code>retry</code> parameter is set.</p>
            <h3><code>AJAXErrorHandler</code></h3>
            <p style="margin-left: 40px;">You can change this variable to override the error handler that's used.</p>
            <h3><code>onRetry</code></h3>
            <p style="margin-left: 40px;">You can pass a function in here that's called when the retry button is pressed (admin mode only).</p>
            <p style="margin-left: 40px;">(Note that the difference between passing a function in using this parameter and passing
                a function in using the <code>retry</code> parameter is that this parameter does not override the default functionality.)</p>
            <h3><code>onCancel</code></h3>
            <p style="margin-left: 40px;">You can pass a function in here that's called when the cancel button is pressed (admin mode only).</p>
            <h3><code>onError</code></h3>
            <p style="margin-left: 40px;">You can pass a function in here that's called when an error occurs.</p>
            <p style="margin-left: 40px;">(But again note that it this does not override the default functionality.)</p>
        returns: |
            This returns a callback object.


    //An easy-as-possible drop-in replacement for zenario.nonAsyncAJAX(), which is now deprecated.
    //It returns a zenario.callback object.
        //url: The URL of the request
        //post: Pass some POST requests in here to use POST. Or set to true to use POST without any POST requests.
        //json: Set to true to decode a JSON response
        //useCache: Store the response in the session cache, and use the cached results next time.
            //Won't apply to POST requests.
            //The cache results are cleared automatically if the data_rev in the database changes.
        //retry: If there's an error, show a "retry" button on the error message.
            //Only works in admin mode.
            //Can be a function to call, or true to recall this function
        //timeout: If set, the request will be automatically retried or cancelled after this amount of time.
    zenario.ajax = function(url, post, json, useCache, retry, continueAnyway, settings, timeout, AJAXErrorHandler, onRetry, onCancel, onError) {

    AJAXLink:
        summary: |
            Given the name of a module, this function returns the link to access its handleAJAX() method.
        desc: |
            <p>
                You can also pass in some GET requests, which will be added to the URL.
            </p>
    applyMergeFields:
        summary: |
            Given a string with merge fields in it, and an object with the values for those merge fields,
            this function will return a new string with the merge fields replaced.
    browserIsChrome:
        summary: |
            Returns true when a visitor is running on Google Chrome.
    browserIsEdge:
        summary: |
            Returns true when a visitor is running on Microsoft's Edge browser.
    browserIsFirefox:
        summary: |
            Returns true when a visitor is running on Firefox.
    browserIsIE:
        summary: |
            Returns true when a visitor is running on Internet Explorer.
        desc: |
            <p>
                (Note that Edge does not count in this case.)
            </p>
    browserIsiOS:
        summary: |
            Returns true when a visitor is running on iOS.
    browserIsiPad:
        summary: |
            Returns true when a visitor is running on an iPad.
    browserIsiPhone:
        summary: |
            Returns true when a visitor is running on an iPhone.
    browserIsOpera:
        summary: |
            Returns true when a visitor is running on Opera.
    browserIsRetina:
        summary: |
            Returns true when a visitor is using a retina screen.
        desc: |
            <p>
                (Note that this check may not work correctly on some old browsers.)
            </p>
    browserIsSafari:
        summary: |
            Returns true when a visitor is running on Safari.
    browserIsWebKit:
        summary: |
            Returns true when a visitor is running on WebKit.
    canCopy:
        summary: |
            Checks whether a visitor's browser supports copy/paste.
        returns: |
            Returns true or false.
    copy:
        summary: |
            Copies the specified text to the clipboard, if the visitor's browser supports copy/paste.
        returns: |
            Returns true if the copy was successful.
    decodeItemIdForStorekeeper:
        summary: |
            This function can be used to give you the original value of an id that was escaped with the encodeItemIdForStorekeeper() function.
        returns: |
            The unescaped id.
    disableScrolling:
        summary: |
            This disables scrolling on the page, until the zenario.enableScrolling() function is called.
    enableFullScreen:
        summary: |
            Enables full-screen mode.
    enableScrolling:
        summary: |
            This enables scrolling on the page if it was disabled by the zenario.disableScrolling() function.
    encodeItemIdForStorekeeper:
        summary: |
            This takes a string, and converts it into a format that is safe to use in comma-separated lists
            or in Organizer item ids.
        returns: |
            The escaped string.
    exitFullScreen:
        summary: |
            Disables full-screen mode.
    getContainerIdFromEl:
        summary: |
            Given a DOM-element or ID that is inside a slot, this function will return the slot's containerId.
        desc: |
            <p>
                Note that some functions that need a containerId as an input will automatically call this function
                if you pass in an DOM-element or ID. 
            </p>
        returns: |
            A containerId.
    getContainerIdFromSlotName:
        summary: |
            Given the name of a slot, this function will return its container id.
        returns: |
            A containerId.
    getEggIdFromEl:
        summary: |
            Given a DOM-element or ID that is inside a nested plugin, this function will return the nested plugin's eggId.
        desc: |
            <p>
                Note that some functions that need an eggId as an input will automatically call this function
                if you pass in an DOM-element or ID. 
            </p>
        returns: |
            An eggId.
    getMouseX:
        summary: |
            Gets the x-co-ordinate of where the user just clicked on the page.
    getMouseY:
        summary: |
            Gets the y-co-ordinate of where the user just clicked on the page.
    getSlotnameFromEl:
        summary: |
            Given a DOM-element or ID that is inside a slot, this function will return the slot's name.
        desc: |
            <p>
                Note that some functions that need a name as an input will automatically call this function
                if you pass in an DOM-element or ID. 
            </p>
        returns: |
            A slot name.
    goToURL:
        summary: |
            Redirects the user to a URL using JavaScript.
        returns: |
            Always returns false.
    IN:
        summary: |
            JavaScript version of our PHP ze::in() function, which itself is similar to MySQL's IN().
        desc: |
            <p>
                Note that most of our functions use camelCase, but "in" is a reserved word in JavaScript,
                so we've written the name in uppercase like the original MySQL function as a work-around.
            </p>
        returns: |
            Returns true if the first parameter matches any of the subsequent parameters.
    inDoc:
        summary: |
            Checks whether a DOM element is still in the document, or if it has been removed.
        returns: |
            Returns true or false.
    isFullScreen:
        summary: |
            Returns true is a visitor's browser is currently running in full-screen mode.
    isFullScreenAvailable:
        summary: |
            Returns true is a visitor's browser supports running in full-screen mode.
    ishttps:
        summary: |
            Returns true when a visitor is accessing the site via https.
    isTouchScreen:
        summary: |
            Returns true when a visitor has a touch screen.
    linkToItem:
        summary: |
            Generates a URL to a content item.
        desc: |
            <p>
                This is a greatly simplified version of the <code>ze\item::link()</code> function.
                The URL generated will be valid, but won't exactly match the canonical URL or friendly URL.
            </p>
        returns: |
            Returns a URL.
    loadLibrary:
        summary: |
            This can be used to load a JavaScript library, if it is not already on the page.
        desc: |
            <p>
                The format/behaviour is very similar to the <code>ze::requireJsLib()</code> function in PHP.
            </p>
            <h2>Parameters</h2>
            <h3><code>path</code></h3>
            <p style="margin-left: 40px;">The URL to the <code>.js</code> file.</p>
            <p style="margin-left: 40px;">If the URL is a relative URL (or matches the <code>URLBasePath</code>),
                the <code>zenarioCSSJSVersionNumber</code> will be automatically added to the end as a cache-killer,
                if not already there.</p>
            <h3><code>callback</code></h3>
            <p style="margin-left: 40px;">A function to call when the library is loaded.</p>
            <h3><code>alreadyLoaded</code></h3>
            <p style="margin-left: 40px;">Set this to true if the library has already been loaded, and you just want to flag this in the system.</p>
            <h3><code>stylesheet</code></h3>
            <p style="margin-left: 40px;">Optional, the URL for a stylesheet that the library needs to be loaded.</p>
    microTemplate:
        summary: |
            A summary.
        desc: |
            <p>
                More words.
            </p>
            <h2>Parameters</h2>
            <h3><code>template</code></h3>
            <p style="margin-left: 40px;">The name of an existing microtemplate.</p>
            <p style="margin-left: 40px;">Alternately you can pass a snippet of microtemplate code in for an
                on-the-fly compilation.</p>
            <h3><code>data</code></h3>
            <p style="margin-left: 40px;">The merge fields for this microtemplate.</p>
            <p style="margin-left: 40px;">If you pass in an object, it will render the microtemplate using these merge fields.</p>
            <p style="margin-left: 40px;">If you pass in an array of objects, it will do a loop and render the microtemplate multiple times.</p>
            <h3><code>filter</code></h3>
            <p style="margin-left: 40px;">If you pass in an array of objects, you can pass in a filter function here to exclude specific rows.</p>
            <h3><code>microTemplates</code></h3>
            <p style="margin-left: 40px;">The library of microtemplates to use when calling microtemplates via name.
                Defaults to the standard visitor microtemplates from the <code>microtemplates/</code> subdirectories of the modules on this site.</p>
            <h2>Return Value</h2>
            <p>
                Returns the HTML code generated by the microtemplate.
            </p><p>
                Note that if you request a microtemplate that does not exist, because of how this this function is designed,
                it will assume that was supposed to be a custom template and return the name back to you.
            </p>
    off:
        summary: |
            This can remove events registered to a slot by the zenario.on() function.
        desc: |
            <p>
                If you specify a containerId, only events for that containerId are removed,
                otherwise this function removes all events from every container in the slot.
            </p><p>
                Likewise, if you specify an event's name, only that event is removed,
                otherwise this function removes events regardless of their name.
            </p>
    on:
        summary: |
            Register an event for a plugin in a slot.
        desc: |
            <p>
                If the plugin is ever removed from the slot (e.g. because of a conductor navigation)
                then the event will automatically be removed as well, unless it was flagged as
                page-wide (see below).
            </p>
            <h2>Parameters</h2>
            <h3><code>slotName</code></h3>
            <h3><code>containerId</code></h3>
            <p style="margin-left: 40px;">You can use these two parameters in three ways:</p>
            <ul style="margin-left: 40px;">
                <li>You can specify a slotName and leave the containerId empty to attach an event to a specific slot.</li>
                <li>You can specify a containerId to attach an event to a element or container in a slot.
                    (If you leave slotName empty it will be auto-calculated from the containerId in this case.)
                <li>If you leave both slotName and the containerId empty then the event will be flagged as page-wide instead.</li>
            </ul>
            <h3><code>eventName</code></h3>
            <p style="margin-left: 40px;">There are two zenario-specific events that you can use here,
                <code>resizeToDesktop<code> and <code>resizeToMobile<code>.
                These are triggered when the grid layout is resized through its breakpoint (which one depends on the direction).</p>
            <p style="margin-left: 40px;">Otherwise you can use the name of any event covered by jQuery.</p>
            <p style="margin-left: 40px;">As long as the name isn't one of the standard HTML/jQuery event names, you can also invert your
                own names, and trigger them using the <code>zenario.sendSignal function</code>.</p>
            <h3><code>handler</code></h3>
            <p style="margin-left: 40px;">A function to call when the event happens.</p>
    pluginAJAXLink:
        summary: |
            Given the name of a module, and the slot/container that one of its plugins is in, this function returns the link to access its handlePluginAJAX() method.
        desc: |
            <p>
                You can also pass in some GET requests, which will be added to the URL.
            </p>
    pluginVisitorTUIXLink:
        summary: |
            Given the name of a FEA module, and the slot/container that one of its plugins is in, this function returns the link to access one of its visitor TUIX methods.
        desc: |
            <p>
                Which method depends on the mode, which can be fill, format, validate, save, or tas
                (which is short for "typeahead search", and leads to the typeaheadSearchAJAX() function).
            </p><p>
                You can also pass in some GET requests, which will be added to the URL.
            </p>
    refreshPluginSlot:
        summary: |
            You can call this function to refresh/reload a plugin by AJAX, with the specified GET requests.
        desc: |
            <p>You can call this function to refresh/reload a plugin by AJAX, with the specified GET requests.</p>
            <h2>Parameters</h2>
            <h3><code>slotName</code></h3>
            <p style="margin-left: 40px;">The name of the slot to refresh.</p>
            <p style="margin-left: 40px;">If the slot contains a nest, then all of the plugins in the nest will be refreshed, not just one.</p>
            <h3><code>instanceId</code></h3>
            <p style="margin-left: 40px;">The instance id of the plugin.</p>
            <p style="margin-left: 40px;">You can set this to "lookup" if you want it to be looked up automatically.</p>
            <h3><code>additionalRequests</code></h3>
            <p style="margin-left: 40px;">Any GET requests you wish to add to the AJAX request.</p>
            <p style="margin-left: 40px;">You can provide a URL request string, or an object of key-value pairs.</p>
            <h3><code>recordInURL</code></h3>
            <p style="margin-left: 40px;">If this is set to <span class="code">true</span>, any GET requests you provide will be added to the URL of the current page.</p>
            <p style="margin-left: 40px;">This will only work if a visitor's browser supports HTML5, however a "hash-bang" system is used as a fallback for browsers that don't support HTML5.</p>
            <h3><code>scrollToTopOfSlot</code></h3>
            <p style="margin-left: 40px;">This will cause the user's browser to scroll up to the top of the slot that is being reloaded.</p>
            <p style="margin-left: 40px;">If not defined, the default value is <span class="code">true</span>.</p>
            <h3><code>fadeOutAndIn</code></h3>
            <p style="margin-left: 40px;">This will cause the slot and its contents to fade out slightly whilst it is reloading.</p>
            <p style="margin-left: 40px;">If you wish to display an AJAX loader or some other sort of loading symbol, you can achieve this by styling the background behind the slot, as the background will be visible whilst the slot is faded out.</p>
            <p style="margin-left: 40px;">If not defined, the default value is <span class="code">true</span>.</p>
            <h3><code>useCache</code></h3>
            <p style="margin-left: 40px;">If this is set to true, the CMS will store AJAX requests in the browser's session cache and only actually perform an AJAX request if the request is not already in the cache.</p>
            <p style="margin-left: 40px;">This behaviour can be somewhat confusing when developing a site, as you can make changes to a plugin but then not see the changes if a request is cached, so it is disabled by default.</p>
    refreshSlot:
        summary: |
            If a slot uses the conductor, this function will reload the current slide.
        desc: |
            <p>
                Otherwise it functions as the <code>zenario.refreshPluginSlot()</code> function.
            </p>
    removeClassesToColorbox:
        summary: |
            This function removes CSS class names from the currently open colorbox.
    scrollLeft::
        summary: |
            Gets or sets the current scroll-left of an element, or the page.
        desc: |
            <p>
                You can target a scrollable element on the page, or the page itself (default).
            </p>
        returns: |
            If a value is not set, then it will return the current value.
            Otherwise it will change the current value.
    scrollToEl:
        summary: |
            Scrolls the page so that the specified element is in view.
    scrollTop:
        summary: |
            Gets or sets the current scroll-top of an element, or the page.
        desc: |
            <p>
                You can target a scrollable element on the page, or the page itself (default).
            </p>
            <h2>Return Value</h2>
            <p>
                If a value is not set, then it will return the current value.
                Otherwise it will change the current value.
            </p>
    scrollToSlotTop:
        summary: |
            This scrolls to show the top of a slot if needed.
        params:
            containerIdSlotNameOrEl: |
                The name of a slot. You can also pass in a containerId or a DOM-element in that slot, which
                will be resolved to the name of that slot.
            neverScrollDown: |
                If this is set, the screen may scroll up but never down.
            time: |
                Set this to animate the scrolling, rather than have it be instant.
            el: |
                The element that should be scrolled. Defaults to the page body.
            offset: |
                Add an offset to the scroll position.
    sendSignal:
        summary: |
            This function can be used to send a signal in JavaScript.
        desc: |
            <p>
                Anything registered for that signal using the <code>zenario.on()</code> function will receive it.
            </p>
        returns: |
            If anything was listing to your signal, you'll receive an array of results containing their return values.
            Otherwise you'll receive an empty array.
    showFileLink:
        summary: |
            Given the name of a module, this function returns the link to access its showFile() method.
        desc: |
            <p>
                You can also pass in some GET requests, which will be added to the URL.
            </p>
    showFloatingBoxLink:
        summary: |
            Given the name of a module, and the slot/container that one of its plugins is in, this function returns the link to access its showFloatingBox() method.
        desc: |
            <p>
                You can also pass in some GET requests, which will be added to the URL.
            </p>
    showImageLink:
        summary: |
            Given the name of a module, this function returns the link to access its showImage() method.
        desc: |
            <p>
                You can also pass in some GET requests, which will be added to the URL.
            </p>
    showSingleSlotLink:
        summary: |
            Given the name of a module, and the slot/container that one of its plugins is in, this function returns the link to access its showSingleSlot() method.
        desc: |
            <p>
                You can also pass in some GET requests, which will be added to the URL.
            </p>
    showStandalonePageLink:
        summary: |
            Given the name of a module, this function returns the link to access its showStandalonePage() method.
        desc: |
            <p>
                You can also pass in some GET requests, which will be added to the URL.
            </p>
    shrtNms:
        summary: |
            This takes a JavaScript library, scans the functions in the library, and adds short-names for them all.
        desc: |
            <p>
                For some libraries, the minifier replaces all function calls with calls to the short-names, so the minified code
                will not function in the browser until the short-names are added via this function.
            </p>
    splitFlagsFromMessage:
        summary: |
            Given a message that might have flags in it, this parses the flags then strips them from the message.
        desc: |
            <p>
                Flags can look like this:
            </p>
            <pre>&gt;!--Flag--&lt;</pre>
            <p>
                ...or like this:
            </p>
            <pre>&gt;!--Flag:Value--&lt;</pre>
        returns: |
            An object in the form:
            <pre>{
                responseText: '...',
                flags: { ... }
            }</pre>
    toObject:
        summary: |
            Given a request string, this function tries to turn it back into an object.
        desc: |
            <p>
                If you pass in something that is already an object, then this function will optionally clone the object
                (if the <code>clone</code> parameter is set) and then just return it as is.
            </p>
        returns: |
            An object.
    unfun:
        summary: |
            If passed a function, this calls the function and then returns the result.
            Otherwise it returns the input you give it.
    urlRequest:
        summary: |
            If you pass an object of key-value pairs into this function, it will return them as a string in the format for a URL request.
        returns: |
            A URL query string.
    versionOfIE:
        summary: |
            When running on Internet Explorer, this function gets the current version number.
    visitorTUIXLink:
        summary: |
            Given the name of a FEA module, this function returns the link to access one of its visitor TUIX methods.
        desc: |
            <p>
                Which method depends on the mode, which can be fill, format, validate, save, or tas
                (which is short for "typeahead search", and leads to the typeaheadSearchAJAX() function).
            </p><p>
                You can also pass in some GET requests, which will be added to the URL.
            </p>
