[drupal-devel] needed documentation for block module for 4.6
I am upgrading recipe.module now like a good citizen. I find these instructions unlikely: "The only required changes to modules implementing hook_block() is to be careful about what is returned. Do not return anything if $op is not 'list' or 'view'". But those are the only $op values according to http://drupaldocs.org/api/head/function/hook_block. Perhaps we need to document 'configure' and other operations? I have not followed these changes very closely.
Agreed, I ran into this exact thing in the last 48 hours or so working on a patch for the block module and looking at block hooks in general. A quick search shows that only block, forum and statistics core modules use 'configure' - so perhaps the rarity of its use kept it from being documented. But knowing that you can add configuration options to a block would certainly be helpful for module contributors. andre Moshe Weitzman wrote:
I am upgrading recipe.module now like a good citizen. I find these instructions unlikely:
"The only required changes to modules implementing hook_block() is to be careful about what is returned. Do not return anything if $op is not 'list' or 'view'".
But those are the only $op values according to http://drupaldocs.org/api/head/function/hook_block. Perhaps we need to document 'configure' and other operations? I have not followed these changes very closely.
Agreed, I ran into this exact thing in the last 48 hours or so working on a patch for the block module and looking at block hooks in general. A quick search shows that only block, forum and statistics core modules use 'configure' - so perhaps the rarity of its use kept it from being documented. But knowing that you can add configuration options to a block would certainly be helpful for module contributors.
IMO the update docs should instruct module authors to move block settings into the "configure" page. It's best for consistency and usability. Anyone have time to write the docs? ;) Steven Wittens
Steven Wittens wrote:
IMO the update docs should instruct module authors to move block settings into the "configure" page. It's best for consistency and usability. Anyone have time to write the docs? ;)
I'm not sure - if these are block specific configuration options - they should be in block/configure (which is the current behaviour using 'configure' in hook_block). Or is that what you just said ;-) Either way - I can't edit the handbook. On a related note - To edit the PHPdocs - does one check out and patch against 'contributions/docs/developer/hooks'? I'm just not sure where drupaldocs.org is pulling its info from (nor where to patch should the inspiration to document hit me) ;-) andre
Agreed, I ran into this exact thing in the last 48 hours or so working on a patch for the block module and looking at block hooks in general. A quick search shows that only block, forum and statistics core modules use 'configure' - so perhaps the rarity of its use kept it from being documented. But knowing that you can add configuration options to a block would certainly be helpful for module contributors.
IMO the update docs should instruct module authors to move block settings into the "configure" page. It's best for consistency and usability. Anyone have time to write the docs? ;)
It is already documented in the update guide (somewhat). What do you think that needs to be expanded upon? Goba
It is already documented in the update guide (somewhat). What do you think that needs to be expanded upon?
Sorry, I misread the original post. I thought the update docs were the ones not mentioning the "configure" part. Still, the hook_block() docs need to be updated... Steven Wittens
Steven Wittens wrote:
Agreed, I ran into this exact thing in the last 48 hours or so working on a patch for the block module and looking at block hooks in general. A quick search shows that only block, forum and statistics core modules use 'configure' - so perhaps the rarity of its use kept it from being documented. But knowing that you can add configuration options to a block would certainly be helpful for module contributors.
IMO the update docs should instruct module authors to move block settings into the "configure" page. It's best for consistency and usability. Anyone have time to write the docs? ;)
Neil once posted an explanation of the modified _block() hook. I believe it was part of his patch. Neil? -- Dries Buytaert :: http://www.buytaert.net/
On Tue, Jan 25, 2005 at 08:40:49AM +0100, Dries Buytaert wrote:
Steven Wittens wrote:
Agreed, I ran into this exact thing in the last 48 hours or so working on a patch for the block module and looking at block hooks in general. A quick search shows that only block, forum and statistics core modules use 'configure' - so perhaps the rarity of its use kept it from being documented. But knowing that you can add configuration options to a block would certainly be helpful for module contributors.
IMO the update docs should instruct module authors to move block settings into the "configure" page. It's best for consistency and usability. Anyone have time to write the docs? ;)
Neil once posted an explanation of the modified _block() hook. I believe it was part of his patch. Neil?
The documentation in hook_block() on drupaldocs.org should be fully updated. Implementing the 'configure' op isn't strictly part of updating a module. However, I do think it should be documented now. Bug me in IRC /next/ week and I will do it myself if you catch me at a good time. I'm a bit short on time for this week. -Neil http://civicspacelabs.org/ http://delocalizedham.com/
participants (6)
-
Andre Molnar -
Dries Buytaert -
Gabor Hojtsy -
Moshe Weitzman -
Neil Drumm -
Steven Wittens