Problem/Motivation

Updated as of comment #7

The array $plugin['classes'](a.k.a identifier of the class) and its field'class' are not documented in code nor in the example pages.

Proposed resolution

Add documentation and example pages.

Files: 
CommentFileSizeAuthor
#16 ctools-classes_key_docs-2054803-16.patch2.31 KBMac_Weber
FAILED: [[SimpleTest]]: [MySQL] Drupal installation failed.
[ View ]
#9 ctools-classes_key_docs-2054803-9.patch1.41 KBKazanir
PASSED: [[SimpleTest]]: [MySQL] 121 pass(es).
[ View ]

Comments

merlinofchaos’s picture

Drupal handles those all of that stuff internally via the registry system and autoload; it is completely opaque to CTools so there's not much that can be done about it.

I would question why you would actually instantiate a class in hook_ctools_plugin_type() however; that should just be returning a packet of data about what plugin types are available. I can't think of a good reason to actually instantiate a class there, so maybe you can just organize your code a little bit differently.

Mac_Weber’s picture

@merlinofchaos the module openlayers is an example. The plugins declared at hook_ctools_plugin_type() are extensions of a parent class.

In openlayers it works because the main classes are declared in the file .module. If you move these main classes to a external file and list them on openlayers.info it will not work. Installing the module will return errors from the plugin file because the main class is not found.

Maybe the structure of this module is not following the best practices. If so, I'd like to learn how to handle such situation, because I'm rewriting the module leaflet to make it similar to openlayers.

Mac_Weber’s picture

I think I've tracked the error. It seems the $class_name (which is sometimes called "class identifier") may point to different things.

The plugin class identifier may refer to:

a file name
○ the file which holds the class (filename.class.php)
○ in this case the class name can be different than the class identifier
the class name
○ if the class is n the same file as the $plugin
○ the plugin .inc file can have a different name than the class identifier

Is it correct? I could not find documentation about the class identifier.

merlinofchaos’s picture

I'm sorry, I don't see how the class identifier is related to the issue you're having. Or maybe the issue isn't being reported very well; it's hard to be sure what your actual problem is.

When you mention $class_name, can you point me to what you're referring to?

merlinofchaos’s picture

Okay, so I went to take a look at hook_ctools_plugin_type() in openlayers and it doesn't declare any classes (directly) in the function. I suspect that you're having trouble explaining the actual problem, and without a concrete code example I don't have any advice.

merlinofchaos’s picture

Hm. I think you may be referring to the 'classes' key in hook_ctools_plugin_type()

Which does, in fact, appear to be undocumented. That's surprising, I didn't realize it hadn't been documented.

That key is used by CTools to automatically register any classes provided by plugins. I'm not sure that's relevant to the problem you're experiencing, because with this system you don't actually declare your plugin classes in the .info file; instead, CTools finds and declares the plugins for you.

Mac_Weber’s picture

Title:Add documentation for $plugin['classes'] (a.k.a identifier of the class) and its field'class'» classes declared on module.info are not dynamically loaded on hook_ctools_plugin_type()
Category:task» bug

Yes, I realize I haven't described my problem well. It's because it's the first time I'm coding ctools plugins and nobody at IRC (even people who was using it) knew how the 'class identifier' works. They just used it, but they said they don't know in deep what they were doing.

After understanding ctools better I think I can organize my ideas:

The function ctools_plugin_get_class() receives in its arguments $class_name, but in its documentation it is described as being the identifier of the class. In fact, the argument received there is the identifier, not the class name. Is it ok to send a patch changing the name of this argument? Maybe $class_identifier? Actually it is called classes in the $plugin array, as discussed below:

The actual $plugin array is something like this:

<?php
// Piece of code taken from ctools_plugin_get_plugin_type_info().
$plugin_type_info += array(
         
'module' => $module,
         
'type' => $plugin_type_name,
         
'cache' => FALSE,
         
'cache table' => 'cache',
         
'classes' => array(), // Undocumented and misleading
         
'use hooks' => FALSE,
         
'defaults' => array(),
         
'process' => '',
         
'alterable' => TRUE,
         
'extension' => 'inc',
         
'info file' => FALSE,
         
'hook' => $module . '_' . $plugin_type_name,
         
'load themes' => FALSE,
        );
?>

'classes' is a misleading name, it should be called 'class_identifier'. I understand it cannot be change now, in order to not break many modules using ctools. Although, it is not documented and in the documentation I think it is important to include this note explaining that this 'classes' receives an array of identifiers and shall not receive an array of class names.

In addition, it should document the array that each class identifier may use. For example describing that the 'class' in this array may point to a class name or a file name, depending of the plugin architecture.

@merlinofchaos If you confirm my assumptions I can send a first patch.

Mac_Weber’s picture

Issue summary:View changes

Updated issue summary.

Mac_Weber’s picture

Title:classes declared on module.info are not dynamically loaded on hook_ctools_plugin_type()» Add documentation for $plugin['classes'] (a.k.a identifier of the class) and its field'class'
Category:bug» task

Updated as of comment #7

Kazanir’s picture

Issue summary:View changes
StatusFileSize
new1.41 KB
PASSED: [[SimpleTest]]: [MySQL] 121 pass(es).
[ View ]

I ran into not knowing what this key did today but got it figured out thanks to this issue. Here's a patch for the plugins-creating.html help file:

Kazanir’s picture

Component:Code» Documentation
Status:Active» Needs review
Pol’s picture

Status:Needs review» Reviewed & tested by the community
Mac_Weber’s picture

Status:Reviewed & tested by the community» Needs review
StatusFileSize
new4.34 KB
FAILED: [[SimpleTest]]: [MySQL] Drupal installation failed.
[ View ]

There was an trailing space at #9, then I fixed it and also I've improved the description explaining that this class identifier may be either a file or a class name.

Status:Needs review» Needs work

The last submitted patch, 12: ctools-classes_key_docs-2054803-12.patch, failed testing.

Mac_Weber’s picture

Status:Needs work» Needs review
StatusFileSize
new2.3 KB
FAILED: [[SimpleTest]]: [MySQL] Drupal installation failed.
[ View ]

Sending correct patch file for comment #12

Status:Needs review» Needs work

The last submitted patch, 14: ctools-classes_key_docs-2054803-13.patch, failed testing.

Mac_Weber’s picture

StatusFileSize
new2.31 KB
FAILED: [[SimpleTest]]: [MySQL] Drupal installation failed.
[ View ]

Testbot is having issues, it is not failing beacause of this patch. See #2375345: Dependency on core module results in PHP Fatal error: Cannot redeclare system_requirements()
In the meanwhile I've figured out an open HTML tag and fixes it.

Mac_Weber’s picture

Status:Needs work» Needs review

Status:Needs review» Needs work

The last submitted patch, 16: ctools-classes_key_docs-2054803-16.patch, failed testing.

  • EclipseGc committed 85c1c36 on
    Issue #2054803 by Mac_Weber, Kazanir, merlinofchaos Added documentation...
EclipseGc’s picture

Status:Needs work» Fixed

Committed to head. You will see this in 7.x-1.5

Eclipse

  • EclipseGc committed 85c1c36 on 8.x-2.x
    Issue #2054803 by Mac_Weber, Kazanir, merlinofchaos Added documentation...

Status:Fixed» Closed (fixed)

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