[drupal-devel] [feature] Improve functionality of block generation for book module

shark drupal-devel at drupal.org
Tue Jul 5 21:48:37 UTC 2005


Issue status update for 
http://drupal.org/node/14120
Post a follow up: 
http://drupal.org/project/comments/add/14120

 Project:      Drupal
 Version:      cvs
 Component:    book.module
 Category:     feature requests
 Priority:     normal
 Assigned to:  andremolnar
 Reported by:  nysus
 Updated by:   shark
 Status:       patch

What is the status of this? Is this patch going to go into the Drupal
core?  I'd really like to use it for my site to automatically create
the site navigation for a simple site, unless there is a better way to
do that.




shark



Previous comments:
------------------------------------------------------------------------

December 8, 2004 - 22:12 : nysus

Attachment: http://drupal.org/files/issues/book_19.patch (4.85 KB)

Attached is a patch for the book module that does the following:


1) Allows book blocks to appear on any page at any time, not just when
a node from the book is being viewed.
2) Allows multiple book blocks to appear on the same page.


This functionality is achieved by the automatic creation of individual
blocks for each book when the book is created.  Simply enable the
book's block to enjoy the benefits of 1 & 2 above.  If the blocks are
not enabled, the blocks will appear only when a node from that block is
being viewed (the same way it works now).




------------------------------------------------------------------------

December 9, 2004 - 04:35 : andremolnar

Attachment: http://drupal.org/files/issues/book_19_1.patch (4.84 KB)

+1 This is great.  A good many people have asked for something like
this, and I think its a nice solution.  But in the end this isn't up to
me.


One minor error in the patch... 


+    $result = db_query('SELECT n.title, b.block, b.nid FROM {book} b
INNER JOIN {node} n on n.nid = b.nid WHERE b.parent = 0');


b.block is not a valid field in this query.  this updated patch removes
reference to it.


andre




------------------------------------------------------------------------

December 9, 2004 - 05:54 : nysus

Glad you like it and thanks for fixing that up.  It was left over from
an older version of my patch.




------------------------------------------------------------------------

December 9, 2004 - 05:54 : andremolnar

Steve,


If I apply this patch,  and I attempt to configure one of the newly
created blocks. I noticed that for some reason the block.module is
returning "true" at line 249 (of the block module)- and is creating a
form for module-specific configuration.  But all that shows up on the
screen is the word "array".


Can you trace this back to see why - and maybe update the patch.


I can continue to test your changes - anything to help this patch make
it into core.


andre




------------------------------------------------------------------------

December 9, 2004 - 07:29 : nysus

Hmmm...probably because I tested my patch on my version of Drupal,
version 4.5.1.  I'm having no problems.  Are you using a cvs version of
Drupal to test.  If so, I'll set up cvs on my site and track this down.




------------------------------------------------------------------------

December 9, 2004 - 10:53 : drumm

See http://drupal.org/node/12347 for information on how the block system
has been updated. When I saw that the elseif ($op == 'view') was taken
out I knew immedaitely that there was something weird about this patch.




------------------------------------------------------------------------

December 9, 2004 - 10:58 : nysus

OK, thanks for the tip.  Sorry for the confusion.  Still kind of new to
making open source contributions and it's easy for me to overlook some
obvious stuff like this.  I'll fix this up when I get a chance.




------------------------------------------------------------------------

December 9, 2004 - 11:06 : Dries

Please do, because this being a new feature, it has no chance getting
committed to the DRUPAL-4-5 branch.  The DRUPAL-4-5 branch is in
bugfix-mode.  New features go into CVS HEAD.




------------------------------------------------------------------------

December 9, 2004 - 14:32 : Dries

There is quite a bit of duplicated code in the patch.  Maybe it can be
simplified (using a function)?  Either way, it is a little weird.  I
haven't tried the path, and I'm not sure I understood the description. 
It's somewhat vague.  Is the book module exporting multiple blocks that
are nearly identical, yet have different display behavior?  If so, why
not add a simple block configuration setting to the original book
block?




------------------------------------------------------------------------

December 9, 2004 - 18:51 : nysus

Dries,


Yes, there is some code that can be factored out and some general
cleaning up that can be done.  It was a little tricky to write so I
left it kind of ragged around the edges until I'm sure there are no
bugs.  It has worked very well on 4.5.1 but I obviously need to update
it to work with cvs.  I'll be on that soon.


As far as what it does:


1) For every new book that a user creates, a new block is associated
with it.  So if you create "Book A", "Book B", "Book C", you will get
three new blocks visible on the block administration page called  "Book
A", "Book B", "Book C".  The original "Book Navigation" block is still
there, too.  The functionality of the "Book Navigation" block is not
affected at all by this patch.
2) If Book A's block is enabled, the block containing its menu will
appear not only when a node within Book A is viewed, but at all times
(unless the user suppresses it on certain pages with the "path"
feature).  When any node is that is NOT in Book A is viewed, Book A's
menu still appears but it is fully collapsed.  When a node that DOES
belong to Book A is viewed, Book A's Book menu expands accordingly.
3) The user can also enable Book B & C's block, and have their menus
appear in a block at all times as well.
4) If none of the book's blocks are enabled by the user, the module
will behave just as it did without the patch.  That is, when the "Book
Navigation" block is enabled, the only time any book menu will appear
is when a book node is being viewed.
5) It's important to note (and this was the tricky part to write) that
if both the "Book Navigation" block is enabled and "Book A" is enabled,
they will play nice with each other and not do nasty things like create
the same book menu twice.




------------------------------------------------------------------------

December 9, 2004 - 21:51 : nysus

Attachment: http://drupal.org/files/issues/book_20.patch (5.37 KB)

Andre,


Attached is a new patch that will resolve the problem of the
block-specific stuff showing on the block configuration form.


Let me know if you spot any other bugs.  If it looks good to you, I'll
go to work making the code look leaner and prettier.




------------------------------------------------------------------------

December 9, 2004 - 23:26 : nysus

Attachment: http://drupal.org/files/issues/book_21.patch (4 KB)

Dries, Andre:


Here is a new and improved streamlined version of the patch.  Have a
look if you get a chance.




------------------------------------------------------------------------

December 10, 2004 - 00:11 : nysus

Attachment: http://drupal.org/files/issues/book_22.patch (4.15 KB)

Found a bug in the last version that would cause the block to jump to a
different location.  I think this should do it.  Everything appear to
work well (famous last words).




------------------------------------------------------------------------

December 10, 2004 - 06:49 : andremolnar

Steve:  bugs appear to be gone, and I didn't run across any other
errors.  This is functioning exactly as described.


everyone: I personally would encourage support for this functionality.
Book is a powerful navigation building tool in a site, not only with
its ability to move next and back through a hierarchy of pages - but
also its ability to build the appropriate navigation block without
further user intervention (unlike the admin features in the menu module
or taxonomy).


The most frequently cited complaint about the book module is its
inflexibility when it comes to when and where the block shows up.  I
also frequently hear requests for the ability to show multiple book
blocks at the same time.  Up until now the best alternatives suggested
required users to do a hack (e.g. build a custom block that calls such
and such a hook).  Most abandon their request at that point because its
over their heads.


