---

top_level_page: ref_of_properties
pages:
    -content_types
    -inheritance
    -jobs
    -signals
    -special_pages

common_definitions:
    stringy: &stringy
        - number
        - string
    variable: &variable
        - boolean
        - number
        - string

$schema: 'http://json-schema.org/draft-04/schema#'

type: object
required:
    - display_name
    - description
properties:
    display_name:
        type: string
        default: "(Your module's class name)"
        description: >
            The display name of the module, which will be shown to administrators.
    required_cms_version:
        type: string
        default: "(The current version of the CMS)"
        description: >
            The version number of the CMS that your module requires to run, e.g. 7.0.0
    author_name:
        type: string
        description: >
            Your name or your company's name.
    copyright_info:
        type: string
        description: >
            Any copyright information.
    license_info:
        type: string
        description: >
            The name of the license you are using, e.g. Modified BSD License
        
            If you wish to release your module under more than one license, you can
            enter multiple names separated by a comma.
    keywords:
        type: string
        description: >
            A comma-separated list of keywords that an administrator can search for in the modules
            panel in organizer.
    is_pluggable:
        type: boolean
        description: >
            If your module is pluggable then you should set this property.
            A module that is pluggable can generate plugins.
    plugin_must_be_on_public_page:
        type: boolean
        description: >
            If your module is pluggable, and your plugins need to be on a public page, then set this property.
    plugin_must_be_on_private_page:
        type: boolean
        description: >
            If your module is pluggable, and your plugins need to be on a private page, then set this property.
    is_abstract:
        type: boolean
        description: >
            If you set this property, your module will always be running if it is present in the filesystem,
            but it cannot be suspended and it will not appear in Organizer.
            
            You can use this from version 7.2 onwards.
    start_running_on_install:
        type: boolean
        description: >
            If you set this property, the module will be flagged as running and installed if it is present in
            the filesystem when the Zenario installer is run, or the site is reset.
            
            Note: this is not a very smart feature and won't check for any dependancies your module has.
            If your module does have dependancies, you should also ensure that they are present in the
            filesystem and also have the start_running_on_install set.
    for_use_in_twig:
        type: boolean
        description: >
            If you set this property, your module will be loaded every time a Twig framework is generated,
            and designers will be able to call your public methods from their Twig frameworks.
            
            Note: this will make all of your public methods available.
            If you want to make an exception, e.g. your saveAdminBox() or handleOrganizerPanelAJAX() methods,
            then you may add
                if (cms_core::$isTwig) return;
            at the top of the function body to prevent it from being called.
            
            You can use this from version 7.3 onwards.
    fill_organizer_nav:
        type: boolean
        description: >
            If you set this property, Organizer will call your module's fillOrganizerNav() method
            when loading Organizer.
            
            If you don't have any navigation, or you have navigation but don't want to modify it
            in PHP, you should set this to false for a faster load time.
        
            If you don't specify this property, or don't write a <code>description.yaml</code> file for your
            module, then the CMS will take an intelligent guess based on whether you have
            the <code>fillOrganizerNav()</code> function in your module_code.php.
            
            You can use this from version 7.2 onwards.
    default_instance_name:
        type: string
        default: "(Your module's class name)"
        description: >
            The default name for an instance of your module, required for pluggable
            modules.
    can_be_version_controlled:
        type: boolean
        description: >
            If your module is pluggable, setting this property will allow it to generate
            version-controlled  plugins.
            (If you don't set this property, it will only be able to generate library
            plugins.)
    nestable:
        type: boolean
        description: >
            If your module is pluggable, setting this property will allow its plugins to be
            inserted in a nest.
        
            (Most modules can, but if you find that your module is unstable when nested,
             or if your module uses the <code>showInFloatingBox()</code> init function,
             or nesting is just counterintuitive to what your module does,
             then you should not set this property.)
    nestable_only:
        type: boolean
        description: >
            Set this property if the plugins from your module should ONLY work when in a nest.
            
            You can use this from version 7.3 onwards.
    vlp_class_name:
        type: string
        default: "(Your module's class name)"
        description: >
            If your module is pluggable, you should provide a class name to use for
            phrases.
            This should usually be the same as your module's directory/class name, however you can
            set it to the <code>vlp_class_name</code> of another module to use that module's phrases.
    css_class_name:
        type: string
        default: "(Your module's class name)"
        description: >
            If your module is pluggable, you should provide a class name to use for
            styles.
            This should usually be the same as your module's class name, however you can
            set it to the class name of another module to use that module's styles.
    default_framework:
        type: string
        description: >
            The directory-name of the default framework for your module.
            
            Required for pluggable modules.
    category:
        enum:
            - custom
            - core
            - content_type
            - management
            - pluggable
        description: >
            The category your module fits into, used to sort modules into seperate organizer panels.
            
            <code>custom</code> - All modules in zenario_custom/modules/
            
            <code>core</code> - Core features modules, such as zenario_common_features
            
            <code>content_type</code> - A module that creates a new content type such as zenario_ctype_event
            
            <code>management</code> - A module that adds management into organizer
            
            <code>pluggable</code> - A module that has a front end plugin
            
            Modules that add both management and a plugin should be added to the management category.

    dependencies:
        type: object
        additionalProperties:
            type: boolean
        description: >
            An array of modules that your module depends on.
            Note: the names of the modules must be stored in the keys, not the values.

    inheritance:
        type: object
        properties:
            inherit_frameworks_from_module:
                type: string
                description: >
                    If you enter the class name of a module here, any Frameworks available to
                    plugins of that module will also be available to plugins of your module.
        
                    In the event of any name clashes the frameworks in your module will be used
                    in preference.
        
                    You may only specify one module to inherit Frameworks from, but this
                    inheritance can be chained; i.e. if you inherit Frameworks from a module that
                    itself inherits Frameworks from a third module, plugins of your module can use
                    the combination of Frameworks from all three modules.
            
            include_javascript_from_module:
                type: string
                description: >
                    If you enter the class name of a module here, any JavaScript functions
                    defined for plugins in that module will also be available for your plugins
                    to call on.
        
                    Be aware that their encapsulated name does not change; i.e. if you write
                    my_module_b which extends my_module_a, then include JavaScript from
                    my_module_a in my_module_b, the syntax for these functions will still be:
                        <code>my_module_a.functionNameFromModuleA();</code>
                    and not:
                        <code>my_module_b.functionNameFromModuleA();</code>
            
            inherit_settings_from_module:
                type: string
                description: >
                    If you enter the class name of a module here, any Plugin Settings defined
                    for that module will be automatically made available to plugins of your
                    module.
                    However you still have the power to add additional Settings of your own,
                    or to hide or otherwise alter the predefined Settings.
        
                    Note: the <code>fillAdminBox()</code>, <code>formatAdminBox()</code>, <code>validateAdminBox()</code> and
                    <code>saveAdminBox()</code> methods of the module you specify here are still called. If you
                    wish to hide any predefined fields or tabs you should do so by setting the
                    <code>hidden</code> property, rather than trying to use <code>unset()</code> which may cause PHP notices and
                    unintended functionality in the original module's code.
        
                    You may only specify one module to inherit Settings from, but this
                    inheritance can be chained; i.e. if you inherit Settings from a module that
                    itself inherits Settings from a third module, you are effectively inheriting
                    Settings from all three modules.
    
    signals:
        type: object
        additionalProperties:
            type: object
            required:
                - name
            properties:
                name:
                    type: string
                    description: >
                        The name of a signal that this module listens for
                static:
                    type: boolean
                    description: >
                        Whether your method is static.
                        Using static methods is recommended, as it is slightly more efficient.
                suppresses_module_class_name:
                    type: string
                    description: >
                        This property allows you to handle a signal in place of a different module.
    
    background_tasks:
        type: object
        additionalProperties:
            type: object
            required:
                - name
            properties:
                name:
                    type: string
                    description: >
                        A code-name for this task. Will also be visible to admins in Organizer.
                script_path:
                    type: string
                    description: >
                        The path to the background script you wish to run.
                        
                        The CMS root directory will automatically be added to the start, and anything you
                        type will be automatically shell-escaped.
    
    jobs:
        type: object
        additionalProperties:
            type: object
            required:
                - name
            properties:
                name:
                    type: string
                    description: >
                        A method in your module that should be called for this job.
                        This is also visible to Admins, and is used for the name of this job.
                static:
                    type: boolean
                    description: >
                        Whether your method is static.
                        Using static methods is recommended, as it is slightly more efficient.
                
                manager_class_name:
                    type: string
                    default: zenario_scheduled_task_manager
                    description: >
                        The class name of the module that you wish to manage this Job, for example
                        the zenario_scheduled_task_manager module or the
                        zenario_incoming_email_manager module.
            
                        If you let the zenario_scheduled_task_manager module manage your job, then
                        your method will be called periodically.
                        If you let the zenario_incoming_email_manager module manage your job, then
                        your method will be called when an email is received.
        
                #If your job is a Scheduled Task, you should set default values for the
                #frequency at which it will be called using the following properties:
                months:
                    type: string
                    description: >
                        A comma-sparated list of months in the year this job should run on.
                        E.g. jan,feb,mar,apr,may,jun,jul,aug,sep,oct,nov,dec
                
                days:
                    type: string
                    description: >
                        A comma-sparated list of the week this job should run on.
                        E.g. mon,tue,wed,thr,fri,sat,sun
                
                hours:
                    type: string
                    description: >
                        A comma-sparated list of the hours this job should run on.
                        E.g. 0h,12h for midnight and midday.
                
                minutes:
                    type: string
                    description: >
                        A comma-sparated list of hours this job should run on.
                        E.g. 0m,20m,40m for every 20 minutes.
                
                first_n_days_of_month:
                    type: number
                    default: '0 (off)'
                    description: >
                        Only run on the first n days of the month.
            
                        Alternately you may enter a negative number to
                        only run on the first n days of the month.
            
                        Defaults to 0, which turns this option off.
                
                log_on_action:
                    type: boolean
                    description: >
                        Whether to add a log entry if this job does something.
                
                log_on_no_action:
                    type: boolean
                    description: >
                        Whether to add a log entry if this job does nothing.
                
                email_on_action:
                    type: boolean
                    description: >
                        Whether to send an email if this job does something.
                
                enabled_by_default:
                    type: boolean
                    description: >
                        If set to true, this job will be running by default without an admin needing to press the "Enable Task" button.
                        
                        (Note: the crontab still needs to be set and the master switch still needs to be enabled.)
                        
                        This works from version 8.6 onwards.
    
    content_types:
        type: object
        additionalProperties:
            type: object
            required:
                - content_type_id
                - content_type_name_en
                - default_template_name
            properties:
                content_type_id:
                    type: string
                    description: >
                        The id of the Content Type, e.g. html, news, document.
                        Must be unique on a site.
                        Can only be made up of the letters a-z in lowercase.
                content_type_name_en:
                    type: string
                    description: >
                        An English name for the content type, e.g. "Web page".
                        This will be shown to administrators.
                content_type_plural_en:
                    type: string
                    description: >
                        A plural name, e.g. "Web pages". Defaults to content_type_name_en if not set. 
                        This will be shown to administrators.
                        
                        This works from version 7.2 onwards.
                default_template_name:
                    type: string
                    description: >
                        The CMS will automatically create a new layout for your content type when
                        it is installed on a site, with this name.
                        
                        If your module has the <code>is_pluggable</code> property set, a library plugin
                        from your module will be placed on this layout.
                enable_summary_auto_update:
                    type: boolean
                    description: >
                        Whether to prompt an Admin to update a Content Item's Summary when they are
                        editing a Content Item.
            
                        This will be the default value; it can be overwritten on a per site basis
                        by changing it in the Content Type settings.
                enable_categories:
                    type: boolean
                    description: >
                        Whether to support categories for this content type. Defaults to false.
                        
                        Categories functionality will be hidden for content items on this type if not enabled.
                description_field:
                    enum:
                        - optional
                        - mandatory
                        - hidden
                    default: optional
                    description: >
                        Whether to show the description field to Admins.
            
                        This will be the default value; it can be overwritten on a per site basis by changing it in the Content Type settings.
                keywords_field:
                    enum:
                        - optional
                        - mandatory
                        - hidden
                    default: optional
                    description: >
                        Whether to show the keywords field to Admins.
            
                        This will be the default value; it can be overwritten on a per site basis
                        by changing it in the Content Type settings.
                summary_field:
                    enum:
                        - optional
                        - mandatory
                        - hidden
                    default: optional
                    description: >
                        Whether to show the summary field to Admins.
            
                        This will be the default value; it can be overwritten on a per site basis
                        by changing it in the Content Type settings.
                release_date_field:
                    enum:
                        - optional
                        - mandatory
                        - hidden
                    default: optional
                    description: >
                        Whether to show the release date field to Admins.
            
                        This will be the default value; it can be overwritten on a per site basis
                        by changing it in the Content Type settings.
                writer_field:
                    enum:
                        - optional
                        - mandatory
                        - hidden
                    default: optional
                    description: >
                        Whether to show the writer field to Admins.
            
                        This will be the default value; it can be overwritten on a per site basis
                        by changing it in the Content Type settings.
    
    special_pages:
        type: object
        additionalProperties:
            type: object
            required:
                - page_type
                - default_alias
                - default_title
            properties:
                page_type:
                    type: string
                    description: >
                        A code name for this special page.
                        Should be prefixed with your name or company name to avoid any clashes with
                        other Plugin Developers.
                default_alias:
                    type: boolean
                    description: >
                        An alias to give this page by default.
                default_title:
                    type: string
                    description: >
                        A title to give this page by default.
                default_content:
                    type: string
                    description: >
                        If your module does not have the <code>is_pluggable</code> property set, this property will
                        place a WYSIWYG Editor on the page upon creation with the
                        specified content.
            
                        If your module does have the <code>is_pluggable</code> property set, this property will be
                        ignored and a library plugin from your module will be placed on the page
                        instead.
                
                menu_title:
                    type: string
                    description: >
                        You can set this property to automatically create a Menu Node with the specified
                        title.
                footer_menu_title:
                    type: string
                    description: >
                        You can set this property to automatically create a Footer-Menu Node with the
                        specified title.
                menu_rel_tag:
                    type: string
                    description: >
                        This property lets you set a Rel-Tag on the Menu Node(s) created by the
                        <code>menu_title</code> or <code>footer_menu_title</code> properties.
                        E.g. for the search page, the rel tag would be "search".
                only_show_to_visitors_who_are_logged_in:
                    type: boolean
                    description: >
                        This lets you set the created Menu Nodes to only be for logged in Extranet
                        Users by default.
                only_show_to_visitors_who_are_logged_out:
                    type: boolean
                    description: >
                        This lets you set the created Menu Nodes to only be for logged out visitors
                        by default.
                
                layout:
                    type: string
                    description: >
                        The name of a layout to use for the created page.
                        (If you do not set a name, or the name is not found, then the default html layout will be used.)
                
                logic:
                    enum:
                        - create_and_maintain_in_default_language
                        - create_in_default_language_on_install
                    default: create_and_maintain_in_default_language
                    description: >
                        The logic that should be followed for this special page.
                        
                        create_and_maintain_in_default_language:
                            A special page will only be created in the first or the default Language of a site.
                        
                        create_in_default_language_on_install:
                            A normal page will be created if this module is running on the first install of the site.
                            This page will not be flagged as "special", can't be found using the langSpecialPage() function,
                            and can be deleted by an administrator.
                allow_hide:
                    type: boolean
                    description: >
                        If you set this property to true, admins will be allowed to hide the special pages
                        (effectively taking them offline without a warning).
                        
                        Set this if your module uses special pages, but they are supposed to be optional.
                
                allow_search:
                    type: boolean
                    description: >
                        If you set this property to true, search modules will not exclude this special page
                        from search results. The Privacy Policy special page is searchable by default.
                
                must_be_listed:
                    type: boolean
                    description: >
                        Set this property to true to stop admins from making this special page unlisted.
                        
                        This works from version 9.6 onwards.
                
                must_be_unlisted:
                    type: boolean
                    description: >
                        Set this property to true to stop admins from making this special page listed.
                        
                        This works from version 9.6 onwards.
                
                publish:
                    type: boolean
                    description: >
                        If this property is set, the Special Page will be published by default.
                        If you feel that you can make your Special Page look presentable using just
                        the options here, you may wish it to be published straight away to reduce
                        the amount of setup that an Administrator needs to perform.
    centralised_lists:
        type: object
        additionalProperties:
            type: object
            required:
                - method_name
                - label
            properties:
                method_name:
                    type: string
                    description: >
                        The name of the static method that returns the list of values.
                label:
                    type: string
                    description: >
                        The label of the centralised list.
        description: >
            If your module provides a centralised list, or multiple centralised lists, you will need to specify a label
            and the method name for each here.
    
    path_commands:
        type: object
        description: >
            For plugins that are designed to work with the nest conductor, you should define a list
            of commands/modes that your plugin issues.
            
            This list is used to pre-populate the list of values used when creating a path in the conductor.
            
            When creating a path, the command is the name of the mode that the path is going TO.
        additionalProperties:
            type: object
            required:
                - label
            properties:
                label:
                    type: string
                    description: >
                        Some descriptive text for the command.
                modes:
                    type: array
                    description: >
                        A list of modes of your plugin that this command can be used in.
                        
                        When creating a path, this list is the name of the modes that the path can go FROM.
                        
                        If not specified, the CMS will assume that it can be used from mode,
                        or that your plugin does not use different modes.
                
                request_vars:
                    type: object
                    description: >
                        For plugins that are designed to work with the nest conductor, and need/use certain variables
                        in the request, you should define a list of these variables.
            
                        You should define them on a mode-by-mode basis - i.e. this should be an array of arrays.
            
                        You will need to increment your plugin's revision number if you make a change to the vars here.
                    additionalProperties:
                        type: string
                        description: >
                            A name of a request variable.
                
                hierarchical_var:
                    type: string
                    description: >
                        If your command is hierarchical (i.e. it can be repeated through many levels of hierarchical),
                        you should specify the variable that is used for this in this property (e.g. dataPoolId).
            
                        You will need to increment your plugin's revision number if you make a change to this property.
                
                able_to_generate_smart_breadcrumbs:
                    type: boolean
                    description: >
                        Set this if your plugin is able to generate smart-breadcrumbs in this mode.
            
                        You will need to increment your plugin's revision number if you make a change to this property.
                
                hidden:
                    type: boolean
                    description: >
                        You can set this property if you wish to hide an option from the picker,
                        but still define options for it if someone manually types it.
