desc: |
    Functions used in admin mode for general or miscellaneous tasks.
funs:
    adjustBox:
        summary: |
            Adjusts the display settings of a popout box opened by the zenarioA.openBox() function.
    AJAXErrorHandler:
        summary: |
            Zenario's error handler for any errors that happen on AJAX requests in admin mode.
        desc: |
            <p>
                This function will try to show a popout error message,
                and depending on the features used in the request, add the
                Retry/Continue buttons.
            </p>
    checkCookiesEnabled:
        summary: |
            Checks whether cookies are enabled and able to be used.
        returns: |
            A callback object.
    checkIfBoxIsOpen:
        summary: |
            Checks if a specific box opened by the zenarioA.openBox() function is current still open.
    checkSlotsBeingEdited:
        summary: |
            Checks if any slots on the page were flagged as being edited by an admin.
        returns: |
            Returns true or false.
    clearToast:
        summary: |
            Clears a toast message that was displayed using the zenarioA.toast() function.
    closeBox:
        summary: |
            Closes a box opened by the zenarioA.openBox() function.
    closeFloatingBox:
        summary: |
            Closes the box that was displayed by the zenarioA.floatingBox() function.
        desc: |
            <p>
                Note that clicking on one of the buttons on the box will automatically close it,
                so you would not normally need to call this function.
            </p>
    closeInfoBox:
        summary: |
            Closes the info box opened by the zenarioA.infoBox() function.
    closeSlotControls:
        summary: |
            Closes the slot controls that were opened by the zenarioA.openSlotControls() function.
    closeSlotControlsAfterDelay:
        summary: |
            Closes the slot controls that were opened by the zenarioA.openSlotControls() function, after a delay.
    copy:
        summary: |
            Copies the specified text into the clipboard, and then shows a toast message to confirm this has happened.
    copyContents:
        summary: |
            Copies the settings of a version-controlled plugin in a slot.
        desc: |
            <p>
                Note that this only works on certain plugins,
                and the contents are copied to the user's $_SESSION and not the user's clipboard.
            </p>
    cutContents:
        summary: |
            Copies the settings of a version-controlled plugin in a slot, and then deletes them.
        desc: |
            <p>
                Note that this only works on certain plugins,
                and the contents are copied to the user's $_SESSION and not the user's clipboard.
            </p>
    debug:
        summary: |
            Opens the TUIX dev tools.
    draft:
        summary: |
            This function is used to check that an admin is on a draft, if they click on any Edit button on the page.
        desc: |
            <h2>Return Value</h2>
            <p>
                This function returns true or false, depending on whether it is safe to continue.
            </p><p>
                If it was not safe, the admin will be shown an error message.
            </p><p>
                In the case where the current content item is not a draft, but it is possible to make one,
                the message will prompt the admin to create one, after which the element that they just clicked on
                will be automatically re-clicked if possible.
            </p>
    enableDragDropUploadInTinyMCE:
        summary: |
            Enables an Admin to upload an image by dragging and dropping it onto a TinyMCE editor.
        desc: |
            <p>
                The file will be uploaded using a call to the <code>handleOrganizerPanelAJAX()</code> function
                of the Common Features Module.
            </p>
    floatingBox:
        summary: |
            Displays a simple popout box with a message and one more more buttons.
    formatFilesizeNicely:
        summary: |
            Given a number in bytes, this function will format it nicely (e.g. in KB, MB, etc.)
        returns: |
            The formatted number.
    generateRandomString:
        summary: |
            Generates a randomly generated base-62 string.
    getGridSlotDetails:
        summary: |
            This function gets layout information about the current CSS grid and a specific slot on that grid.
        returns: |
            An object with information in its properties.
    getItemFromOrganizer:
        summary: |
            Given a path and the id of an item, this gets information about that item form Organizer.
        returns: |
            A data object, or a callback object if the async option was set
            (this is recommended, as not using it is deprecated).
    hideAJAXLoader:
        summary: |
            Hides the "JAX loader if it was displayed by the
            zenarioA.showAJAXLoader()
            function.
    infoBox:
        summary: |
            This opens an "info box" which displays information on the current version of the CMS and where it is installed..
    isHtaccessWorking:
        summary: |
            Checks whether the .htaccess file on the server appears to be set up and working.
    loggedOut:
        summary: |
            Checks a message to see if it has the <!--Logged_Out--> flag set at the start,
            and displays the "you have been logged out" box if it is there.
        returns: |
            Returns true if the flag was set.
    multipleLanguagesEnabled:
        summary: |
            Checks if more than one language is enabled on a site.
        returns: |
            Returns true if two or more languages are enabled.
    translationsEnabled:
        summary: |
            Checks if translations are enabled on a site.
        returns: |
            Returns true if translations are enabled.
    getDefaultLanguageName:
        summary: |
            Displays the name of the default language for a site.
        returns: |
            The name of the site's default language.
    notification:
        summary: |
            Briefly displays a short message in a "toast" notification at the top of the screen..
        example: |
            <pre>zenarioA.notification('Hello world!');</pre>
    nowDoingSomething:
        summary: |
            This can be used to display a pulsating "Loading..." or "Saving..." message on the screen..
        desc: |
            <p>
                The first parameter should be set to either "loading" or "saving" to display a message,
                or left undefined to hide the previously displayed message.
            </p>
        example: |
            <pre>zenarioA.nowDoingSomething('loading');
            $.ajax('api.html').always(
                function() {
                    zenarioA.nowDoingSomething();
                }
            );</pre>
    openBox:
        summary: |
            Opens a new popout box.
        desc: |
            <p>
                Popout boxes are essentially Zenario's own version of lightboxes/colorboxes, but with lots of
                Zenario-specific features and tweaks.
            </p><p>
                If you just want a colorbox, we would recommend using the colorbox library instead as it's more
                general purpose and is better documented.
            </p>
    openSlotControls:
        summary: |
            Opens the slot control drop-down menu for a slot.
    organizerQuick:
        summary: |
            Opens Organizer in "quick" mode.
    organizerSelect:
        summary: |
            Opens Organizer in "select" mode.
    pasteContents:
        summary: |
            Pastes the settings of a version-controlled plugin into a slot.
        desc: |
            <p>
                Note that this only works on certain plugins,
                the type of plugin needs to match the one that was copied,
                and the contents are taken from the user's $_SESSION and not the user's clipboard.
            </p>
    reloadMenuPlugins:
        summary: |
            Reloads all of the menu plugins on the current page.
        desc: |
            <p>
                (A plugin is considered to be related to the menu if it's being show on the Menu Tab of the Admin Toolbar.)
            </p>
    rememberToast:
        summary: |
            Saves the value of the last toast message opened using the zenarioA.toast() function ahead of a page/browser reload.
        desc: |
            <p>
                After the page is reloaded, the toast message will be re-displayed.
            </p>
    savePageMode:
        summary: |
            Whenever the admin clicks something that changes the page mode of the Admin Toolbar,
            this function sends an AJAX request to the server to remember what it was.
    scanHyperlinksAndDisplayStatus:
        summary: |
            This adds the warning symbols in admin mode where links go to pages that aren't published.
    showAJAXLoader:
        summary: |
            Calling this function dims the screen and displays an AJAX loader (i.e. the spinning circle thing).
        desc: |
            <p>
                You can use this function if you want to stop the admin from interacting with the page while you
                wait for an AJAX request to load.
            </p><p>
                The admin will not be able to click on anything until you remove the loader by calling
                <span class="code">zenarioA.hideAJAXLoader()</span>
            </p>
    showHelp:
        summary: |
            This displays Organizer's help-system.
        desc: |
            <p>
                Requires Organizer to be already open to work.
            </p><p>
                Note that this help system is powered by intro.js, and this function is basically just sets everything up and calls it.
            </p>
    showMessage:
        summary: |
            This displays a CMS-styled message box in admin mode.
        params:
            message: |
                A message to display. You can enter a plain text message, or html.
                You can prefix this message with any of the controls documented on the <a href="customising-popout-messages-in-admin-mode">Customising Message Boxes in Admin Mode page</a>.
            buttonsHTML: |
                Some html for some buttons at the bottom of the box.
                If set to <span class="code">undefined</span> or <span class="code">true</span>, a simple "OK" button will appear.
            messageType: |
                You can enter "error", "success", "warning" or "question" to set the style of the message.
            modal: |
                If this is set to true, the admin won't be able to close the box by clicking in the background.
            htmlEscapeMessage: |
                If you entered a plain text message into <span class="code">message</span>, you should set this to <span class="code">true</span>.
    showPagePreview:
        summary: |
            Opens a colorbox, showing a preview of what the current page would look like in visitor mode.
    showTutorial:
        summary: |
            This displays the popout box in Organizer with links to the tutorial videos.
        desc: |
            <p>
                Requires Organizer to be already open.
            </p>
    swapContents:
        summary: |
            Swaps the settings of a version-controlled plugin in a slot with the last settings that were copied.
        desc: |
            <p>
                Note that this only works on certain plugins,
                the type of plugin needs to match the one that was copied,
                and the contents are swapped with the contents from the user's $_SESSION and not the user's clipboard.
            </p>
    tinyMCEPasteRreprocess:
        summary: |
            This function attempts to do lots of string-replacements in
            an attempt tidy any bad/messy HTML from TinyMCE up a little bit.
        returns: |
            None (the input is modified).
    toast:
        summary: |
            A shortcut to the toastr library, with some sensible default settings.
    toggleShowGrid:
        summary: |
            This function toggles on/off the "grid" display viewing the Edit or the Layout tab on the Admin Toolbar.
        desc: |
            <p>
                This only works for layouts created by Gridmaker; if a layout was not created using Gridmaker, you won't see anything.
            </p>
    tooltips:
        summary: |
            Sets tooltips on the page or element, just like the zenario.tooltips() function,
            except with admin-mode stylings.