With this patch all those requests are covered and more.  Now all books
can automatically have their own block and admins can easily decide when
and where each of those individual blocks show up (left right, up down)
and coupled with the new configuration features of the block module -
its very easy for admins to decide on which individual pages a block
will show up.


I would be interested what other have to say about this feature.


My only reservation (which is minor compared to the benefits of the
functionality offered) is that there is no way to turn this
functionality off.  i.e.  The default behaviour is to build individual
blocks for each book.  If there could be a way to toggle this feature
on and off somewhere - it would be perfect.  Still, AS IS - this is a
major improvement and offers great flexibility to admins and site
creators.


andre




------------------------------------------------------------------------

December 10, 2004 - 07:04 : Anonymous

Andre,


Thanks for the feedback on the usefulness of this module.  Glad I could
pitch in and help.


I agree about the inability to turn the feature on/off and I was
thinking about that myself.   I think it could easily be accomplished
by creating a checkbox in the "book navigation" block individual
configuration's settings.  Call it "Enable individual book blocks." 
When enabled, the individual book blocks will appear on the block
administration menu.


One question:  Where would the state of this checkbox get saved?  Has
Drupal moved away from serializing data in the data base?




------------------------------------------------------------------------

December 10, 2004 - 10:36 : Dries

I'm afraid that 'Enable individual book blocks.' is not
descriptive/clear at all.  Are you suggesting a setting to toggle
between 'show block on all pages' and 'show block on book pages only'?




------------------------------------------------------------------------

December 10, 2004 - 11:45 : nysus

Dries,


No.  Andre and I suggest a setting within the "Book Navigation"
cofiguration page, that would toggle whether or not individual books
appear on the list of all blocks on the block administration page. 
Hence the name 'Enable individual book navigation blocks.'  The help
text for this checkbox might read something like: "By default, a book's
navigation block is visible only when a page from that book is being
viewed.  Check this box if you want more control over where and when an
book's navigation block is visible.  You will then be able to control
the book's navigation block location and visibility settings on the
"admin/block" page."


Hope this makes it pretty clear.




------------------------------------------------------------------------

December 10, 2004 - 12:08 : Dries

I understand what you are trying to do, but not how you are trying to do
it, or how the setting is supposed to work.  I guess I'll have to try it
when a new patch lands.




------------------------------------------------------------------------

December 11, 2004 - 01:52 : nysus

Attachment: http://drupal.org/files/issues/book_23.patch (5.02 KB)

Alright, fellas, I'm proud to unveil my crowning achievement in the open
source development world (no big deal to most of you guys but pretty
good for a hack like me).


Thanks for all the input so far.  It's been helpful.  I've streamlined
the heck out of it per Dries suggestion and I've created an option to
turn this functionality on an off per Andre's suggestion.  Does this
look good to you guys?  Anything else I have to fix or improve?


Thanks.




------------------------------------------------------------------------

December 11, 2004 - 05:02 : Dries

I tried the patch. 


It works great but to me, the 'Give books their own block' settings
seems to be redundant.  Why not export the current book navigation
block, along with an additional block for each book?  Looks a lot
simpler to me.


I think I spotted a bug: orphaned book pages (or possibly book pages
that are unpublished) appear to be getting book navigation blocks.




------------------------------------------------------------------------

December 11, 2004 - 09:34 : nysus

I'll see if I can fix the bug.  Might be tricky.


But I don't understand your recommendation to "export the current book
navigation block, along with an additional block for each book".  Can
you expand on this thought?




------------------------------------------------------------------------

December 11, 2004 - 10:06 : nysus

Dries,


I am unable to duplicate the bug.  I have three orphaned pages.  I also
tried unpublishing some pages.  But as far as I can tell, the patch
works as expected.




------------------------------------------------------------------------

December 11, 2004 - 11:00 : Dries

If you can't reproduce the problem, chances are my node/book table is
somewhat fubar.


As for the configuration option.  I suggest removing it and to always
make these new blocks available on the /admin/block configuration
screen.




------------------------------------------------------------------------

December 11, 2004 - 11:52 : moshe weitzman

I am hoping that we maintain the option to keep the behavior where the
appropriate book block only shows up when its book page viewed. this is
a nice, tidy arrangement.




------------------------------------------------------------------------

December 11, 2004 - 12:03 : nysus

Yes, if you don't enable any of the individual book blocks, the a book's
block (i.e. navigation menu) will only appear when a page in a book is
viewed.  In other words, you have the option to have the book block act
like this patch isn't even installed.




------------------------------------------------------------------------

December 11, 2004 - 12:54 : Dries

I guess I'll have to try the patch again, because I don't understand why
it works like this -- or at least, why it can't be made simpler.




------------------------------------------------------------------------

December 11, 2004 - 13:13 : nysus

Can you be more specific?  Why it works like what?




------------------------------------------------------------------------

December 11, 2004 - 13:24 : nysus

Attachment: http://drupal.org/files/issues/book_24.patch (4.1 KB)

This patch reverses a change made in the last patch which required a
user to enable individual book block before they could enable any
individual book blocks.




------------------------------------------------------------------------

December 11, 2004 - 13:41 : andremolnar

As I mentioned earlier I am *fine* with either version of this patch as
long as it makes it to core.


But, as I said earlier, I clearly think the preference for admins would
be to have the option to enable or disable this functionality.


BTW - if this does make it in, I would be happy to create a Handbook
page that describes the new features - something like "how to build
robust site navigation using the book module". (on or after December
17th).


andre




------------------------------------------------------------------------

December 12, 2004 - 04:11 : Anonymous

I am not at all happy with these features. They are incosistant,
confusing and should use exising methods and UIs.
May main concern is the incosistancy: it is confusing, will require
extra attention with each core code change, adds extra logic to the
core, and is not re-useable.


so here are my questions:
1) why do we not use the menu system and apis to build and adminster
the trees? Saves code, does not add extra UIs, and gives users more
power.
2) why do we need that extra showing logic? a book block should not get
exeptional if clauses, it should use the existing path setting methods
on block admin. extra logic is confusing for administrators (hey, i set
the path so that the book-block should show up here, but it does not,
why?) we should really not provide extra logic in the block hook, but
should rather use default settings in block admin (the book could fill
the bookblock sql cells with custom paths, for example)
3) we should avoid extra UIs. We already have far too much, and far too
much different ones. Please rather improve the block admin, than add new
separate interfaces.
4) why do book blocks need al these expeptions in the first place? If
they are so exeptional, we could consider not using blocks, but
something else, like in-line book layout (pages with the index etc)
5) why did you not choose for a general, standard, block gerneation
API? that way modules, such as taxonomy, image gallery, weblinks,
article, etc can reuse it and introduce block gernation.


All that sayd, i like the idea of this functionality, but i fear for a
great useability downfall if we start introducing all sorts of
exeptions for all sorts of modules. Because now chances are very big
that taxonomy, image gallery etc will need to introduce other UIs,
other code, new methods and new documentation, if they too want some
sort of better block handling.


so a -1 from me.




------------------------------------------------------------------------

December 12, 2004 - 04:12 : Bèr Kessels

^^--- That was me (bèr kessels) forgot to log in.....




------------------------------------------------------------------------

