desc: |
    The basic class definition used by all Organizer panel types. To create a new panel type, extend this library.
funs:
    closeInspectionView:
        summary: |
            This method should close inspection view.
    cmsSetsPanelTUIX:
        summary: |
            Called by Organizer whenever it needs to set the panel data.
    cmsSetsPath:
        summary: |
            Called by Organizer whenever it needs to set the current tag-path.
    cmsSetsRefiner:
        summary: |
            Called by Organizer to give information on the current refiner.
    cmsSetsRequestedItem:
        summary: |
            Called by Organizer whenever a panel is first loaded with a specific item requested.
    cmsSetsSearchTerm:
        summary: |
            If searching is enabled then the CMS will call this method to tell you what the search term was.
        desc: |
            <p>
                (N.b. searching will be enabled if your <code>returnSearchingEnabled()</code> method returns true.)
            </p>
    cmsSetsSelectedItems:
        summary: |
            This method will be called when the CMS sets the items that are selected,
            e.g. when your panel is initially loaded.
        desc: |
            <p>
                This will be an object in the format
            </p>
            <pre>{1: true, 6: true, 18: true}</pre>
            </p><p>
                It is usually called before your panel is drawn so you do not need to update the state
                of the items on the page.
            </p>
    cmsSetsSortColumn:
        summary: |
            Called by Organizer to set the sort column and direction.
    deselectItem:
        summary: |
            This method should cause an item to be deselected
        desc: |
            <p>
                It is called after your panel is drawn so you should update the state of your items
                on the page.
            </p>
    displayToastMessage:
        summary: |
            Called whenever Organizer has saved an item and wants to display a toast message to the administrator.
    itemClick:
        summary: |
            This function is called whenever someone clicks on an item in your panel.
        returns: |
            You should return false (this is used to cancel the event propagation).
    onUnload:
        summary: |
            This is called when an admin navigates away from your panel, or your panel is about to be refreshed/reloaded.
    openInspectionView:
        summary: |
            This method should open inspection view.
    restoreScrollPosition::
        summary: |
            This is called when your panel has just been reloaded/restored, and Organizer wants to prompt you to restore the saved the scroll position of your panel.
    returnAJAXRequests:
        summary: |
            Use this to add any requests you need to the AJAX URL used to call your panel.
        returns: |
            You should return an object. If you do not wish to add any requests then you should return <code>{}<code>.
    returnAJAXURL:
        summary: |
            Use this function to set AJAX URL you want to use to load the panel.
        desc: |
            <p>
                The default value here is a PHP script that will:
            </p>
            <ol>
                <li>Load all of the TUIX properties.</li>
                <li>Call your <code>preFillOrganizerPanel()<code> method.</li>
                <li>Populate items from the database if you set the <code>db_items</code> property in TUIX.</li>
                <li>Call your <code>fillOrganizerPanel()</code> method.</li>
            </ol>
            <p>
                You can skip these steps and not do an AJAX request by returning false instead,
                or do something different by returning a URL to a different PHP script.
            </p>
        returns: |
            You should return a URL, or false.
    returnDoSortingAndSearchingOnServer:
        summary: |
            Return whether you want searching/sorting/pagination to be done server-side.
        desc: |
            <p>
                If you return true, sorting and pagination will be applied on the server.
            </p><p>
                If you return false, your <code>sortAndSearchItems()</code> method will be called instead.
            </p>
        returns: |
            You should return true or false.
    returnInspectionViewEnabled:
        summary: |
            Return whether you want to enable inspection view.
        returns: |
            You should return true or false.
    returnMultipleSelectEnabled:
        summary: |
            Return whether you are allowing multiple items to be selected in full and quick mode.
        desc: |
            <p>
                (In select mode the opening picker will determine whether multiple select is allowed.)
            </p>
        returns: |
            You should return true or false.
    returnPageSize:
        summary: |
            You should return the page size you wish to use, or false to disable pagination.
        returns: |
            You should return an integer, or false.
    returnPanelTitle:
        summary: |
            You should use this to return the panel title.
        desc: |
            <p>
                This is also shown in the back button when the back button would take you back to this panel.
            </p>
        returns: |
            You should return a string.
    returnSearchingEnabled:
        summary: |
            You should return whether to enable searching on a panel.
        returns: |
            You should return true or false.
    returnSelectedItems:
        summary: |
            You should return the currently selected items.
        returns: |
            This should be an object in the format
            <code>{1: true, 6: true, 18: true}</code>
    returnShowLeftColumn:
        summary: |
            Return whether to show the left hand nav.
        desc: |
            <p>
                If you don't write this function, then by default if this is full mode then
                the left hand nav will be shown, and hidden if not full mode.
            </p>
        returns: |
            You should return true or false.
    saveScrollPosition:
        summary: |
            This is called when Organizer wants to prompt you to save the scroll position of your panel.
    searchItems:
        summary: |
            This function allows you to search items on the client side.
        returns: |
            You should return an array of matching ids.
    selectItem:
        summary: |
            This method should cause an item to be selected.
        desc: |
            <p>
                It is called after your panel is drawn so you should update the state of your items
                on the page.
            </p>
        summary: |
            This function is called when Organizer needs to draw the buttons for a panel.
        desc: |
            <p>
                Note that this may be more often than a panel redraw, as it also happens when
                the user selects or deselects an item.
            </p><p>
                You should add html to the buttons, e.g.
            </p>
            <pre>$buttons.html('<p>Hello world!</p>').show();</pre>
    showPanel:
        summary: |
            This function is called when Organizer needs to draw the current panel.
        desc: |
            <p>
                You should add html to the panel, e.g.
            </p>
            <pre>$panel.html('<p>Hello world!</p>').show();</pre>
    sizePanel:
        summary: |
            This is called whenever Organizer is resized, and also on the first load of your panel.
        desc: |
            <p>
                This is called whenever Organizer is resized - i.e. when the administrator resizes their window.
            </p><p>
                It's also called on the first load of your panel after your <code>showPanel()</code> and <code>setButtons()</code> methods have been called.
            </p>
    sortAndSearchItems:
        summary: |
            This function allows you to search/sort items on the client side.
        returns: |
            If your <code>returnDoSortingAndSearchingOnServer()</code> function returned false,
            you should return an array of matching ids.
    sortItems:
        summary: |
            This function allows you to sort items on the client side.
        returns: |
            You should return an array of sorted ids.
    toggleInspectionView:
        summary: |
            This method should toggle inspection view.
    updateItemCheckbox:
        summary: |
            This updates the checkbox for an item, if you are showing checkboxes next to items,
            and the "all items selected" checkbox, if it is on the page.
