This is a draft that I make a few weeks ago. I will update it as the work is being done.
Drupal administration tasks are currently performed using Drupal Form API through a web interface. To ease the task of administrating Drupal sites as well as to provide a graphical administration console we need to build an API for getting/setting Drupal settings.
The current Drupal Form API is a very briliant idea. And I think it's a good starting point to implement Drupal Configuration API. But since the Form API is quite HTML-specific and have some strange behaviours, there must be some adaption and may be some hacks to get the system works consistently without touching the core. But at first, I shall describe the new system.
Configuration system will be organized into Modules, Config Pages & Config Items. Each drupal site will have a list of modules (that provides remote configuration service). Each modules contains one or more config pages (configuration page), each config page contains several config items. Config pages and config items can be nested, but not modules. A config item can not contain a config page and a config page or config item cannot contain a module. In this way, the whole drupal site configuration system will be organized in to a single rooted tree which is very similar to a Windows filesystem with Drives, Directories and Files.
- Module – Module that provide remote configuration service. It is the container for the whole configuration system provided by that module. A module may have some attributes associated with that module (ex. Modules names, versions, etc…)
- Config Page – A configuration page is the container for configuration items. It have many similarity to Drupal Forms and may be rendered in different ways to represent and collect data.
- Config Item – A configuration item is basically a form element. It contains information to render an input element as well as the datatype for that item. A config item may be editable or readonly.
There are tree basic actions that can be performed on this tree. (1) List sub items (sub pages, config items) of a config tree node, (2) read values of items and (3)write values. We can combine action (1) and (2) together to form a new action : get both configuration structures and values at once. So we have only two basic actions :
- Get configuration structures and data
- Set configuration values
Config page is the basic unit to get/set data. This maybe a weird method to deal with a tree but it have some advantages:
- It helps maintain compatibility with Form API.
- It keeps module developers from having to manage individual config items. All they have to implement is a form (which is basically a “strict” Drupal Form) and how data submitted by that form is saved.
- It may help reduce the number of xmlrpc calls (in some cases) and should not increase the update overhead (most of the updates only required one SQL call).
- It will provide better support for batch update.
That’s a glance of how this system will work. Let’s get into some details:
Specification
Path
A configuration path is an dot separated string. Ex. “system.admin.general.site_name”
Entities
A config entity (or node) is a node on the configuration tree. It may contain config items and attributes. Below is the list of supported attributes and their purpose:
- #type : the type of the current entity.
- #subpages : mapped array between config subpage’s name and its content.
- #datatype : type of input data, used for data conversion.
- #callback : page callback to get (merge) array of page content.
- #submit_callback : callback to submit page data. If this attribute is skipped, function name $page[‘#callback’] . “_submit” will be used instead.
- #supported_actions : array of actions supported by page’s callback_submit function.
- #access : indicate whether use have access right to a node. If user is denied to access a node then that user will be denied to access to all sub nodes. (Should we add another flag for writing privilege ?)
How these attributes are applied to each config entity type :
Module
- #type = ‘_module’
- #subpages
- #name | #title (module’s friendly name)
- #version (may be the module’s Config API version here :)
- #access
Config Page
- #type = ‘_page’
- #subpages
- #callback
- #supported_actions
- #submit_callback
- #access
Config Item
- #type : Any Form API’s type and “undefined”
- #datatype
XML-RPC API
These are XML-RPC method used to deal with the configuration tree.
- remoteconfig.traverseConfigTree(path, include_items)
Traverse to a config tree node and get child data of that node. If the flag include_items is set to false, only traverse on config pages (skip config items).
- remoteconfig.getConfigPageContent(path)
Get content of a config page. This is just a shortcut of above function with include_items set to false. (May useful for explorer likes interface. With one pane is the tree of modules, pages and the other pane is page’s content – may be rendered like a form)
- remoteconfig.getConfigModules()
Get the list of modules support configuration services.
- remoteconfig.submitConfigPage(path, data, action)
Submit a config page’s data
- remoteconfig.submitConfigTree(path, data, action)
Batch submit a (part of) configuration tree.
Modules development notes
- To support remote configuration service a module must implement “hook_remoteconfig”. This hook will return an (nested) array of config pages. Each config page must have correspondence callback function and an optional callback_submit function. The hook_remoteconfig receive no parameter.
- Each config page implemented by the module must have an associated callback function. This callback function will return an array of what’s in that page. That may be attributes, config items, subpages, etc … Page callback functions must accept two parameters : callback($path, $include_items).
- $path – is an array contains relative path (splitted by dot) from callback’s node point of view. Notice that the path must include the current node.
- $include_items – specify that is page’s config items are required
- Each page must also have a corresponding callback_submit function in order to save data. Page submit callback functions must accept three parameters: callback_submit($path, $data, $action).
- $path – array contain relative path of page/item to be submitted.
- $data – data struct.
- $action – action to performed