December 12, 2004 - 04:34 : nysus

I'm not going to pretend I can argue if my patch does or does not fit
well into Drupal's larger architecture.  My motivation for writing it
is that I had an immediate need to create an easy way to make it easy
for users to create menus.


I'll let others decide whether or not the patch has merit from the big
picture perspective.  But if it doesn't, why not just use it for its
immediate benefits and then throw it away when something better comes
along?




------------------------------------------------------------------------

December 12, 2004 - 05:01 : Dries

My summary is this: +1 on the functionality, -1 on the implementation. 
The code itself is good, but the usability/integration is not.




------------------------------------------------------------------------

December 12, 2004 - 05:13 : nysus

When you say "usability" is that from the user's perspective or the code
maintainers?  I'm guessing it's the latter but I'm unsure.


What about the idea of using the patch until a more permanent solution
comes along?  Yes, it's much better to live in a home with indoor
plumbing but why not use the outhouse while you wait for a toilet to
get installed?  Or are there other considerations I'm overlooking that
would make this a bad idea?




------------------------------------------------------------------------

December 12, 2004 - 05:20 : Goba

nysus it is just generally against the Drupal philosophy to add
improperly implemented functionality until something better comes
along. There even used to be ocassions in Drupal releases, when some
functionality was removed (not fixed) for a release, because its
implementation was not adequate.




------------------------------------------------------------------------

December 12, 2004 - 05:55 : Dries

Usability for the user.  The extra setting on the block configuration
page is both confusing and awkward.  I don't understand why things must
be configured/enabled that way (see my and Ber's previous comments on
this issue).




------------------------------------------------------------------------

December 12, 2004 - 06:03 : nysus

Well, just for the record, I reversed that functionality per your
suggestion and uploaded the patch.  The indiviudal book blocks now
appear automatically.




------------------------------------------------------------------------

December 13, 2004 - 05:56 : Bèr Kessels

Hi,


I am sure you can make not only simpler, but better usefull for admins
and users.
All you need to do is use the menus for this. i.e. make a menu entry
for each book page.


For each book make a menu on level 0, without a parent. that way they
become a seoprate menu, each with an own block.


it saves code, makes things more consistent, and most important, uses
drupal functionality where it should.




------------------------------------------------------------------------

December 13, 2004 - 06:50 : nysus

Ber,


Are you suggesting that for every single book page that a menu item be
created?   That's really not practical.    That was my main motivation
for writing this patch: to make it easy to put links, not necessarily
related to one another, into a block.  Any more pages than 10 and the
sheer tedium of the job would prevent anyone from ever doing that.  The
menu.module is great, but adding new menu items is far from quick and
painless.  I just added about 10 to my menu for different taxonomies on
my site and it wasn't fun.


Plus, if you do as you suggest, there is also the problem of the book
showing up twice.  It will be generated by the menu and then it will be
generated again by the book module which is programmed to design a
block.  You'd have to put some logic in the book.module _block hook to
try to anticipate if a user has enabled a book in the menu.  That
wouldn't be pretty code.


I'm all for putting automatic generation of book navigation blocks as
part of the menu module.  It does make more sense to have it there. 
But it forces me to ask the question: "Then why do we currently have
code in the book module that generates a menu?  Shouldn't that belong
in the menu.module, too?"




------------------------------------------------------------------------

December 13, 2004 - 14:31 : killes at www.drop.org

I think what Ber is trying to say is that you can write a contrib module
that monitors the changes to the book table and creates menu items
automatically. nodeapi is your friend. I would also prefer this
solution.




------------------------------------------------------------------------

December 15, 2004 - 08:39 : Anonymous

""Then why do we currently have code in the book module that generates a
menu? Shouldn't that belong in the menu.module, too?"

"
Because it's old code.  It would be nice if book.module generated this
block using its _menu hook, so that the admin would have a few options
in terms of configuration.


"Plus, if you do as you suggest, there is also the problem of the book
showing up twice. It will be generated by the menu and then it will be
generated again by the book module which is programmed to design a
block.

"
No.  The old code which manually builds a block in book.module would be
removed.  Book blocks would only be generated by the menu.


This would also have the added benefit of allow the administrator to
easily place a book in an appropriate spot in the menu tree, while
still allowing the possibility of displaying it in a separate block. 
Because of menu caching, I don't expect a large performance hit for
creating the menu items.


"That was my main motivation for writing this patch: to make it easy to
put links, not necessarily related to one another, into a block.

"
It sounds like instead of (mis)using book.module, your time would be
better spent in a usability improvement to menu.module so it's easier
to do this.




------------------------------------------------------------------------

December 15, 2004 - 22:55 : nysus

Thanks for the feedback and input.  I appreciate it.  However, I would
also appreciate if you took more care to avoid the condescending tone
in your post:


"It sounds like instead of (mis)using book.module, your time would be
better spent in a usability improvement to menu.module so it's easier
to do this.

"
It's really quite unnecessary and off-putting.  Though it won't stop me
from contributing to Drupal in the future, I'm sure others would be
really turned off by such a patronizing comment and it could dissuade
them.  I'd like the Drupal community to be a welcoming and friendly
place that will inspire people to contribute, not discourage them. 
Thanks.




------------------------------------------------------------------------

December 16, 2004 - 02:07 : Bèr Kessels

nyesus,


Please do not start /that/ discussion here. :) Drupal community is
known fo being direct, maybe because of the big number of
western-Europeans attending, maybe because of other reasons.


No-one commented that you are wasting your time. But the commentor was
telling you somthing likethis:
"If you would follow the previous sugeestions, your added feature would
be much better appreciated, and will probably work much better for you
too".


He/she was by no means telling you to stop your silly coding, or
anything in that line. He/She only wanted to show you the obvious and
better direction.


We often deal with issues that add some feature, and a complete new UI,
because the author does not like, or cannot use the existing UIs and
features. This is nogt good, because if that same author would have
spend his/her time on improving that existing functionality or UI
(improving is not neccesarily the same as extending!!) that code and
time would benefit all much better.
Thats what the commentor tried to say. And so is it here: If you
dislike the way the books handle the blocks, and if you do not want to
use the menu, because you do not like its UI, then do not add another
UI and more features, but rather merge these, and improve the parts (in
the menu) you dislike.




------------------------------------------------------------------------

December 16, 2004 - 02:35 : Dries

We can worry about the menu integration later.  Let's focus on the new
option's usability/interaction design first.




------------------------------------------------------------------------

December 16, 2004 - 06:51 : nysus

I understand what the commenter was saying and like I said, I appreciate
and understand it.  I'm not upset and I'm not looking for an argument, I
was just being direct as well. :)  As part of the Drupal community
(albeit a minor player), all I'm saying is that I would like to see
folks not have a tin ear to the humanity in all of us.  It will help
make Drupal an even stronger community and attract even more talented
developers.


Human interaction is part of the development process. Whether we like
it or not, we must cope and deal with it.




------------------------------------------------------------------------

December 18, 2004 - 01:54 : Dries

I thought some more about this and am starting to believe that
integration with the menu system should take priority.  Here are common
cool scenario's:



