Concept: Architectural standard

A experimental document on an architectural standard.

Overview of Drupal concepts

Project

TODO

Namespace

TODO

Core

TODO

(Installation) profile

TODO

Module

A module is a project and extends, builds or enhances Drupal core functionality.

Theme

TODO

Theme engine

TODO

Translation

TODO

Library ^experimental

TODO

API ^experimental

TODO

Shared namespace ^experimental

TODO

Namespace

^[namespace]

In general, a namespace is an abstract container providing context for the items (names, or technical terms, or words) it holds and allowing disambiguation of homonym items having the same name (residing in different namespaces).

The implementor of a namespace may give directions/guidelines/restrictions on how to use sub-namespaces. For example, the theme namespace may only be used for themables.

By default namespaces may only be filled by its implementor. The implementor however could allow others to add to the namespace. The theme namespace for example may be used by modules.

Project

^{[project] implements [namespace]}

To prevent name collisions projects SHOULD BE registered at drupal.org.

Core

^{[core] implements [project]}

Directory structure:

includes/
  [api].inc
libraries/
  [library]*
modules/
  [module]*
profiles/
  [profile]*
sites/
  all/
    libraries/
    modules/
    themes/
  default/
themes/
  [theme]/

Profile

^{[profile] implements [project]}

Module

^{[module] implements [project]}

A [module] that doesn't implement [api], only contains [hook implementation]s and [helper function]s.

includes/ (optional)
  [api].inc
libraries/ (optional/discouraged)
  [library]/
modules/ (optional)
  [module]/
{module:name}.info
{module:name}.module
{module:name}.install

To prevent running out of descriptive module names, themes should use
nondescriptive humanlike names.

Theme

^{[theme] implements [project]}

To prevent running out of descriptive module names, themes should use
nondescriptive humanlike names.

Theme engine

^{[theme_engine] implements [project]}

Translation

^{[translation] implements [project]}

Library ^experimental

^{[library] implements [project]}

http://drupal.org/project/libraries

Examples of libraries are javascript libraries as jQuery, swfobject and tinymce, css frameworks as 960, blueprint, but also php libraries like the PEAR library.

API ^experimental

^{[api] implements [project]}

API's MAY BE defined by [core] and [module]s

API names SHOULD BE registered as a project on drupal.org to prevent collisions.

This means that also core API's should be registered as a drupal project.

Module may use their own name as an API.

{api:name}.inc
{api:name}.{subapi:name}.inc

Shared namespace ^experimental

^{[shared namespace] implements [project]}

[shared namespace]s MAY BE defined by [core] and [api]s

[shared namespace]s MUST NOT implement hooks.

[project]s that implement a [shared namespace] MAY implement an [api], but may not contain [hook]s.

[shared namespace]s SHOULD BE registered as a project on drupal.org to prevent collisions.

This means that also core's [shared namespace]s should be registered as a drupal project.

When a module needs to implement a [shared namespace], it should implement an api.

{api:name}.inc
{api:name}.{subapi:name}.inc

Site

^[site]

modules/
libraries/
themes/
settings.php

Project File^experimental

^{[project file]}

Any file in projects.

Project Info File^experimental

^{[project info file] implements [project file]}

Every project must have an info file.

Function ^experimental

^[function]

Drupal programming from an object-oriented perspective
Change the hook separator from '' to '_hook'
Register all core modules/APIs on drupal.org

Any function defined in [project]s should comply to one of the following types:

• [api function]
• [helper function]
• [hook implementation]
• [routine]

Function name collisions

For example, hook__node_access_grants() may be defined by:

• node.api
• node_access.api
• node_access_grants.api

API function

^{[api function] implements [function]}

{api function}

{api}(_[a-z][_a-z0-9]*)?

[api function]s can only be defined by [api]s. Note: a [module] can be an [api].

Examples of api functions:

• theme
• module_invoke
• node_load

Helper function

^{[helper function] implements [function]}

A helper function is a [function] that performs part of the computation of another function. Helper functions are used to make your project easier to read by giving descriptive names to computations. They also let you reuse computations, just as with functions in general.

{helper function}

_{project}_([a-z][_a-z0-9]*)

Helper functions may be defined by all [project]s. Helper functions should be used only by the project that defined it.

Hook

^{[hook] implements [api function]}

{hook}

{api}(_[a-z][_a-z0-9]*)?

{hook definition}

hook__{hook}

[hook]s can only defined by [api]s. Note: a [module] can be an [api].
[hook]s should be defined in the {project}.api.php file of the project the [api] belongs to.

Examples of hook definitions:

• hook__block_info
• hook__node_delete

Hook implementation

^{[hook implementation] implements [function]}

{hook implementation}

{project}__{hook}

Examples of [hook implementation]:

• hook__menu
• routine__form
• node__menu
• file__element_info

Routine interface^experimental

^{[routine interface]}

{routine interface}

{api}(_[a-z][_a-z0-9]*)?

{routine interface definition}

routine__{routine interface}

[routine interface]s can only defined by [api]s. Note: a [module] can be an [api].
[routine interface]s should be defined in the {project}.api.php file of the project the [api] belongs to.

Examples of [routine interface] definitions:

• routine__page
• routine__form
• routine__views_plugin

Routine ^experimental

^[routine]

{routine}

{project}__{routine interface}__([a-z][_a-z0-9]*)

[routine]s should be implemented according to a [routine interface].

Examples of routines:

• node__page__default
• comment__form__comment
• views__views_plugin__display_default

Issues

Functions like theme_{name} and template_preprocess_{name} should be routines.

• theme__table
• hook_form_ID_OF_FORM_alter