[documentation] [task] Documentation for hook_install

[hunmonk]

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

 Project:      Documentation
 Version:      <none>
 Component:    Developer Guide
 Category:     tasks
 Priority:     normal
 Assigned to:  Anonymous
 Reported by:  drewish
 Updated by:   hunmonk
-Status:       fixed
+Status:       patch (code needs review)
 Attachment:   http://drupal.org/files/issues/install_php.patch (3.01 KB)

@yktdan: the reminder shouldn't go in the hook doc, but on in the
'upgrading to drupal 4.7' section of the drupal handbook.


i found this doc to be just a bit confusing, so i've attached a patch
which i think makes things a bit more clear.  i removed the PHP
heredoc, which i've never seen used in any drupal table creation
statements before--it definitely threw me off for a sec.  :)  also
cleaned up the spacing.


while playing with the install hook last night to get it working for my
modules, i discovered that you can do lots more w/ it than just install
db tables.  the function is called from a full bootstrap, and even the
functions of the module that was just enabled are available!  i figured
this would be a nice thing to note in the doc, so it's added as well.




hunmonk



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

Thu, 09 Feb 2006 20:32:41 +0000 : drewish

Attachment: http://drupal.org/files/issues/document_install_hook.patch (1.88 KB)

Here's some initial docs for the newly committed hook install [1].
[1] http://drupal.org/node/46422




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

Thu, 09 Feb 2006 22:06:59 +0000 : drumm

the mysql is missing the {} and I'm not so sure about the heredoc
strings, we don't really use those anywhere now.




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

Tue, 14 Feb 2006 22:28:46 +0000 : Jaza

My only concern is site admins dealing with complex multisite setups,
where multiple database prefixes are involved. This documentation needs
to include a comment to such people, that if they want the tables
created by hook_install() to use a prefix other than the default one,
they must specify this in the relevant settings.php file *before*
enabling the new module.


Perhaps we should also recommend that module developers list all tables
in their module's installation instructions, along with instructions for
custom prefixing.




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

Tue, 14 Feb 2006 22:48:52 +0000 : drewish

Attachment: http://drupal.org/files/issues/document_install_hook_0.patch (1.99 KB)

drumm, I added the {} to the MySQL case and a node that all tables need
the curly braces so prefixing works correctly. You're right that we
don't use the HEREDOC format much but it really makes it easier to
paste in the SQL and to read it. 


Jaza, you're right that this should be documented, but in the docs for
end users, not developers. I think most people who'll be using the
prefixes will set those up before downloading and enabling contrib
modules. At that point all the tables created will have the proper
prefixes. If a user need to change them later, they can open up the
.install file, look at the module_install() function and see a list of
the tables created.




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

Wed, 15 Feb 2006 03:45:48 +0000 : drumm

Looks good.


Whenever this happens go ahead and cvs rm update.php, mv update.php
install.php, cvs add install.php.




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

Wed, 15 Feb 2006 20:42:06 +0000 : drewish

This has been committed. The file was renamed as drumm suggested.




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

Tue, 21 Feb 2006 06:14:21 +0000 : yktdan

There needs to be a reminder somewhere to fix README.txt and/or
INSTALL.txt in modules so that don't tell you to run the .mysql file
which isn't there any more, e.g. event.