* I want to create a separate navigation block for the 'Drupal
handbook'.
* I want to add a menu item called 'handbook' to the user block.  That
is, I want the book navigation to be part of the existing user
navigation block.
* I want to add a menu item called 'handbook' to the top-level
navigation menu.
* 

How would that work from a user's point of view?  What do I have to
click and where to configure this?




------------------------------------------------------------------------

December 21, 2004 - 10:47 : andremolnar

I was actually thinking about the same thing last night (must have been
something in the arctic air).


/
2. I want to add a menu item called 'handbook' to the user block. That
is, I want the book navigation to be part of the existing user
navigation block.
3. I want to add a menu item called 'handbook' to the top-level
navigation menu.
/


This is already possible (to a certain extent) with the current
Book.module and Menu.module - A 'Books' menu item is created in the
user navigation by having the Book.module enabled.  Menu.module allows
you to enable/disable this menu item.  Menu.module also allows you to
re-name this menu item.  But, this only helps if you only intend to
have 1 book (or else the name 'Handbook' is misleading if the user
finds more than 1 book listed). - so this isn't good enough (or is it).


/1. I want to create a separate navigation block for the 'Drupal
handbook'./


This is what I was trying to figure out.  Not just this, but a
different way to do what Nysus was attempting.  i.e. create a menu
block for each and every book that is created.  There is a way to write
code that would (re)build a 'custom menu' on every add/edit/update to a
book page - or book outline update.  Custom menu's automatically have a
block created for them.  But, this I think would be a misleading use of
the 'custom' menu - as the menu would not be custom if they are a part
of core.


So, I would think that two new constants could be added to the menu.inc
file - MENU_BOOK_MENU - and MENU_BOOK_ITEM - each would behave as custom
menu's, but would be reserved for books.  These menu types should NOT
show up in the Menu.module administration - because the administration
of the book_menu items would be  done by administering the book itself
(adding an item, removing an item, moving an item up/down in the
hierarchy, assigning parents etc.).


However, the blocks that the book_menus would create would show up in
the block administration (so users could enable/disable each block -
and decide where on the site they show up).  The existing book block
logic would be removed.


So the logic would be:


If a creates a book in the book administration page - the Book.module
automatically creates a new MENU_BOOK_MENU
Any time a user adds to or updates or delets a book page - the entire
book menu is deleted and recreated based on the hierarchy defined by
the book itself.
The blocks for each book would show up in block administration.


Any thoughts - I know that this doesn't exactly address points 1 and 2
- but it could act as a first step.
Is this approach a bad idea?  It would add special conditions for the
proposed book menu's - but books would be a special case.


Even if people don't like this solution, maybe it will give someone a
better idea.  I'd love to hear them.


andre




------------------------------------------------------------------------

December 21, 2004 - 14:55 : Boris Mann

+1 to this andre


I had promised to put down my thoughts on this matter, as it relates to
1) primary and secondary links and how they are managed and 2)
auto-generation of primary/secondary navigation based on book outlines


So, for 1), we currently have functional-but-not-very-usable plain
textfields to manage primary and secondary links. I would like to see
menu.module used to control all navigation links, whether it is the
navigation block or primary/secondary links. What is needed:
a) default system menus labelled "primary" and "secondary" which would
store; this is where modules could insert navigation
b) support for full URLs (e.g. http://myexternaldomain.com) instead of
just path


2) if we got 1 working, and andre does his book menus, this could get
taken care of automatically. Basically, for brochureware/business/etc.
sites that have static content, you could have a root book as one of
the primary navigation links, and then the secondary links are
generated automatically.




------------------------------------------------------------------------

December 22, 2004 - 13:02 : Dries

I agree with Andre that the book module's integration with the menu
system needs to be worked on.  I support any effort that makes it
easier to structure pages and that makes it easy to link pages/nodes
from within a menu.  


However, I'm opposed to putting book module specific names in the menu
system (eg. MENU_BOOK_MENU and MENU_BOOK_ITEM).  I can imagine a
handful of modules that want to maintain a menu tree (or part thereof)
so I'm in favor of generic names.


I'd have to read up on the menu system code, but last time I checked
there was a MENU_MODIFIABLE_BY_ADMIN flag.  You could choose not to set
this flag for the menu items generated by the book module.  Maybe it's
already possible to implement to implement Andre's suggestion without
having to modify/extend the menu system.


Are you exploring this path?




------------------------------------------------------------------------

December 24, 2004 - 02:01 : andremolnar

I've had a few spare hours to work on this.


I've started to cobble together a solution - but in doing so I
discovered a bug in the menu module (for which I will submit a seperate
issue - if one doesn't already exist).


The principal I suggested works.  I added some code to the book module
that creates custom menu's (MENU_CUSTOM_MENU with MENU_CUSTOM_ITEMs)
for each Book that exists in a site.  This is just as a proof of
concept - I chose this menu type to start with because they
automatically have a block created for them in admin/block (which is
ultimatly the functionality we want).


I ran a test and the menus are created as expected - the blocks are
also created.  But when I tested the menu blocks by enabling them I ran
into a problem.


It seems as though the menu system does not expand/explode sub menu
items if the node type is book.  I'm not sure why this is, and I
haven't traced the source code yet - I thought I would ask if anyone
has intimate knowledge of the menu system if they can point me in the
right direction.


No patch attached because until that problem is fixed this proposed
change won't fly :(


andre




------------------------------------------------------------------------

December 24, 2004 - 03:11 : Dries

Just a wild guess: maybe it doesn't work because the book module's URI
scheme is not hierarchical?




------------------------------------------------------------------------

January 7, 2005 - 02:45 : andremolnar

Attachment: http://drupal.org/files/issues/book_module_1.patch (5.1 KB)

I finally took some time out to do some work on this.  As mentioned in a
post to dev the problem I was having with menus not
expanding/contracting properly was some crud in my database.  Once that
was cleared up my changes worked fine.


I am attaching a patch for comments and for the brave willing to give
it a test drive.


History: This thread and http://drupal.org/node/15198 and
http://drupal.org/node/15153
node/15198 has a patch that is required for this patch to work.


What this does:
Pretty straight forward.
Any time a user adds/updates/deletes book or book pages (including via
outline) - a function is called to create a new menu for each book. 
Any existing book menus are wiped out and then the new book menus are
inserted - and the system menu is rebuilt to reflect the changes.


The menus created consist of type MENU_MODULE_MENU and
MENU_MODULE_ITEM.  These menus show up in the menu/admin page so that
admins can be aware of them, but the menu types are not editable via
menu/admin (all changes are handled by the book module).


Since the menus are in the menu table, the menu_block() hook handles
the creation of the blocks for each of them.  The blocks can then be
administered in the usual ways via the block/admin interface.


KNOWN ISSUE: (suggested solutions welcome)
Since the menu table is updated on every change to books - the blocks
associated with the menus are also recreated with default settings
(i.e. disabled, and with no path or throttle settings) requiring a user
to take an extra step and re-configure the book blocks for viewing on
their site.  I think this is unacceptable.  For the casual user of the
book module that only has a single book that doesn't change often, this
would not be a big deal. But, if anyone wanted to make use of book
module to handle dynamic site navigation this would create more work
than it saves.


Looking forward:
If the block generation issue can be solved in a tidy way, this patch
could allow users to use book to handle all their site navigation
generation needs.
Also, this patch could allow for the removal of a large chunk of code
in the book module dedicated to building its own block via the block
system.  I left it there for now because I suppose there may be those
out there that want to have book.module work the way book.module always
worked (only show the book block when viewing a book page).  Even so,
since each book would have its own block, an admin could specify when
and where the block shows via admin/block.


I would appreciate feedback.  If nothing else I hope this gives someone
some new ideas.
I'll continue to work on the block regeneration issue.


andre




------------------------------------------------------------------------

January 7, 2005 - 02:47 : andremolnar

Attachment: http://drupal.org/files/issues/book_module_2.patch (4.98 KB)

sorry - here's a patch with prefered line breaks.
andre




------------------------------------------------------------------------

January 7, 2005 - 08:47 : nysus

Andre,


I've been meaning to give this a throrough look when I get a chance. 
Hopefully this weekend.


---Steve




------------------------------------------------------------------------

January 19, 2005 - 18:02 : andremolnar

Attachment: http://drupal.org/files/issues/book_module_3.patch (6.66 KB)

Here is an updated patch.


Same comments as followup 51 - except that the known issue has been
resolved.


This changes book module so that any action taken on a book, including
adding new books or book pages will create a menu in the menu system
for that book - and thus create blocks for those menus that can be
administered in the usual ways.


This is my first attempt at a major patch to core - comments are
welcome


I will be happy to update documentation once revisions to the code have
been taken care of.


andre




------------------------------------------------------------------------

January 19, 2005 - 18:53 : andremolnar

Attachment: http://drupal.org/files/issues/book_module_4.patch (6.17 KB)

Sorry - would be nice if I removed some debugging code - ;-)
also previous patch also would have introduced a need for a change to
the menu table that isn't required yet.


