OOE: Drupal.org project application checklist [mirror]

This page roughly mirrors the Drupal.org version of the special Apply for permission to create full projects issue [D7] ooe for the tutorial module OOE = Object Oriented Examples = One Of Each, and adheres to the Project application checklist guide.


Application for permission to create full projects

This application includes links to external resources on a dedicated demonstration site.

This application meets the Project application checklist (see below).

Link to project (sandbox) page

https://drupal.org/sandbox/webel/2120905

Link to project repository viewer

http://cgit.drupalcode.org/sandbox-webel-2120905

Git clone command

git clone --branch 7.x-1.x git://git.drupal.org/sandbox/webel/2120905.git

Detailed description of what the 'OOE = Object Oriented Examples = One Of Each' project does

The Object Oriented Examples (OOE) project is a unique educational tutorial module for Drupal7 intended primarily for enthusiasts of graphical software engineering with Unified Modeling Language (UML) and fans of object-oriented Design Patterns. It may also be of interest to advocates and practitioners of object-oriented software engineering who are not yet familiar with UML, especially those with some background in Java (or similar OO languages).

This is an actively maintained development project, with a dedicated live demonstration site and a gallery of graphical Unified Modeling Language (UML) diagrams of the OOE system, which illustrate the main purpose of this module and serve also as a tutorial for other graphical UML enthusiasts.

OOE may also be taken to mean "One Of Each", as it endeavours to represent one of each of the capabilities of Drupal7 module development in purely object-oriented form, starting with object-oriented versions of some well known existing Drupal7 tutorials and examples.

It achieves this by using a special "bridge" between the Drupal7 contributed module API (via a specially organised .module file) and a completely object-oriented OOE world that uses a special PHP recipe that is (more) amenable to reverse engineering to graphical UML, currently optimised for processing with the PEAR:PHP_UML script into XMI and graphical modelling in the MagicDraw UML tool (although once in XMI any decent UML tool could be used).

When using the OOE classes one never has to deal directly with Drupal "by convention" structured arrays; instead, the Drupal arrays are encapsulated completely, and the OOE classes know how to build and hand off valid Drupal structured arrays to the Drupal contributed module API. By encapsulating Drupal structured arrays OOE also supports IDE prompting on operations/methods (and their tightly bound documentation) that is not possible with Drupal7's "by convention" structured arrays, as demonstrated in NetBeans IDE in this short video.

