This is just wishful thinking. I really like this module. I try to use it my everyday module development sort of stuff. I fall into the lazy developer category.

I was thinking that it would be really helpful for this module to provide a hook (or set of hooks) to allow modules to provide templates for the Module Builder.

For instance, CCK could provide a template of functions that are used in creating a CCK field. I think Views could offer many templates for fields or plugins. Basically any module that provides hooks, could use this. I don't think it should replace documentation, but would offer a code template that would be a great help to developers.

I would be interested in trying to code this. My time is limited at the moment, but maybe more summer, I can look at this. If you think this is actually a good idea. I can also provide some sample code of how a module might implement the hook(s) to help clarify my idea.

Comments

joachim’s picture

joachim CreditAttribution: joachim commented

That would be pretty cool.
Question is, would views / cck maintainers be interested in keeping module builder code in their modules and keeping it up to date?
Alternatively, are there fixed online sources of hook data that we can use, the same way we get core hook data from the Drupal API site?

zzolo’s picture

zzolo CreditAttribution: zzolo commented

That is a big question for sure. Will module maintainers do this? It's hard to say. If, module_builder becomes a little more common place, then I think more module maintainers will. But, this is kind of a chicken/egg dilemma, as well. It seems like providing a hook template is a lot like writing documentation, and honestly, most people (including myself) are not that good about it. But, I think if it is helpful, it will become common practice.

But, personally, even if CCK did not implement the hook, I write enough CCK fields and widgets for projects, that I would create my own hook for module_builder (on behalf of CCK). Right now, I just keep a template-ish file.

I would still want module maintainers to provide their own hook templates. 1) I am still mystified by making CCK modules, and module creators usually know their modules the best, and 2) hooks overall are not documented well or at all.

As far as I know, there are no fixed sources of hook documentation. Otherwise, I would have not thought about this. I think full documentation and hook templates are two different things, but both are extremely helpful. It would be ideal to have a single source, probably in the handbooks, that provide detailed information and templates.

mojzis’s picture

mojzis CreditAttribution: mojzis commented

subscribe, great idea

joachim’s picture

joachim CreditAttribution: joachim commented

Ok, so let's figure out how this should work.