This patch is a correct version
andre




------------------------------------------------------------------------

January 20, 2005 - 11:16 : Dries

The menu is recreated every time a book page is updated.  I believe this
is unwanted behavior because it requires the book block to be
reconfigured upon every update.




------------------------------------------------------------------------

January 20, 2005 - 11:32 : andremolnar

The menu is indeed re-created with every book page edit - because if the
book page title changes the menu needs to reflect this change.


The book block re-configuration is not required by the user.  The code
stores this information and re-sets the block settings.


I will see if I can test for 'title change' before forcing the re-build
of the menu - It would save a bit of processing power.


andre




------------------------------------------------------------------------

January 20, 2005 - 12:21 : andremolnar

Took another at this - and it turns out that I already have a check to
see if title or weight change (rather - they already existed in the
module and I used them).


andre




------------------------------------------------------------------------

January 23, 2005 - 18:22 : andremolnar

Attachment: http://drupal.org/files/issues/book_module_6.patch (7.42 KB)

Feedback received indicated that the original block generation code in
this module should be removed - since this patch hands block generation
off to the menu and block system.


This patch removes that code.  BUT - It should be noted, that in order
to have book blocks only show up on pages of node type book - an
additional patch found at http://drupal.org/node/16074 is required.


andre




------------------------------------------------------------------------

January 24, 2005 - 10:36 : andremolnar

Attachment: http://drupal.org/files/issues/book_module_7.patch (7.43 KB)

Yet another patch:


Brings this patch in line with - http://drupal.org/node/16074 (i.e. the
column name change in {block} table)


andre




------------------------------------------------------------------------

January 25, 2005 - 10:56 : andremolnar

Attachment: http://drupal.org/files/issues/book_module_8.patch (7.53 KB)

And another minor patch to cover coding style and variable names.


Just to bring everyone up to speed:
1) Each book and its children pages have a menu created for them (on
any add, edit, delete to a book or book page).
2) Those book menus automatically have a block created for them via
menu_block hook.
3) Block settings are preserved any time there is a change to a book
that requires the menu and its associated block to be re-built.
4)  book_block hook is removed because it is redundant.
5) With the addition of the configuration option in blocks to only show
blocks on certain node types (see: http://drupal.org/node/16074)
administrators have full control over when and where a book block shows
up (including maintaining the status quo of only having book blocks show
up on book pages).


6) This patch does require http://drupal.org/node/15198


andre




------------------------------------------------------------------------

January 25, 2005 - 13:49 : Boris Mann

+1!!


Book-based automatic navigation for corporate/brochureware sites!
Fantastic! Chris Messina, get in here and add a +1 to this.




------------------------------------------------------------------------

January 25, 2005 - 14:26 : Dries

Boris, have you tested this patch extensively, or are you just giving
this +1 based on what you've read?  If you want to see this committed,
take the time to review/test it.




------------------------------------------------------------------------

January 25, 2005 - 21:45 : andremolnar

Yes - please - testers are welcome.


Nysus (aka Steve) has already agreed to give this a test drive when he
had a spare moment.  I hope for some feedback in the near future.  But
if you have a moment Borris I would appreciate it.


OR - If someone would just like to demo this:
http://s92258948.onlinehome.us/greenbeach/
UN: drupaldev PW: drupaldev


Don't mind the mess - it is my test environment and there is a lot of
junk data and settings floating around - but this patch is running
there along with the additional block configuration settings.


andre




------------------------------------------------------------------------

January 31, 2005 - 11:12 : Boris Mann

You got me, Dries...


I have since spent time testing the module on andre's site, and it does
everything I can foresee needing at this point, with no functional
errors.


This functionality alone will make creating standalone sites that are
composed of mainly static pages very, very simple.




------------------------------------------------------------------------

February 3, 2005 - 00:58 : Dries

The demo-site appears to be down.  Bummer.




------------------------------------------------------------------------

February 3, 2005 - 14:59 : andremolnar

Attachment: http://drupal.org/files/issues/book_module_9.patch (7.58 KB)

Sorry - demo site was down while database was being cleaned and latest
CVS modules were being installed (general site maintenence for
testing).


The site is up now with a fresh database and install of Drupal CVS.


UN drupaldev PW drupaldev (has access to manage blocks, books, and
menus to see this patch in action)


Attached is an updated patch to make use of db_rewrite_sql (instead of
node_rewrite_sql).  Also fixes a minor bug that appeared if you were
creating the first book in the site.


andre




------------------------------------------------------------------------

February 3, 2005 - 15:13 : Anonymous

This patch seems to modify the blocks and menu tables directly from
within book.module. (in the new book_build_menu_module_menu function) 
This sets a terrible precedent for other modules.  IMO, these tables
should be modified by functions defined within the block module or menu
module (or menu.inc).  Modifying the tables randomly throughout many
other points in the code makes changes to these tables difficult and
makes troubleshooting problems much trickier.  Let's not sacrafice code
organization for the sake of making the patch as small as possible.




------------------------------------------------------------------------

February 3, 2005 - 22:25 : andremolnar

With regard to the blocks - the block module is doing all the block
building (with the call to _block_rehash) - the only thing that this
code does is preserve block settings (the select sql) before the menu
is updated - and then restores those block settings (with the update
sql).


"Modifying the tables randomly throughout...

"
While I appreciate the point you are making, I would hesitate to call
this random.  After all the menu items being added to the menu table
'belong' to book module.


