---

top_level_page: admin_boxes
pages:
    - fields
    - key
    - multiple_edit
    - pick_items
    - plugin_setting
    - site_setting
    - slider
    - tabs
    - upload
    - validation
    - values
    
    
 #   - admin_boxes
 #   - edit_mode
 #   - fields
 #   - visible_if
 #   - multiple_edit
 #   - picked_items
 #   - plugin_setting
 #   - pressed
 #   - site_setting
 #   - slider
 #   - snippet
 #   - tabs
 #   - type
 #   - validation
 #   - values
 #   - _picked_items
 #   - _value


common_definitions:
    stringy: &stringy
        - number
        - string
    booly: &booly
        - boolean
        - string
    variable: &variable
        - boolean
        - number
        - string
        - "null"
    ord: &ord
        type: *stringy
        description: >
            This controls the order in which elements are drawn on the screen.
            
            If not set, it defaults to the order Zenario finds them in.
            
            From version 10.1 onwards, we have some logic where you can place a field or a button
            immediately before or after an existing field or button using an offset.
            To do this you need to use a pattern like this: "field_name + 0.1" (to put your field after)
            or like this: "field_name - 0.1" (to put your field before).

            
    copy_of: &copy_of
        type: string
        description: >
            You can enter the code-name of another element (this must be element with the same
            parent element) to copy the properties from.
            
            Any other properties you set will override the copied properties.
            
            If the element that you are attempting to copy is missing, unset, or not yet loaded,
            then your element will be removed.
            
            This works from version 8.0 onwards.
    hidden: &hidden
        type: boolean
        description: >
            The hidden property hides elements from view when <code>true</code>.
    visible_if: &visible_if
        type:
            - string
            - object
        description: >
            A snippet of JavaScript code to be evaluated.
            
            From version 7.5 onwards, to avoid using an inefficent eval(), you can also call a function
            by using an object of the form:
                lib.methodName => arg1, arg2, arg3, ...
            
            The visible_if property hides elements from view if the code provided does not evaluate to <code>true</code>.
            
            See https://zenar.io/visibility-in-tuix for examples.


$schema: 'http://json-schema.org/draft-04/schema#'
title: Admin Box Schema