So first of all, we have two kinds of data: function definitions which we download from api.drupal.org, and our own template files which we ship with the module.
When you generate a module, both sets of files are used to whip up some function stubs.
(There's a proposal somewhere else to do the processing at the download stage, by the way.)

So: what should the hook tell us about other modules? What should they provide?

Also, given that module_builder is something you use infrequently, and not on live sites, a hook is an extra function that PHP has to process, which just sits there on every single production site serving no purpose. Might a module_builder.inc file in the modules folder be cleaner?

zzolo’s picture

zzolo CreditAttribution: zzolo commented

As far, as moving code out of the .module file, this is almost always a good idea. It's true, Drupal parses all the main module files every page load. So, ideally our hook would allow for different files. Like the menu hook or the views hook.

To me, we can keep it simple. There are two things to provide on a basic level:
* A file structure (directory and filename)
* Code template

For instance, (I am not 100% accurate), for a View Row Plugin, it would provide the following:
template.module -> hook_views template code
views/example.views.inc -> views_router_function_thing template code
views/example.plugin.views.inc -> plugin class template code

So, basic array structure. This could be a lot better; just kind of thinking off the cuff.

$module_builder['views'] = array(
  'id' => 'views',
  'name' => t('Views Templates'),
  'templates' = array(
    'views_row_plugin' => array(
      'id' => 'views_row_plugin',
      'name' => t('Views Row Plugin'),
      'functions' => array( // Could use a better name, as these are code snippets
        'module' = array(
          'template file' => '[[MODULE_NAME]].module',
          'include file' => 'views/module_builder/views_hook.template',
        ),
        'views_router' = array(
          'template file' => 'views/[[MODULE_NAME]].views.inc',
          'include file' => 'views/module_builder/views_router.template',
        ),
        'views_style_plugin' = array(
          'template file' => 'views/[[MODULE_NAME]].plugin.views.inc',
          'include file' => 'views/module_builder/views_row_plugin.template',
        ),
      ),
    ),
  ),
);

The next level of features, I see the following:
* Modules providing a settings form, that would affect the template output
* Some sort of token system for replacing values

joachim’s picture

joachim CreditAttribution: joachim commented

I'm sticking with the current model of downloading from a ViewCVS page, for now at least.
So module only need to give a URL and a list of files.

Here is what we're doing on behalf of Drupal core:

/**
 * Implementation of hook_module_builder_info().
 *
 * Provide information about hook definition files to Module builder.
 * This hook should go in a MODULE.module_builder.inc file in your module folder.
 * Is it only loaded by Module builder when the user goes to download new hook data.
 *
 * @return
 *   An array of data, keyed by module name.
 *   The subsequent array should specify:
 *    - url, a base url to fetch files from.
 *      Use tokens to insert filenames and a branch number: %file, %branch 
 *    - minor_version, the current minor version of the module, eg 1, 2. 
 *      This becomes the last part of the CVS branch, eg DRUPAL-6--N
 *    - hook_files, an array of files to fetch. The filename is the key
 *      and the value is the file where the hook code should eventually be stored.
 *      (TODO: storing code in different files not done yet!)
 *      Usually this will be '%module.module' but for instance,
 *      'install.php' has hooks that should go in '%module.install'.
 */
function module_builder_module_builder_info() {
  $data = array(
    // Hooks on behalf of Drupal core.
    'system' => array(
      'url' => 'http://cvs.drupal.org/viewvc.py/drupal/contributions/docs/developer/hooks/%file?view=co&pathrev=%branch',
      'minor_version' => 1,
      'hook_files' => array(
        // List of files we should slurp from the url for hook defs.
        // and the destination file for processed code. NOT USED YET!
        'core.php' =>    '%module.module',
        'node.php' =>    '%module.module',      
        'install.php' => '%module.install',      
      ),
    ),
    // We need to do our own stuff now we have a hook!
    /*
    'module_builder' => array(
      'url' => 'http://cvs.drupal.org/viewvc.py/drupal/contributions/docs/developer/hooks/%file?view=co&pathrev=%branch',
      'minor_version' => 1,
      'hook_files' => array(
        'foo.php' =>    '%module.module', // TODO!
      ),
    ),    
    */
  );
  
  return $data;
}

Next job is to go forth and convince other module maintainers to support this! Any volunteers?

zzolo’s picture

zzolo CreditAttribution: zzolo commented
Status: Active » Fixed

I'll try to do this with my modules, since I was the one who suggested the idea in the first place. I think I'll have to use in action to really see it, but it looks good here. Thanks for the great work.

joachim’s picture

joachim CreditAttribution: joachim commented
Status: Fixed » Active

I'm reopening this as I think it needs tweaking.

    'system' => array(
      'url' => 'http://cvs.drupal.org/viewvc.py/drupal/contributions/docs/developer/hooks/%file?view=co&pathrev=%branch',
      'minor_version' => 1, ### [2]
      'hook_files' => array(
        // List of files we should slurp from the url for hook defs.
        // and the destination file for processed code.
        'core.php' =>    '%module.module',  ### [1]
        'node.php' =>    '%module.module',     
        'install.php' => '%module.install',     
      ),
    ),

[1] Currently, the root of the filename (such as 'core' for core.php) is used for UI hook groups, minus the extension.
This is no good for, say, views, which calls its hook doc file hooks.php.
On the other hand, we need to convince merlin to split that file into two as there are two different destinations for views hooks, so we could request a name change too...
[2] Some modules run on HEAD.

joachim’s picture

joachim CreditAttribution: joachim commented
Status: Active » Fixed

New version:

    'system' => array(
      'url' => 'http://cvs.drupal.org/viewvc.py/drupal/contributions/docs/developer/hooks/%file?view=co&pathrev=%branch',
      'branch' => 'DRUPAL-6--1',
      'group' => '#filenames',
      'hook_files' => array(
        // List of files we should slurp from the url for hook defs.
        // and the destination file for processed code.
        'core.php' =>    '%module.module',
        'node.php' =>    '%module.module',      
        'install.php' => '%module.install',      
      ),
    ),
    // We need to do our own stuff now we have a hook!
    'module_builder' => array(
      'url' => 'http://cvs.drupal.org/viewvc.py/drupal/contributions/modules/module_builder/hooks/%file?view=co&pathrev=%branch',
      'branch' => 'DRUPAL-6--2',
      'group' => 'module builder',      
      'hook_files' => array(
        'module_builder.php' => '%module.module_builder.inc',
      ),
    ),

As ever, documentation in the file.

zzolo’s picture

zzolo CreditAttribution: zzolo commented

I just put this hook into the OpenLayers Drupal-6--1 branch. A few things I noticed:

* I could not get it to read form the cvs repo, without directly putting in the URL without any tokens. This may be cause because our HEAD branch is not maintained.
* When creating a module in Drush, it did not respect the option of Beginner or Advanced
* No errors were ever given when I had a bad URL in my hook implementation

Overall great job! The Drush integration is great.

joachim’s picture

joachim CreditAttribution: joachim commented

* I could not get it to read form the cvs repo, without directly putting in the URL without any tokens. This may be cause because our HEAD branch is not maintained.

Basically, the %branch token is just a convenience. You could leave that part in your URL if you wanted.
Also, the trick is to try the URL out yourself first. If you see a complete file of code, you're good.
What URL did you try?

* When creating a module in Drush, it did not respect the option of Beginner or Advanced
No support for that in Drush yet. You can file another issue and post a patch ;) -- it's really not a priority for me as there are only a few templates that make use of this.

* No errors were ever given when I had a bad URL in my hook implementation
Nope. If there's no file, or if there are no hooks in the file, you get nothing. Again, file a bug and that one I might get round to sometime :)

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.