There is a little bit of a discussion about the best way to go about
doing this sort of thing (i.e. allowing modules to build their own
menus) over at http://drupal.org/node/15198 - which includes the patch
required to make this patch work.  Right now there is no existing hook
or method of doing this.  hook_menu does not have anything in place as
of yet.


I have suggested the introduction of a new hook (name yet to be
determined) that would be in charge of these menu_module_menu type
inserts.  But, I haven't heard any feedback on whether that is a good
idea - or if anyone has a better idea.


Anyone else have thoughts on the approach taken here or suggestions for
a different/better approach?  I'm willing to write the code, I would
just like a little bit of input.


andre




------------------------------------------------------------------------

February 3, 2005 - 22:46 : Dries

I added a test page and all book blocks dissapeared? I also got an SQL
error (check your watchdog messages) upon pressing the 'Submit' button.




------------------------------------------------------------------------

February 4, 2005 - 23:31 : Steven

Doesn't this patch still suffer from the inability to show the menu
block only on the relevant book(s)? I know we can now restrict blocks
per node type, but that still doesn't help with multiple books.


By the way, big code style violation:
$menu_block_settings[$menu_block->path][weight]


"weight" should be surrounded by quotes. Right now it is being treated
as an undefined constant. This is not a good idea. Other than that
there's a bunch of missing spaces... if the code looks cramped, it
usually violates the coding style.


+    $menu_block_settings[$result->path] =
array('status'=>$result->status, 'weight'=>$result->weight,
'region'=>$result->region, 'throttle'=>$result->throttle,
'visibility'=>$result->visibility, 'pages'=>$result->pages,
'types'=>$result->types);


+  db_query('DELETE FROM {menu} WHERE type=%d OR type=%d',
MENU_MODULE_MENU | MENU_MODIFIED_BY_MODULE, MENU_MODULE_ITEM |
MENU_MODIFIED_BY_MODULE);


//restore menu_module_menu block settings


There are several more examples. Please pay attention to this. It's
incredibly annoying to have to fix it later, and it makes the code
harder to read as you cannot make certain assumptions about how it is
layed out.




------------------------------------------------------------------------

February 5, 2005 - 14:56 : andremolnar

I am fixing up the code as we speak.


I actually made a bigger faux pas by not escaping my INSERT sql string
properly - (There is a quick fix, but I understand 'addslashes' is not
good enough for drupal ;-). (Thank you to Dries for catching this right
away on his test of the demo site).


As for multiple books - you actually have more flexibility to enable as
many book menus as you like - not only based on type but also by path.


e.g. Could allow for:
drupal.org/handbook (with some general book menu blocks enabled)
drupal.org/handbook/developer (with developer book menu blocks enabled)
drupal.org/handbook/developer/theme (with theme developer book menu
blocks enabled)
etc. (the sky is the limit).


I will resubmit a patch with all of the coding style fixes requested -
and I will be more careful with the coding style in the future.


andre




------------------------------------------------------------------------

February 5, 2005 - 16:05 : andremolnar

Attachment: http://drupal.org/files/issues/book_module_10.patch (7.7 KB)

Updated Patch,


Implemented code style improvements as per Steven.
Fixed unescaped sql INSERT string (turns out that addslashes is more
than enough in this situation, because the 'title' string has already
been valided and properly inserted into the database before any of this
code ever runs - i.e. this isn't coming directly from user input, but
rather from the drupal database).


Demo site is once again live and welcomes all testers (Thank you again
to those that have already tested this out).


andre




------------------------------------------------------------------------

March 13, 2005 - 14:11 : killes at www.drop.org

Still applies.


Andre: Please create patches from the Drupal root directory.




------------------------------------------------------------------------

March 15, 2005 - 02:42 : Paul Iliano

This is exactly the functionality I have been waiting for. As I can see
many uses for showing a book menu on all pages, I never really
understood why book menus could only be shown on book pages.


I'm still at DP 4.5, but as soon as 4.6 is out I will install and try
it out. I'd love to see this kind of functionality
in core!




------------------------------------------------------------------------

March 17, 2005 - 23:43 : Steven

Your visibility 'fix' requires that the entire handbook has clean,
hierarchical URL aliasing. This is often not the case.


I understand that for sites where the book is used to organise the main
structure, you might want the block visible everywhere. But it is not
good for sites where this isn't the case, like Drupal.org itself.




------------------------------------------------------------------------

April 3, 2005 - 09:12 : Paul Iliano

As Steven says, for some type of sites (like perhaps drupal.org), it
could not be desirable to show book menus on all pages. But for other
sites it could be very much wanted.


It seems to me a good solution would be to let administrators simply
choose which node types they want book menus to appear on, like we
currently can opt to switch off author/date info per node type.




------------------------------------------------------------------------

April 3, 2005 - 14:49 : factoryjoe

In general, +1 on the auto-updating aspect of this. It does seem to be a
welcome improvement to the book system, though I question Boris’
assertion that this is really a good solution for “brochure-ware”
sites.


For one thing, when I design a site, no matter who I am, I highly doubt
that I would think “ah ha, make a book to contain the pages of my
site... and the navigation will be generated from it!” While the
functionality is pretty much spot-on, the name is not. So what we end
up with is an overloaded book module or worse, a misnamed module.


I also wonder about moving the book-generated menus around. For
example, the way I would like this patch to work is for there to be
top-level “chapters” (like sections of a website) and then book
pages within each section, representing the individual pages. I would
like to be able to put the “chapters” horizontally in the header of
my site (like on OurMedia.org [1]) and then have the pages show up in
the sidebar when you navigate to each section. I guess I just wonder
about the flexibility of this approach and whether or not it will serve
the functional needs that Boris thinks it might. What if I want the page
titles to be different from the menu link titles? It doesn't seem that
this is something I can control with the current partial menu
integration.


Anyway, with a specific eyes towards improving book navigation, I do
agree that it functionally looks pretty good.


I did find one serious bug and one major usability issue. It has to do
with integration with the menu system. Andre will hate me for this, but
I clicked through the “reset menus” command in the menu system.
Doing so wiped out all the book navigation menus. If these menu items
were really “locked”, then why were the book menu items wiped out?
How do I restore them?


As for the usability issue, it is unclear to me where I would go
reorganize my book-generated navigation menus. I looked in menus, where
it should logically exist, but everything was locked. Does this mean I
have to go to each individual node to sort my content?


[1] http://www.ourmedia.org/




------------------------------------------------------------------------

April 5, 2005 - 15:24 : menesis

>From what i see on demo site, there is no way to configure the site to
act as it does now in case of multiple books - show book navigation
block only for current book. I could only configure a block to show up
on any book page, but it is shown while viewing other books, too.


IMHO the preferred way to modify a module is to introduce new
functionality while keeping it's behavior without any extra
configuration. In this case, when creating a new book, a menu would be
created, the block enabled, and configured to show up only on pages of
that book.


Visibility by path will not work, because all book pages have url like
node/1653 by default, need a block setting for that (true="Show on any
book's pages", false="Show only on current book's pages", false by
default). The tricky part is that menu module, which provides the block
and it's configuration, does not know which book is being displayed.




------------------------------------------------------------------------