Finally, when using OOE, one does not need to implement complex behaviours in the usual hooks, page handlers, and form handlers in the .module file; instead, OOE supports fully object-oriented page controllers and form controllers (although this currently requires a small and harmless tweak to the Drupal7 core's form.inc, see below).

Requirements

The OOE module depends (as a "tip of the hat") on the experimental Page controller project.

It requires also the X Autoload class loader.

It also currently requires a small and completely harmless tweak to the Drupal7 form.inc, as described at:

- Drupal 7.25: form.inc 1471: form_execute_handlers($type, &$form, &$form_state): $function($form, $form_state); Does not work for static class method 'Drupal\mymodule\FormContoller::handler'

- drupal_retrieve_form() issues Undefined index: warning on line 764 when static class method used as $form_id: hinders use of object-oriented FormController

The need for the tweaks is also well explained in those issue reports.

It is planned that patches will be provided for these against latest Drupal7 soon. In the meantime, it's very simple to simply edit the Drupal7 core form.inc file after the code examples in the issue reports above, or using this guide.

Related projects (and how they differ).

The Ghost project also demonstrates object-oriented page and form controllers for Drupal7, but it is not conceived as a graphical UML-friendly project, and does not endeavour to map the Drupal7 system (including blocks, menus, menu items, rendering etc.) into an object-oriented bridge API for Drupal7. Page and form controllers are just a small part of OOE.

Q: Is OOE an attempt at an object-oriented version of Drupal7 core (or a "better Drupal7") ?

No. OOE is designed specifically to work with the Drupal7 contributed module API, and to offer an object-oriented bridge to it. However, to the extent that it maps out the Drupal7 contributed module API in a UML-friendly object-oriented form it reveals a lot about Drupal7. OOE does not in any sense repeat the functionality of Drupal7 core.

Q: Is OOE already a complete object-oriented API mapping the entire Drupal7 system suitable for development of other object-oriented modules ?

No. So far it is deliberately only a functioning proof-of-concept with an emphasis on introducing a UML-amenable PHP coding style to the Drupal community, based on a few well known Drupal7 examples. But there is no reason it could not be extended to become a fully-fledged object-oriented module development system for Drupal7.

Q: But what about Drupal8 ? Isn't that object-oriented already ?

Drupal8 introduces an increasing degree of object-orientation, but is not developed specifically with graphical UML software engineering in mind and is not particularly UML friendly. A Drupal8 version of the UML-friendlier OOE demonstration module may in future be developed for Drupal8 also. (In any case, when the OOE module was commenced, Drupal8 was not yet mature enough to support a live demonstration site.)

Some information about my background and experience with Drupal

The Object Oriented Examples (OOE) module is developed by Dr Darren Kelly of Webel IT Australia, specialists in PHP-driven Drupal CMS web engineering, UML, SysML, Java and XML.

Although OOE is the first contributed module by Webel for Drupal.org, Webel has developed many custom Drupal modules for clients.

In addition to using Drupal CMS for developing web sites for clients, Webel has used Drupal CMS for many years to develop educational web sites promoting graphical software engineering with Unified Modeling Language (UML), graphical systems engineering with Systems Modeling Language (SysML), as well as Java and XML/XML Schema engineering, and of course PHP-driven Drupal CMS too.


Project application checklist

1. Basic application checks

1.1 Ensure your application contains a repository and project page link.

Done. See top.

1.2 Ensure your project is not a duplication.

Done. See Related Projects above.

1.3 Ensure you don't have multiple applications.

Done. This is the 1st and only application.

2. Basic repository checks

2.1 Ensure the repository actually contains code.

Done. Full Git clone also performed and checked.

2.2 Ensure you are working in a version specific branch.

Done. Working on 7.x-1.x (and can Git clone ok).

3. Security Review

3.1 Ensure the project does not contain any security issues.

Done.

4. Licensing checks

4.1 Ensure the repository does not contain a ‘LICENSE.txt’ file.

Done.

4.2 Ensure the repository does not contain any 3rd party (non-GPL) code.

Done.

5. Documentation checks

5.1 Ensure the project page contains detailed information.

Done.

5.2 Ensure the repository contains a detailed README.txt

Done.

5.3 Ensure the code contains a well-balanced amount of inline-comments.

Because this module is conceived as and educational tutorial module for other Drupal developers (for those developers interested in graphical UML and/or OO techniques) this module contains particularly verbose inline comments, including clearly referenced quotes from Drupal.org docs and other non-OO Drupal.org tutorials and examples for Drupal7.

It also employs inline comments to comment out some code that is deliberately left in for educational purposes (and in some cases to illustrate what does not work).

6. Coding standards and style

6.1 Run an automated review and ensure there are no major issues.

Seldom in the history of Drupal contributed module development has anybody spent so much time examining Coder and the Coder rules, discussing/reporting issues with Coder, and/or discussing and/or challenging the Drupal coding and documentation standards. The developer in fact spent some weeks alone on this matter.

Coder has been used to inspect every single code file, however the code deliberately does not pass the current Coder rules, primarily because a very particular UML-amenable PHP coding style is employed (and must be used to support better reverse engineering to XMI/UML), but also because the developer contests a number of Drupal coding standards as clearly not yet very OO friendly and in some cases clearly inconsistent.

Please note: it is not possible to simply put this UML-dedicated project through a PHP code manipulation ("correction") tool, as it would break the synchronisation between the PHP project and the UML XMI project files. This is clearly a very special case.

All line-end whitespace has been removed (even though PHP does not care about it) as Coder requires.

Full stops (however unnecessary for one word comments like '// DEBUG.') have been included at the end of the line of most inline comments, except where inline comments are used to comment out code (see below).

A space has been left after most inline comment markers and before the comment text (like this // DEBUG., not '//DEBUG.'). This also does not work well when using inline comments on code (see below).

The capital TRUE, FALSE, NULL has now been used (all lower case forms replaced/converted).

The developer rejects completely - and with very good reason - the use of the verbose 'Interface' suffix on interfaces, preferring the concise, clear, and promptable 'I' prefix. This superior, UML-friendlier practice will not under any circumstances be changed by this developer for this UML-oriented project, where graphical UML diagrams and UML Interface symbols make it clear what is and what is not an interface. Please see: Please remove this requirement: 'WARNING | Interface names should always have the suffix "Interface"'.

As all files (except for the .module file) contain only either a single Interface or a single Class, with documentation in the Class or Interface header doc block, the developer does not include a description in any @file doc header, and only includes the class or interface name, not the namespace, as that practice is redundant and fragile against repacking/refactoring in tools like NetBeans. Please see Please relax requirement for @file when using OO Class or Interface per file: 'ERROR | Missing file doc comment' updated. (As a concession the @file is included, but still considered completely redundant for pure OO.)

The developer completely rejects the current requirement that parameters of methods of classes should use $lower_case as inconsistent, especially for setters, as argued here (OO: Coder complains about camel caps (camelCase) argument to setter method in Class ). Instead, the consistent "Java like" practice of $camelCase for both method parameters and class variables is used, as well as for local variables. Please note that some vendor code included in the Drupal8 core downloads also uses this practice, and with very good reason, because it's consistent and sensible and has been used by OO advocates (especially many Java coders) for a very long time.

The developer insists that inline comments should be permitted to comment out code, and that in some cases such commented out code should be left even in "finished" projects (are they ever ?) and when this is done it is (for the sake of the IDE) not a good idea to leave a space before the code after the comment markers. Clearly, if inline comments are used for code, then the line will not end a full stop (period '.'). Please see:

- Inline comments before code (as opposed to text) should not enforce: Inline comments must start with a capital letter

- Inline comments before code (as opposed to text) should not enforce: 'ERROR | No space before comment text; expected "//'

- Commented out code blocks using inline comments give multiple indentation errors.

In some cases long URLS are used with inline comment to include references to PHP code tips: Please permit long URL text in inline comments in the code area (not in the docblock).

In some cases single quotation marks 'around quoted text' are used in inline comments to indicate that Drupal.org docs or other examples are quoted: Permit punctuation (like quotation mark) at start for function comment.

Although the developer also does not agree with this Drupal recommendation, and effort has been made to reduce the use of inline comments after code statements: Please relax rule for inline Comments: 'Comments may not appear after statements'.

In some cases the developer includes (for educational purposes) parameter indicators in @see docs, which trip Coder but not the API module. Please see: Coder does not accept function parameter indicators in @see (but API module does).

In some cases (again consistent with some common Java conventions) CAPITALS_WITH_UNDERSCORES are used for static final class variables that are to act like constants. This matter has not been fully resolved: OO: Coding standards: permit CAPITALS_WITH_UNDERSCORES for static class variables

So. Nobody can say I didn't at least try hard. Please see also my suggestion for offering Drupal modules together with a Coder configuration file: Advanced feature idea: Coder strict mode (applies all rules) and user selectable rule switches, together with Coder configuration file for submission with a module.

7. API and best practices Review

7.1 Ensure you are using Drupal's API correctly.

There is one known major problem area discussed in detail here: This requirement is at odds with OO encapsulation: WARNING | Only string literals should be passed to t() where possible. The current Drupal translation registry strategy is not compatible with translation of some dynamically generated strings or with OO encapsulation of strings as variables to which translation policies are applied "after the fact". The developer is completely aware of the currently recommended practice for t() and the reasons for it, but still seeks a strategy more compatible with OO encapsulation (than say translation with placeholders). The matter may be addressed in future releases, but not yet here. For the time being, this project (with very special aims) is known to be not completely translatable.

Also, one database variable is introduced (in an object-oriented adaptation of the well known Current Posts example) that is not yet removed by an uninstall facility; this will be addressed in future releases.

Concerning HTML output and theming. This module demonstrates encapsulation of and generation of valid Drupal7 render arrays using special OOE Render Classes. There is some use of theming functions and theming hints already included. But advanced theming is not yet handled by the demonstration (not yet encapsulated using OOE classes), it is the next major topic for future releases.

Visit also