type: object
additionalProperties:
    title: Admin Box
    type: object
    required:
        - key
        - tabs
    properties:
        title:
            type: string
            description: >
                The title for the Admin Box
                If you do not specify this property the title bar will be hidden from view.
        
        title_for_existing_records:
            type: string
            description: >
                If you set this property, it will be used instead of the title when editing an existing record.
                
                (The toolkit will consider that you are editing an existing record if the $box['key']['id']
                 variable is set.)
                
                You can also use merge fields, e.g.: Editing the animal "[[details/name]]".
                
                
                This works from version 7.2 onwards.
                
                As of version 8.7, you can also include variables from the key.
        
        key:
            type: object
            properties:
                id:
                    type: *variable
                    modified_by_cms: true
                    description: >
                        The id key for this Admin Box.
                        
                        If opening an Admin Box from Organizer, this should match up with the
                        id of an Item in the current Panel. If you open the Admin Box using an
                        Item Button in Organizer, this will be automatically populated.
                        
                        If you are saving a newly created Item, you should populate the id
                        yourself as soon as you know what it is.
                openNextMode:
                    type: boolean
                    description: >
                        Set this to true if you want to edit multiple items one after the other.
                        
                        This will cause the "Skip to next", "Save & next" and "Save & close" buttons
                        to appear at the bottom instead of the "save" button.
                        
                        This works from version 9.3 onwards.
                nextIds:
                    type: string
                    description: >
                        If you want to edit multiple items one after the other, place the id of the
                        first item to edit in the id variable, and the ids of subsequent items in a
                        comma-separated list in this variable.
                        
                        When the user presses the "Skip to next" or "Save & next" button, the current
                        id will be deleted, the nextIds will be placed back into the id variable,
                        and your fillAdminBox() method will be called again.
                        
                        This works from version 9.3 onwards.
            additionalProperties:
                type: *variable
                description: >
                    A variable or meta-information that you define about this Admin Box.
            description: >
                The key of an Admin Box lets you receive and/or store meta-information and variables.
        
        identifier:
            type: object
            properties:
                css_class:
                    type: string
                    description: >
                        A CSS class name, which should be used to define an icon.
                label:
                    type: string
                    description: >
                        You can use this to set a label next to the id.
                value:
                    type: *stringy
                    description: >
                        The value of the id to show.
                        
                        Defaults to the $box['key']['id'] variable if not set.
                    default: (Defaults to the $box['key']['id'] variable)
                frontend_link:
                    type: string
                    description: >
                        Use this to set a hyperlink to the item being edited.
                        
                        This works from version 10.4 onwards.
                where_used:
                    type: string
                    description: >
                        Use this to add some HTML (which can include hyperlinks)
                        on the right of the identifier.
            description: >
                This adds a green box at the top left with the current id.
                
                
                This works from version 7.2 onwards.
        
        last_updated:
            type: string
            description: >
                This adds a bit of text in italics at the top right, just under the tabs.
                
                This works from version 8.6 onwards.
        
        configure:
            type: object
            properties:
                link:
                    type: string
                    description: >
                        A href for the link.
                tooltip:
                    type: string
                    description: >
                        A tooltip for the link.
            description: >
                This adds a link at the bottom left, which will be styled as a cogwheel.
        
        tab:
            type: *stringy
            modified_by_cms: true
            description: >
                The code-name of the current tab that's being displayed.
                
                It defaults to the first tab in the Admin Box, but this can be overridden
                by the developer who opened this Admin Box.
            default: (the first tab of the Admin Box)
        
        switchToTab:
            type: *stringy
            modified_by_cms: true
            description: >
                Set this property to request to switch to another tab in the Admin Box.
                
                If the user clicks on a tab, this property will be set to the code-name of the tab
                they just clicked on.
                
                Note: if there were any validation errors on the current tab,
                the switch will be cancelled and the current tab will be remain in view.
                
                
                This works from version 7.7 onwards.
        
        disable_selecting_tab_from_url:
            type: boolean
            description: >
                This allows you to disable the feature where a FAB can be opened on a specific
                tab by requesting it in the URL.
                
                You would want to do this if you are making a multi-step wizard, and
                want to make sure that users always start on step 1 when the wizard
                is opened.
                
                This works from version 9.0 onwards.
        
        hide_tab_bar:
            type: boolean
            description: >
                If you set this property, the tab bar will not be visible.
                If you only have one tab, you may wish to hide the tab bar to reduce
                clutter and/or to gain a little bit of extra space.
        
        max_height:
            type: integer
            description: >
                Include this property to set a maximum height (in pixels) for the box.
            default: (the height of the screen)
        
        shake:
            type: boolean
            modified_by_cms: true
            description: >
                If there are errors on a tab, Zenario will give the Admin Box a little
                shake when the Admin tries to submit it.
                However if you wish to specifically enable or disable the shaking, you can
                set this property.
                Zenario will clear this property and go back to its default behaviour every time
                the Admin Box is validated and formatted.
        
        css_class:
            type: string
            description: >
                A CSS class name to add to the outer wrapper of the Admin Box.
                
                Defaults to "zenario_fab_default_style" if not set.
        
        save_button_message:
            type: string
            description: >
                The message on the save button.
            default: Save
        
        cancel_button_message:
            type: string
            description: >
                Including this property will add a "cancel" button with the specified message at
                the bottom next to the "save" button.
                Pressing this button is exactly the same as pressing the close button at the top
                right of the box.
        
        error_on_form_message:
            type: string
            description: >
                A message to display at the top of the screen when there is an error
                attached to a specific field on the form.
                
                A generic message will be used if one isn't provided here.
                
                This works from version 8.0 onwards.
        
        save_and_continue_button_message:
            type: string
            description: >
                Including this property will add a "Save and Continue" button to the Admin Box.
                This button acts in the same way as the save button, except that it does
                not close the Admin Box afterwards.
                
                This means that the Admin Box may be saved more than one time, and it also
                means that an Admin Box may start out creating a new thing, but then switch
                to editing an existing thing.
                
                The "Save and Continue" option probably works best when an Admin is
                editing something that already exists. You can enable it when in "Create"
                mode, but you will probably need to reformat the Admin Box when the Admin
                first saves and the thing you are creating is saved in the database.
                
                If the change between creating a new thing and editing an existing thing
                is too drastic, or will cause problems, you should not enable the "Save
                and Continue" option in "Create" mode.
        
        extra_button_html:
            type: string
            description: >
                You can use this property to add some extra html after the save button.
                
                
                This works from version 7.1 onwards.
        
        download:
            type: boolean
            html_description: |
                <p>You can set this for your Admin Box to offer a file download upon completion.</p>
                <p>Setting the <code>download</code> property for an Admin Box will cause Zenario to call your <code>adminBoxDownload()</code> method as well as your <code>saveAdminBox()</code> method when the Admin Box is saved.</p>
                <p>You should handle this request by outputting the appropriate headers and then outputting a file.</p>
                
        
        popout_message:
            type: string
            description: >
                A message to display after saving.
                
                You can use all of the features from https://zenar.io/customising-popout-messages-in-admin-mode
                in order to customise the message.
                
                Note: this will clash with the <code>popout_message</code> property in Organizer;
                you can use one or the other, but not both at the same time.
        
        toast:
            type: object
            description: >
                This will cause the panel to display a "toaster" at the top right when the admin box is displayed,
                or after the admin box is saved.
                
                The toastr library is used;
                you can see https://github.com/CodeSeven/toastr for more information.
            properties:
                message:
                    type: string
                    description: >
                        A message for the toast.
                title:
                    type: string
                    description: >
                        An optional title for the toast.
                
                message_type:
                    enum:
                        - error
                        - warning
                        - info
                        - success
                    default: info
                    description: >
                        The type of message. A different styling will be applied for each different type.
                
                options:
                    additionalProperties:
                        type: *variable
                        description: >
                            Any additional options to pass to the toastr library.
        
        confirm:
            type: object
            dependencies_if_true:
                show:
                    - message
                    - button_message
                    - cancel_button_message
            properties:
                show:
                    type: boolean
                    description: >
                        The confirmation will only be shown if this is set.
                message:
                    type: string
                    description: >
                        A message to show.
                html:
                    type: boolean
                    description: >
                        If this is set, the message will not be html-escaped.
                button_message:
                    type: string
                    description: >
                        A message for the confirm button
                cancel_button_message:
                    type: string
                    description: >
                        A message for the cancel button
                        
                        As of version 8.7 this is optional, and will default to "Cancel"
                        (translated into the local language if translations are enabled) if not set.
                message_type:
                    enum:
                        - none
                        - error
                        - warning
                        - question
                        - success
                    default: none
                    description: >
                        The type of message. A different styling will be applied for each different type.

            description: >
                Use this property to display a confirmation prompt before saving.
                If show is set to true, you must provide the message, button_message and cancel_button_message attributes.
        
        tabs:
            type: object
            description: >
                Admin Boxes are divided up into sections called "Tabs".
                
                Your Admin Box must have at least one tab, but can have multiple tabs.
                
                To place fields on your Admin Box, you must create at least one tab to put them on.
            
            additionalProperties:
                type: object
                properties:
                    ord: *ord
                    copy_of: *copy_of
                    label:
                        type: string
                        description: >
                            A label to display on the tab's link.
                    
                    parent:
                        type: string
                        description: >
                            Enter the code-name of another tab here to make your tab appear
                            under the named tab as a dropdown.
                        
                            There's a limit of 2 levels; you can't have a dropdown inside another dropdown.
                            
                            
                            This works from version 7.3 onwards.
                    
                    in_use:
                        type: boolean
                        description: >
                            The "in use" flagging feature.
                            
                            This is used in combination with the parent propety.
                            If you set it to true, the UI will flag to the admin that there is something set on this tab.
                            If you set it to false, the UI will flag to the admin that there is nothingthing set on this tab.
                            Leave it null/undefined to disable the feature.
                            
                            This works from 9.6 onwards.
                    
                    hidden: *hidden
                    visible_if: *visible_if
                    hide_when_children_are_not_visible:
                        type: boolean
                        description: >
                            If you set this property, the button will be hidden when it has no
                            visible children.
                            
                            
                            This works from version 7.3 onwards.
                    
                    errors:
                        type: object
                        html_description: |
                            <p>You can set errors&nbsp;using your <code>validateAdminBox()</code> method to show that there are errors on a tab.</p>
                            <p>If edit mode is enabled for a tab, an Admin will not be able to leave that tab or save the Admin Box whilst there are errors on that tab.</p>
                            <p>Zenario will automatically initialise the <code>errors</code> property to an empty array each time the tab is validated. This means that any errors from a previous validation will be cleared and must be re-added if the error is still present.</p>
                        additionalProperties:
                            type: string
                            description: >
                                An error message to show.
                    notices:
                        type: object
                        html_description: |
                            <p>Notices display like errors, but do not have any special functionality.&nbsp;If visible, they are displayed one after the other just below the error messages on a tab.</p>
                            <p>Zenario never automatically sets or removes them, and a notice will not stop an Admin from leaving a tab or saving.</p>
                        additionalProperties:
                            type: object
                            required:
                                - type
                            dependencies_if_true:
                                show:
                                    - message
                            properties:
                                show:
                                    type: boolean
                                    description: >
                                        The notice will only be shown if this is set.
                                        
                                        From version 8.4 onwards, you can also use the visible_if property to control whether the notice is displayed,
                                        however the show property must still be set to true otherwise the notice will not display.
                                visible_if: *visible_if
                                message:
                                    type: string
                                    description: >
                                        A message to show.
                                type:
                                    enum:
                                        - error
                                        - warning
                                        - question
                                        - information
                                        - success
                                    description: >
                                        The type of notice. A different styling will be applied for each different type.
                                html:
                                    type: boolean
                                    description: >
                                        If this is set, the message will not be html-escaped.
                    
                    show_errors_after_field:
                        type: string
                        description: >
                            If you don't want the error messages displaying at the top of the tab,
                            you can set the name of a field here to display them below that field.
                            Note: the field after must start on a new line.
                    disable_autofocus:
                        type: boolean
                        description: >
                            When a tab is displayed/redrawn/formatted, Zenario will try to focus on the
                            first field on that tab.
                            This is usually convenient, but can cause problems for tabs with scrollbars
                            as the browser will scroll to show the focused field.
                            You can disable this automatic focusing by setting this property.
                    
                    edit_mode:
                        type: object
                        description: >
                            The edit mode property controls whether the fields on a tab can be edited by an administrator.
                        properties:
                            enabled:
                                type: boolean
                                description: >
                                    Whether this tab can be edited.
                            on:
                                type: boolean
                                modified_by_cms: true
                                description: >
                                    Zenario will automatically set this property when this tab is in edit mode.
                            use_view_and_edit_mode:
                                type: boolean
                                description: >
                                    Set this property if you wish the user to first press an "edit" button
                                    before they can start editing a tab.
                                default: true
                            #enable_revert:
                            #    type: boolean
                            #    description: >
                            #        Include this property to show the "Undo Changes" button when using the
                            #        always_on property.
                            #
                            #        If this property is not defined, then Zenario will automatically enable this
                            #        option if the $box['key']['id'] variable is set.
                            #    default: (intelligent default)
                            format_on_edit:
                                type: boolean
                                description: >
                                    If this property is set, the Admin Box will be submitted to the server and
                                    reformatted if the "Edit" button is pressed.
                            format_on_cancel_edit:
                                type: boolean
                                description: >
                                    If this property is set, the Admin Box will be submitted to the server and
                                    reformatted if the "Cancel" button is pressed.
                            #format_on_revert:
                            #    type: boolean
                            #    description: >
                            #        If this property is set, the Admin Box will be submitted to the server and
                            #        reformatted if the "Revert" button is pressed.
                            validate_on_edit:
                                type: boolean
                                description: >
                                    If this property is set, the Admin Box will be submitted to the server and
                                    validated if the "Edit" button is pressed.
                            validate_on_cancel_edit:
                                type: boolean
                                description: >
                                    If this property is set, the Admin Box will be submitted to the server and
                                    validated if the "Cancel" button is pressed.
                            #validate_on_revert:
                            #    type: boolean
                            #    description: >
                            #        If this property is set, the Admin Box will be submitted to the server and
                            #        validated if the "Revert" button is pressed.
                    
                    
                    # Please see the tuix_form_schema.yaml file for field definitions.
                    # The fields property here will be array_merge_recursive() with the fields property
                    # from tuix_form_schema.yaml by the dev tools when this file is loaded.
                    fields: {}
        
        
        # Please see the tuix_form_schema.yaml file for LoV definitions.
        # The lovs property here will be array_merge_recursive() with the lovs property
        # from tuix_form_schema.yaml by the dev tools when this file is loaded.
        lovs: {}
        
        go_to_url:
            type: string
            description: >
                    This property is used in the installer. If set, the installer will close
                    and navigate to the specified path or URL.
        
        module_class_name:
            type: string
            description: >
                    When defining your module's plugin settings, you will need to set this
                    property in your .yaml file to indicate that the tabs and fields inside this file
                    are only for your module.
        
        setting_group:
            type: string
            description: >
                    When defining your module's site settings, you will need to set this
                    property in your .yaml file to indicate that the tabs and fields inside this file
                    are only for a specific settings group.
        
        missing_items_warning:
            type: string
            description: >
                The form toolkit will not display selected values for checkboxes, radios or select lists
                that are not in the provided LOV.
                
                It will also not save these values.
                
                If you want to enable a warning when this is about to happen, you can enable it by adding
                some text to this property, e.g. "Warning: ID [[items]] missing, save settings to clean up."
                
                This works from version 8.8 onwards.
        
        always_sync_this_data_between_client_and_server:
            type: object
            description: >
                This object, and any child objects and properties, will always be synced between the client
                and the server.
                
                To help make TUIX forms and applications secure, and to make it harder for a developer to
                unwittingly introduce security vulnerabilities in their code, only a few TUIX properties
                that have a specific purpose can be synced between the client and the server.
                
                This object is provided as a free-for-all exception, so anyone making a custom application
                can add anything they need synced in here.
        
        never_sync_this_data_between_client_and_server:
            type: object
            description: >
                This object, and any child objects and properties, will never be synced between the client
                and the server.
                
                This object allows you to send slightly larger data streams from the server to the client,
                on a one-time-only basis.
                
                Anything in here won't be saved in the cache/fabs/ directory, and won't be between the client
                and the server.
                
                This is an exception to how TUIX forms and FABs usually work, where a copy of the TUIX
                sent to the client is kept on the server, and the two are kept in sync.
                
                Any data that is large, or does not need to be kept in sync between the client and the server,
                should be put in here.
                
                This works from version 9.4 onwards.
                
            
                                            
        