April 17, 2005 - 13:38 : bobo

For those of us without linux, can someone please add the latest patch
to the Drupal 4.5 book.module. I would like to use it asap for a
website I'm creating for an animal welfare group. This is really cool,
I hope you guys find a way to get it put into the latest version of
Drupal. It should be a core peice of code. It seems strange to me that
an option to click wether or not you want a book to display on the main
page doesn't exist...


Bobo




------------------------------------------------------------------------

April 18, 2005 - 09:23 : bomarmonk

This functionality seems crucial to completing the organizational
website that I have developed with Drupal.  Yet, I've applied the
book.module and menu.inc patches to Drupal 4.6 and can't seem to get by
book blocks to display on the front page.  Why not?  Is it because I'm
using the front_page.module?  I'm still using a themed drupal page for
the front page.  I definitely need help with this.




------------------------------------------------------------------------

April 20, 2005 - 09:45 : andremolnar

It occurs to me, as I finally dive back into this, that the main issue
is that people want BOTH the new way of handling blocks (because of
greater flexibility of putting a book block anywhere they like) AND the
old way (because people have sites where they only want to book block to
show up in the current book's nodes - at the exclusion of all other
books).


At some point in the patch history, both options were available by
simply leaving book.module's own block generation code intact AND
implementing the new code that inserted items into the menu system and
let menu.module handle block creation.


This was deemed to be bad.  (The argument being that there shouldn't be
two sections of code generating blocks for one module.  Essentially
duplicating each other's efforts).  The good news is that in an attempt
to address the issue I added a welcome configuration option to the
block.module - but it wasn't enough to REALLY solve the problem.


As menesis pointed out, the problem is that when the block generation
is handed off to the menu module, the menu module doesn't have any way
of knowing that the blocks it is generating based on the menu structure
are 'books' - and hence there is no way to know that a particular book's
navigation block should only show up in a particular book - it simply
becomes a block like any other block and must follow the same rules.


Quite frankly I think people should just suck up the fact that in order
to move forward and offer improved functionality some other
functionality is deprecated.  But, I suspect that that argument won't
fly in this case - its just too big a paradigm shift *wink*.


All kidding aside, I am going to try and find a solution.  In the mean
time a REAL issue was raised by factoryjoe when he noticed the blocks
could be wiped out simply by 'resetting' menu's in the menu admin. 
This is NOT desired and should be reasonably easy to fix by telling
menu module not to dump menu's generated by modules during a 'reset'.
{And no joe I didn't mind you messing up the blocks on the demo site -
it raised a very valid problem}.


If anyone is interested I am going to be placing pre-patched files in
my sandbox - so if people like the new functionality despite losing
traditional book block functionality they can just download the
pre-patched files.  And if people want to monkey with the code and
contribute solutions there is a place to do it.


http://cvs.drupal.org/viewcvs/drupal/contributions/sandbox/andremolnar/book-menu/


More to come.


andre




------------------------------------------------------------------------

April 28, 2005 - 07:43 : bomarmonk

Andre,


I really appreciate the work you and others have put into making the
book module and menus/blocks  better.   I am fairly new to PHP, mySQL,
Drupal etc., but I would like to offer some suggestions anyway (even if
they are a bit naive).  I have tested the patched versions of menu.inc
and book module and would like to offer my support for the following
added functionality:


1) Have support to allow or disallow the root page of the book in the
navigation block (this would definitely be desireable for many using
book blocks for hierarchal menus).  


      a) However-- another desired (more useful?) behavior might be to
not display the currently viewed
          book page whether it is the root page, second page, third
page, etc.  Food for thought.


2) Allow individual book blocks to behave in the traditional manner, or
to enable certain book blocks to show up on every page (as site
navigation).  


3) This feature would also be complemented by the ability to show
navigation blocks for sections or chapters within a larger book.  This
way, you could create a "master" book with a larger table of contents
(providing an index of book titles) and still allow concise, focused
navigation within the chapter nav blocks.


Again, I am sorry If I've repeated anything I've already said in
another post (a little double posting), but I felt this was the best
place to sum up some of the functionality I feel is currently missing
from the book module.  Since I am a novice, feel free to correct me or
give me verbal lashings.  I can take it.




------------------------------------------------------------------------

April 29, 2005 - 07:29 : mcduarte2000

I also have one desire...


I wanted an option to expand completly the menu block to the 2nd or 3rd
level. Not only the section the user is currently in, but all the
sections.


This would be great to be able to use it as well as site navigation.
And I believe is not difficult to implement.


Regards,


Miguel




------------------------------------------------------------------------

May 1, 2005 - 07:57 : Dries

I committed a change to the block module that lets people use PHP to
specify when a particular block should show up.  So if you make it so
that the book blocks show up on _every_ page (like all other blocks),
administrators can still use PHP to limit their visibility.  Showing
the book block on every page (unless instructed otherwise) makes for
improved consistency and is more likely to match the administrator's
expectations.  Mind to take a look at this to see how this would affect
the proposed patch?  Let us focus on getting the right blocks in core,
and worry about their visibility later.




------------------------------------------------------------------------

May 1, 2005 - 10:23 : andremolnar

The normal behaviour of these blocks is to show up everywhere by
default.  So we are on the right track.


I am going to have to bake a new patch if there are changes to the
block module (particularly new settings).  More to come.


andre




------------------------------------------------------------------------

May 4, 2005 - 08:01 : andremolnar

Attachment: http://drupal.org/files/issues/book_module_11.patch (12.26 KB)

Okay,


I finally had a minute to update this patch.


The latest patch - does everything that the previous patches did plus:


The menu.module is modified slightly so that "reset menu" doesn't wipe
out menu's generated by the book module.  It only kills changes to the
default navigation menu and other custom menu's defined in the
menu.module admin interface.  FactoryJoe (chris) found this bug in the
last version - thank you for that.


While I was at it in the menu.module:  Since the book module menus are
wiped and re-built with every change to a book I had to remove the
option of adding 'custom' elements to these menus (or else people would
loose those custom items with every change to a book).  I did this
simply by not including MENU_MODULE_MENUs in the option list that is
generated.


I've gone ahead and created a patch from the root which also includes
the patch required to menu.inc


I will be placing pre-patched files up in my sandbox if people want to
test that way - or you can always take a look at the demo site and try
this out.  (I recently updated the demo site to the latest changes in
CVS/HEAD).


As dries pointed out there is a change to the block.module that will
allow anyone to add some PHP logic to handle when/if a block shows up
on a site.  Hopefully that change is sufficient to address people's
concerns about the way book blocks used to show up.


Looking forward to people's comments.


andre




------------------------------------------------------------------------

May 4, 2005 - 08:07 : andremolnar

Attachment: http://drupal.org/files/issues/book_module_11_0.patch (12.26 KB)

Okay,


I finally had a minute to update this patch.


The latest patch - does everything that the previous patches did plus:


The menu.module is modified slightly so that "reset menu" doesn't wipe
out menu's generated by the book module.  It only kills changes to the
default navigation menu and other custom menu's defined in the
menu.module admin interface.  FactoryJoe (chris) found this bug in the
last version - thank you for that.


