Dev.Module Configuration

Configuration files of Module

config/module.php

This configuration file is the most important file in a module. This file is used to tell user the basic information of the module, It also allow user to decide which configuration files to use. All the configuration data is stored in an array:

return array(
    'meta'  => array(
        'title'         => 'DEMO Sandbox',
        'description'   => 'Examples and tests for developers.',
        'version'       => '1.0.0',
        'license'       => 'New BSD',
        'logo'          => 'image/logo.png',
        'readme'        => 'docs/readme.txt',
        'demo'          => 'http://demo.Pi.org/demo',
        'clonable'      => true,
    ),
    'author'    => array(
        'name'      => 'Taiwen Jiang',
        'email'     => '[email protected]',
        'website'   => 'http://www.Pi.org',
        'credits'   => 'Zend Framework Team; Pi Team; EEFOCUS Team.'
    ),
    'dependency'    => array(
    ),
    'maintenance'   => array(      
        'resource' => array(
            'database'  => array(
                'sqlfile'   => 'sql/mysql.sql',         
                'schema'    => array(
                    'test'          => 'table',
                    'page'          => 'table',
                )
            ),
            'config'    => 'config.php',
            'block'     => 'block.php',
            'bootstrap' => 1,
            'event'     => 'event.php',
            'search'    => array('callback' => array('search', 'index')),
            'page'      => 'page.php',
            'acl'       => 'acl.php',
            'navigation'    => 'navigation.php',
            'route'     => 'route.php',
            'monitor'   => array('callback' => array('monitor', 'index')),
            'test'      => array(
                'config'    => 'For test'
            )
        )
    )
);

This array includes three parts:

Basic module information (described by meta array);
Author information (described by author array);
Configure file needed (described by maintenance array).

meta array - contains several fields to describe basic module information, the name of fields can not be changed.

The title, version and license fields are required;
The description, logo, readme and demo fields are optional;
The clonable field describes whether the module can be installed more times, this field can be ignored if user want to set it to false.

author array - includes fields of name, email, website and credits to describe author information.

The name field is required, and the others are optional.

maintenance array - defines database and configuration files used.

The resource array:

sqlfile field defines the directory of sql file, this file is used to create tables for module;
schema array defines the tables to remove when uninstalls the module. To remember that the key of the array is table name.

Take the code for example, the navigation and route field defines the configuration file name, the configuration data of these files will be fetched when installs the module. Therefore, if you define these field, you should create these files first in your config directory.

The default fields can be: acl, block, config, event, navigation, page and route. We will introduce these configuration files at following sections.

config/block.php

Different blocks can be used to form a page, this configuration file is used to define the interfaces of blocks.

Supposing we want to add two blocks named login and details:

return array(
    // Login block
    'login'    => array(
        'title'         => __('Login'),
        'description'   => __('User login block'),
        'render'        => 'block::login',
        'template'      => 'login',
    ),

    // Details block
    'details'  => array(
        'title'         => __('Details'),
        'description'   => __('Module details'),
        'render'        => 'block::details',
        'template'      => 'details',
    ),
);

In the code, the login and details fields are the block name.

The render field define the method name of block, you can also use array to assign value:

'render'   => array('block', 'login');

The template field define the template to use for this block.

If you want to add configuration information for blocks, you can add a config field in the block array. These configuration data will be stored in database, and allow you to change the configuration data if necessary:

'login'    => array(
    ...
    'template'      => 'block-a',
    'config'        => array(
        // text option
        'first' => array(
            'title'         => 'Your input',
            'description'   => 'The first option for first block',
            'edit'          => 'text',
            'filter'        => 'string',
            'value'         => __('Demo option 1'),
        ),
    ),
),
...

In the code, the edit field decides the form type to modify the configuration data, for example, a text value show that you will change the Your input configuration data in a text form.

config/config.php

Sometimes users want to configure the module and hopes its configuration data will be permanent. This file will helps to realize this function, it will store the configuration data in the system config table. This configuration file achieves the following tasks:

Defining the forms to display for user to change its configuration data.
Setting the default configuration data.
Setting the configuration categories.

The codes in this file are:

return array(
    'category'  => array(
        array(
            'title' => 'General',
            'name'  => 'general',
        ),
        array(
            'title' => 'Test',
            'name'  => 'test'
        ),
    ),

    'item'     => array(
        'test'  => array(
            'category'      => 'test',
            'title'         => 'Test Conf',
            'description'   => 'An example for configuration.',
            'value'         => 'Configuration text for testing',
            'visible'       => 0,
        ),
        'add'   => array(
            'category'      => 'general',
            'title'         => 'Add Item',
            'description'   => 'An example for adding configuration.',
            'edit'          => array(
                'attributes'    => array(
                    'type'      => 'select',
                    'multiple'  => true,
                    'options'   => array(
                        1   => 'One',
                        2   => 'Two',
                        3   => 'Three',
                    ),
                ),
            ),
            'filter'        => 'array',
            'value'         => array(1, 2),
        )
    )
);

