On Wed, 16 Jun 2004, Todd Grimason wrote:
> * Gerhard Killesreiter <killesreiter@xxxxxxxxxxxxxxxxxxxxxx> [2004-06-16
> 06:07]:
>
> [...]
>
> > I really wonder why people don't see such easy solutions and must fill my
> > inbox with mindless blabber about teasers (not aimed at you).
>
> Thanks for answering in spite of this.
*g*
> But why do people keep asking? Frankly because the docs kind of suck. And
> there are near-zero comments in the code. Those are two obvious factors from
> my point of view.
a) It is a bit difficult to document "invent a module"
b) the code contains an increaing amount of doxygen comments.
> I don't want to have to bother you guys for these kinds of things, but
> neither do I want to have to read nearly every line of code in Drupal to
> figure these things out.
The nodeapi hook as such is documented here:
http://drupal.org/doxygen/drupal/group__hooks.html#ga12
> You say to write a module. Previously I read the node_api doxygen docs which
> say:
>
> "If you don't need to make a new node type but rather extend the existing
> ones, you should instead investigate using hook_nodeapi()."
There you go.
> and
>
> "If you are writing a node module, do not use this hook to perform actions
> on your type of node alone. Instead, use the hooks set aside for node
> modules, such as hook_insert() and hook_form()."
Yep.
> <http://drupal.kollm.org/tmp/drupal-phpdoc/>
>
> These two points are far from clear.
Not to me. If you have a better formulation I'd like to hear it.
> And the diary example in the handbook
> is a bit simplistic shall we say.
Well.
> I realize this is all volunteer work, and appreciated, but it would
> *drastically* help if the node system, and extending it had much better
> coverage in the docs. I know developers hate writing docs,
> understandably so, but if everyone's asking the same questions about
> 'easy solutions' it's time to think maybe it's not evident at all to
> those not intimate with the code. Especially as this is the heart and
> soul of the whole system.
I really think that our docs have dramatically improved during the last
year or so.
> If it's felt that a very small % of users actually modify/extend nodes
> and internals, and more extensive docs for those who don't just "get it"
> are uncalled for, just say so in the docs. "here's the general idea. to
> get a better idea, read all the code, it changes too fast to keep the
> docs in sync."
We sure would like to have better docs, if they are unclear. But we also
can't write a whole novel in doxygen comments.
And seriously: If I want to add a teaser field to a node /and/ I read the
nodeapi docs at http://drupal.org/doxygen/drupal/group__hooks.html#ga12
it should be very clear what to do:
# "form pre": The node form is about to be displayed. This hook can be
used to add fields at the top of the form.
# "insert": The node is being created (inserted in the database).
Together with the genral understanding what a hook is, this should be
obvious.
> Then again, this is endemic to 98% of open projects, and at the end of
> the day it is quite nice software. I just get the impression this
> particular weakness turns away many who would otherwise join in and
> help. And I (and countless others) could ask less repetitive annoying
> questions if it was fleshed out a bit more in the docs.
The annoying part of the recent discussion on drupal-devel was that all
people were discussing what "should be" instead of producing a single line
of code.
> And if I should write a new module to add back a teaser, what's flexinode
> for? (OK, yes this is half-trolling...)
You can of course simply use flexinode instead. With the recent addition
of "select a fields to appera in teaser" this will work allright. But you
can't add teasers to blogs or books this way.
BTW: You will also need the _load hook.
Cheers,
Gerhard
--
[ Drupal support list | http://list.drupal.org/ ]
|