While I was at it in the menu.module:  Since the book module menus are
wiped and re-built with every change to a book I had to remove the
option of adding 'custom' elements to these menus (or else people would
loose those custom items with every change to a book).  I did this
simply by not including MENU_MODULE_MENUs in the option list that is
generated.


I've gone ahead and created a patch from the root which also includes
the patch required to menu.inc


I will be placing pre-patched files up in my sandbox if people want to
test that way - or you can always take a look at the demo site and try
this out.  (I recently updated the demo site to the latest changes in
CVS/HEAD).


As dries pointed out there is a change to the block.module that will
allow anyone to add some PHP logic to handle when/if a block shows up
on a site.  Hopefully that change is sufficient to address people's
concerns about the way book blocks used to show up.


Looking forward to people's comments.


andre




------------------------------------------------------------------------

May 4, 2005 - 08:13 : andremolnar

Whoops sorry for the double post there - not sure what happened.


Just wanted to correct myself - I'm not going to put the pre-patched
files in my sandbox.  I already decided that wasn't a good idea for CVS
stuff anyway or else I would have to constantly update it.


BUT - the demo site is live if you want to test it out there.


andre




------------------------------------------------------------------------

May 4, 2005 - 11:00 : Steven

Dries: while having a piece of PHP is certainly flexible enough, it is
far from user-friendly.


Ideally we could have each module define custom visibility options for
its menus. Then book.module could have a toggle between "always show
block" "only show on its book pages".




------------------------------------------------------------------------

May 4, 2005 - 12:11 : andremolnar

Steven just reminded me of something - something which hasn't got much
discussion (and I had completely forgotten about since this patch
process started so long ago).


The change to menu.inc to allow for a menu type of MENU_MODULE_MENU and
MENU_MODULE_ITEM were generic name choices to offer future flexibility
for other modules to define menu's in some way (not unlike what this
book patch has done).  Currently though, I have no code to check which
module created the menu items.  For now, that doesn't pose a problem
because book module would be a first - but if other modules decide to
do something similar (say contrib modules) - there needs to be a way to
distinguish module_menus from one another so they don't step on each
other's toes.


This is simple enough to fix - just an extra field in a table - and an
extra field check in the code.  The question is 'where should the extra
field be - and what should it be called'.


I think a 'module' field in the menu table seems like the obvious
choice - but I'd like to hear what everyone has to say.


andre




------------------------------------------------------------------------

May 5, 2005 - 00:56 : Dries

I had a look at this patch and ...


1. In the PHPDoc I read: /"Do not return from hook_menu()
implementations."/ (two occurrences) but I have no idea what this
means.


2. How about we rename book_build_menu_module_menu() to
_book_rebuild_menu()?


3. IMO, it is slightly better to centralize all calls to
book_build_menu_module_menu() in book_nodeapi.


4. I don't like book_build_menu_module_menu().  While it is good code,
it fiddles with menu system internals, manipulates the {menu} table,
etc.  I can't think of a better solution though.


5. I don't think the use of addslashes() is appropriate here.  Are you
trying to prepare strings for use in a SQL query?


6. Are these /mega INSERTs/ ANSI SQL or are these an MySQL-ism?


7. It is better to populate an array, and to implode(', ', $inserts)
it.  Like that, you don't have to fix things up with rtrim($tree, ',
').


8. Is there a particular reason we can't use dynamic menus (eg. in the
!$may_cache-clause in book_menu())?




------------------------------------------------------------------------

May 5, 2005 - 08:01 : andremolnar

"1. In the PHPDoc I read: "Do not return from hook_menu()
implementations." (two occurrences) but I have no idea what this means.

"
I took my cue from the PHPDocs for MENU_CUSTOM_ITEM and
MENU_CUSTOM_MENU which say the same thing, and I understood to mean...
"Don't try to make this kind of menu/item via the menu hook of your
module."  - Which is what I mean in this case.


"2. How about we rename book_build_menu_module_menu() to
_book_rebuild_menu()?

"
Sure thing


"3. IMO, it is slightly better to centralize all calls to
book_build_menu_module_menu() in book_nodeapi

"
I'm not sure that I follow (which does not mean that i'm not sure this
is right).  From the drupaldocs "...do not use [_nodeapi] to perform
actions on your type of node alone. Instead, use the hooks set aside
for node modules, such as hook_insert()..."  


Are you saying that its preferable to do:


function book_nodeapi (&$node, $op, $teaser, $page) {
switch ($op) {
case 'insert':
  book_build_menu_module_menu();
//..


But, wouldn't that run the code on ALL node inserts (and updates and
deletes)?  I don't think we want to do that.  But I am not a guru - can
someone help me grasp this - I might be too thick to understand the
nodeapi hook.


"4. I don't like book_build_menu_module_menu(). While it is good code,
it fiddles with menu system internals, manipulates the {menu} table,
etc. I can't think of a better solution though.

"
I think the only other solution requires a whole new hook that handles
this specific type of transaction in a standardized way.  I agree that
its a bit 'wrong' to be mucking with menu system and the block system
willy nilly from a module - but without such a hook, I couldn't see
another way to accomplish what needs to be accomplished here given the
current drupal API.


"5. I don't think the use of addslashes() is appropriate here. Are you
trying to prepare strings for use in a SQL query?

"
All I need done with add slashes is to escape the 'title' strings for
use in the SQL insert.  These strings have already been validated (they
are coming from straight from the DB - NOT from user input).  Is there a
preferred meathod?


"6. Are these mega INSERTs ANSI SQL or are these an MySQL-ism?

"
I can't find anything that says this is ANSI 92/99/ or greater... BUT -
it is supported in MySQL and Postgres (and possibly DB2 and some MS)
(someone correct me if I am wrong).  The reason I went with this syntax
is because of the performance boost on MySQL:  see
http://dev.mysql.com/doc/mysql/en/insert-speed.html


Clearly this can be turned into a series of inserts in a loop, but I
was trying to be conscious of the impact of this code on a site with
large books that are updated regularly.


"7. It is better to populate an array, and to implode(', ', $inserts)
it. Like that, you don't have to fix things up with rtrim($tree, ', ')

"
Both work - I'm not sure which is better.  What is the overhead of an
array and an implode call - vs. a string that has a single character
stripped off the end?  The first is potentially more flexible - but I
think that latter is quicker (sorry can't back that up with a
benchmark, but I'd be willing to bet $1CDN).  Regardless, I'm okay with
such a change if everyone thinks its better.


"8. Is there a particular reason we can't use dynamic menus (eg. in the
!$may_cache-clause in book_menu())?

"
This is a very good question.  I will have to investigate.  I quite
frankly have no idea how the dynamic menu type works...  If its the
right tool for the job I'm happy to use it - Would that address Point
#4?  If it is the right tool and does address point #4 you will see it
in the next patch.




------------------------------------------------------------------------

May 5, 2005 - 08:12 : Steven

RE: addslashes, you should use the normal db_query() mechanism for this.
Building queries like you do is a bad idea because, even if it is safe
in one particular instance, it sends a very bad signal to others.


Build the query string with placeholders in it (%d, %s), and put the
arguments in an array. Pass the array as a single argument to db_query:


db_query("UPDATE ....", $parameters);







More information about the drupal-devel mailing list