These codes mainly contain two part: category and item.

category array - defines the categories of the configuration data for configure editing or displaying, it use name and title to describe;
name field - defines the category name, and the title field mainly used to describe this category.

The item array decides the configuration data name, category and forms to display the configuration.

test and add fields - the configuration name;
value field - defines the default value of this configuration;
edit field - describes the forms to display for modifying configuration data, if this field is not set, a text form will be used as default. You can also sets the filter field to filter data before insert it into table;
visible field - describes the visualization of the configuration form, this parameter is optional, the form will no display on configuration board if it is set to 0.

config/navigation.php

We can find that a site generally contains navigation, it will help user to find a page quickly. This configuration file is used to define the navigation of front-end and admin-end for a module. You should only set some attributes and the application will generate navigation automatically.

The define codes are:

return array(
    'front'   => array(
        'pagea'     => array(
            'label'         => __('No template'),
            'route'         => 'default',
            'controller'    => 'index',
            'action'        => 'index',
            'visible'       => 0,
            'params'        => array(
                'test'   => '1',
        ),
    ),
);

front field - tells that there will generate a front-end navigation;
label field - tells what to display on the navigation;
route field - tells the router type of a URL;
controller and action fields - tell which action to access;
visible - tells whether to hide a navigation, the navigation will be hide if it set to 0;
params field - defines the parameters to post by query strings, this field can be ignored if you do not want to post query string.

If you want a admin-end navigation, just add a same array and change the front field into admin and assign the admin value to route field:

return array(
    'front'   => array(
        ...
    ),

    'admin'   => array(
        'pagea'     => array(
            'label'         => __('No template'),
            'route'         => 'admin',
            'controller'    => 'index',
            'action'        => 'index',
        ),
    ),
);

Perhaps you want to add a sub navigation under pagea, it is possible to add a pages array in the pagea field:

'pagea'      => array(
    'label'     => __('No template'),

    'pages'     => array(
        'pageaa'     => array(
            'label'      => __('List'),
            'route'      => 'admin',
            'controller' => 'index',
            'action'     => 'index',
        ),

        'pageab'     => array(
            'label'      => __('Search'),
            'route'      => 'admin',
            'controller' => 'index',
            'action'     => 'search',
        ),
    ),
),

Continuing add this codes if you want to add more sub navigation.

Pi provides users another way to generate navigation, which is callback field.

'front'   => array(
    'pagea'      => array(
        'label'      => __('Test 3'),
        'uri'        => '',
        'callback'   => array('navigation', 'admin'),                     
    )
);

In which, the navigation is the class name, and the admin is the method name. Users can also assign the method's namespace to the callback.

'callback'   => 'Module\\System\\Navigation::admin',

If users use callback to generate the navigation, a related callback method is needed absolutely. Take the code above for example, users should create a Module\System\Navigation class and then add a admin method for it:

namespace Module\System;

use Pi;

class Navigation
{
    public static function admin($module)
    {
    }
}

In the admin method, users should create an array for generating navigation.

public static function admin($module)
{
    $nav = array(
        'pages'   => array(),
    );

    $modules = Pi::service('registry')->modulelist->read('active');
    unset($modules['system']);
    foreach ($modules as $key => $data) {
        $nav['pages'][$key] = array(
            'label'     => $data['title'],
            'module'    => $key,
            'route'     => 'admin',
        );
    }

    return $nav;
}

The code above will create a sub navigation for pagea, such as:

'front'    => array(
    'pagea'    => array(
        'pages'   => array(
            'page1'   => array(...),
            'page2'   => array(...),
            ...
        ),
    ),
),

If users want to change the navigation struture, the follow code can be used.

$nav = array(
    'parent'    => array(
        'pageaa'    => array(...),
        'pageab'    => array(...),
        ...
    ),
);

This array is used to create a parent navigation, the page pagea' will be replaced with pageaaandpageab`.

Such as:

'front'   => array(
    'pageaa'   => array(...),
    'pageab'   => array(...),
    ...
),



$nav = array(
    'parent' => array(
        'position'    => 'after',
        'pages'       => array(
            'pageaa' => array(...),
            'pageab' => array(...),
            ...
        ),
    ),
);

In this code, the position field is used to specified that inserting the pageaa and pageab after pagea as parent.

Such as:

'front'   => array(
    'pagea'    => array(...),
    'pageaa'   => array(...),
    'pageab'   => array(...),
    ...
),

config/page.php

This configuration file is used to operate with page, it achieves the following tasks:

Setting the page cache time and cache level;
Deciding whether allows users to operate with blocks;
Creating the page's accessing controller list.

return array( // Front section 'front' => array( array( 'cache_ttl' => 0, 'cache_level' => 'locale', 'title' => __('Module homepage'), 'controller' => 'index', 'action' => 'index', 'block' => 1, 'access' => array( 'guest' => 0, 'member' => 1, ), 'parent' => array( 'name' => 'public', 'module' => 'system', ), ... ), );

In this configuration data:

front field - indicates the section to which the pages belong, it also can be admin and feed;
cache_ttl field - uses to set the cache time, and the cache_level fields is used to set the cache level;
controller, action and title fields - describe a special resource and its name;
block field - decides whether the page allows users to add or remove blocks, if it is not set or set to 0, it will find is parent page to decide whether the user could dress up the page, or else, the page is allowed to operate with blocks.

The access array is used to decide roles' permission for a special page:

guest and member fields - roles, their value define their permission; If this array is not set, both guset and memeber will have permission to access for pages in front section, and the guest will be set to 0, and member will be set to 1 for pages in admin section.

The parent field tells which category the resource is belong to, the example above tells that the 'Module homepage' resource is a child of a resource named public in system module. This field also can use string to describe, if you do this, its parent resource is current module and has a name as parent field set.

You can use the following code to disable pages:

return false;

It also allows users to disable sections:

return array(
    'front'     => array(
    ),
    'admin'     => false,
);

config/route.php

As we know, general we create a file for a page to display, then we can request the page by / character, in Pi, a page is created by an action method, Pi provides us a route such as domain/module/controller/action to request pages, but it also allows us to define ourselves router.

This configuration file is used to define router, then you can use it in url() method:

return array(
    'default'   => array(
        'section'   => 'front',
        'priority'  => -999,

        'type'      => 'Standard',
        'options'   =>array(
            'structure_delimiter'   => '/',
            'param_delimiter'       => '/',
            'key_value_delimiter'   => '-',
            'defaults'              => array(
                'module'        => 'system',
                'controller'    => 'index',
                'action'        => 'index',
            )
        )
    ),
);

In this code, the default field is the route name:

section - decides which section's action to request, it can be front, admin and feed;
priority field - defines the priority of the url resolving, the smaller digit the lower priority, generally we recommend set lower priority to the common router.

The type field defines which class is used to resolve the url, there has three types recommend, which are: Standard, Home and User.

The options array defines how to display the url:

defaults array - describes the default action to request if there is not set the controller and action field in navigation file.

For example:

$this->url('default' array());
$this->url('default', array('module' => 'user', 'controller' => 'login', 'action' => 'reset', 'params' => '1233'));
$this->url('', array('module' => 'user', 'controller' => 'login', 'action' => 'reset', 'params' => '1233'));

Output:

'/Pi/www/'
'/Pi/www/user/login/reset/params-1233'
'/Pi/www/user/login/reset/params-1233'

In the first output, the module is system, and both the controller and action is index, this default set is ignored. If you only return a null array in navigation.php, it will request the action as defaults array set, which will be:

'/Pi/www/user/'

The user is module name, and the controller index and action index can be ignored.

Now let's change the options array to:

'structure_delimiter'   => '/',
'param_delimiter'       => '-',
'key_value_delimiter'   => '=',
'defaults'              => array(
    ...
),

The output of first example will be:

'/Pi/www/user/login/reset-params=1233'

NOTE: the character ?, @ is predefine, it can not be used as a delimiter.

It allows you to define another router, such as admin router, which is used to request actions in admin section:

'admin' => array(
    'section'   => 'admin',
    'priority'  => 100,

    'type'      => 'Standard',
    'options'   => array(
        'route'     => '/admin',
        'defaults'  => array(
            'module'        => 'system',
            'controller'    => 'index',
            'action'        => 'index'
        )
    ),
),

You may find that the section field here is set to admin, it tell application to request controllers and actions in admin section. You may also find that we have added a route field in options array, this will change the url displayed.

For example:

echo $this->url('admin', array('module' => 'user', 'controller' => 'login', 'action' => 'reset'));

Output:

'/Pi/www/admin/user/login/reset/'

Provide feedback

Saved searches

Use saved searches to filter your results more quickly