Академический Документы
Профессиональный Документы
Культура Документы
Attendee Guide Prepared for: EDT502, Fall 2007, Dr. Savenye Prepared by: Jeff Beeman November 26, 2007 EDT502 Final Project
Table of Contents
Introduction
Program Content and Purpose
Program Objectives
Getting Started
3 3 3 4 5 5 6 9 9 11 12 13 13 15 16 17 18
Appendix: Resources
18 20 21
Introduction
Program Content and Purpose
Drupal provides an elegantly designed and powerfully implemented mechanism for storing content as extensible, modiable objects with various properties called nodes. Every major release of Drupal contains many enhancements and new features but the node system, at its core, has seen very little change due to its straightforward and simple design. For this very reason, a strong understanding of how Drupals node system works is important to understanding Drupal itself, both as a developer and an administrator. It can, however, be difcult to understand just how nodes work. In particular, administrators and developers tend to have a difcult time wrapping their heads around the ways in which Drupal modules can modify the node structure. This session is an important step for any potential Drupal developer to quickly get up to speed with what is arguably Drupals most important feature - its node system. Many potential Drupal developers have used the node system for years either without knowing it, or without fully understanding it. An understanding of the basic features of Drupals node system, how and when nodes are modied, and being able to identify where and when that modication happens are key objectives to becoming a better Drupal developer. This session helps lay the foundation required for Drupal developers to write modules and themes that work with Drupals node system.
Program Objectives
This workshop for potential and current Drupal developers presents an overview of Drupals node structure in easy to understand terms; provides attendees with useful tools for inspecting the structure of a node; and gives attendees the knowledge required to identify where and when nodes are modied.
Getting Started
You are participating in an overview of Drupals node system. The term node, in Drupal, refers to any piece of content within the site. When youve worked with Drupal before, any time youve created a new story, page, blog entry, or forum topic, you were creating a node. You probably recognized that each of those pieces of content had some things in common. In spite of being different types of content, they each had authors, titles, created times and body text. What else is common about them? How do different node types behave differently in Drupal? This session has been built as an exploration of Drupals node system. Understanding just how Drupals exible node system works and uses or adds to attributes of nodes can save you hours of development and debugging time when you are working on modules or themes for Drupal. After this session you will be able to: list the key attributes of a node, state what mechanism can be used to discover all the attributes of a given node, explain how hook_nodeapi and hook_form_alter can alter a nodes structure To help you get more hands-on with the material, a demo site has been setup specically for this session. Once your instructor has provided you with a URL, username and password for the site, please log in to the site. If you are going through this material on your own, it is assumed that you have administrative access to a Drupal installation and the ability to add new modules to the web server.
Practice
You will now practice creating some content and identifying the key attributes of the resulting nodes.
Navigate to Create Content and create a new story. Choosing to create a story node has cause Drupal to set the new nodes type to story.
Enter a title for the node and expand the Authoring Information rollout. Youll see you can set the author name, which references the uid (numeric user ID) of the author, and the Authored on time, which is the created date of the node. Complete the form and press Submit to create it.
On the resulting page, nd and note the key attributes of your new node, including the node ID, title, created date and author.
Repeat the process of creating a node a couple more times. Each time you create a new node, pay special attention to the ve key attributes of the resulting node. 1
The node type is not displayed on the resulting page. The next topic will show you how to discover this and many
2 3
The devel module can be downloaded from http://drupal.org/project/devel A tutorial covering module installation is available at http://drupal.org/handbook/customization/tutorials 9
Check the box next to the Devel module and save the conguration
10
11
As you can see, the display is essentially the raw data of the nodes contents. With the devel module, you can quickly and easily see attributes that would otherwise be more difcult to nd, such as the node ID and node type.
Practice
Using the steps below, view the attributes of various nodes you have created on the site. 1. 2. 3. 4. Using the node ID of one of the nodes you created in the previous section, navigate to that node. Click on the Dev load tab visible on the page. Locate the node ID, type, title, created date, and author. Find the nodes body text and changed dates.
12
Creating a vocabulary
During the session, the instructor will create the vocabulary for you, but on your own site you can follow the instructions below. 4
Go to Administer -> Content Management -> Categories and choose Add Vocabulary
You can learn more about taxonomies and their various congurations by clicking on more help on the categories
Enter Story tags into the Vocabulary name eld, check the box next to Story under Types, check the box next to Free tagging, and submit the form to create the vocabulary.
14
Introducing hook_form_alter
Now that a vocabulary has been assigned to the Story node type, edit a story node that you created earlier. The resulting form is a modied version of the form you used to create the node before. You can now see a eld labeled Story tags that allows you to enter a comma-separated list of terms describing the story. This eld was added to the node editing form through a programmatic method called hook_form_alter. There are many Drupal methods, called hooks, that follow a standardized naming convention which any module can implement. These hooks allow modules to act upon various events that occur when a Drupal page is loaded. They are useful enough for an entire session of their own, but what is important to understand about them in this case is that the taxonomy module contains a method called taxonomy_form_alter, which is the taxonomy modules implementation of the hook called hook_form_alter. This hook allows any module to modify any form that Drupal generates. In this instance, the taxonomy module takes the node edit form and modies it to add the Story tags form element. Doing so allows users to add terms to the story. Heres how it works:
Add a few terms to the Story tags eld and submit the changes.
On the resulting node page, you can see the terms displayed.
15
Click on the Dev load tab. Find the taxonomy property of the node and you will see that the terms you entered are in the resulting array of data.
Introducing hook_nodeapi
As you saw, the Story tags form element on the node edit form was put there through the taxonomy modules implementation of hook_form_alter. While the form alter hook is vital in that it allows your module to present form elements and information to its users, thats the only thing that it does. In this case, hook_form_alters only purpose is to modify a form and present form elements and controls to users. You can see, by using the devel module, that tagging the node you created earlier with terms through the taxonomy module resulted in a structured array of data being attached to the taxonomy attribute of the node. Drupal had to process that data so that it could be saved, loaded and viewed on the resulting page, and hook_form_alter is not the preferred way to do so. Fortunately, there is another hook available to you called hook_nodeapi. This hook provides many operations that can be called in the process of creating, updating, viewing, and deleting nodes, as well as in several other useful contexts. For example, when a node is created, the insert operation, or op, of hook_nodeapi is called. In this case, when taxonomy_nodeapi is called with the insert op, it is given the full node, including the form data that was submitted. The taxonomy module then takes that data and saves it into its database tables. A similar set of events happens when a node is edited and saved. Take a look at the code below for taxonomy modules implementation of hook_nodeapi. Try to nd where the module handles loading and updating node data. Drupal Node Overview
16
Taxonomy modules implementation of hook_nodeapi function taxonomy_nodeapi($node, $op, $arg = 0) { switch ($op) { case 'load': $output['taxonomy'] = taxonomy_node_get_terms($node->nid); return $output; case 'insert': taxonomy_node_save($node->nid, $node->taxonomy); break; case 'update': taxonomy_node_save($node->nid, $node->taxonomy); break; case 'delete': taxonomy_node_delete($node->nid); break; case 'validate': taxonomy_node_validate($node); break; case 'rss item': return taxonomy_rss_item($node); case 'update index': return taxonomy_node_update_index($node); } }
Practice
1. 2. 3. 4. 5. 6. 7. Go to the form for creating a new story node What is the name of the hook that inserts the Story tags text eld? Finish creating the new node by lling in and submitting the form. What hook is called when you submitted the form that saves the Story tags data? What hook is called to helps display the tags when the resulting node is shown? Click on the Dev load tab. What hook is called to pull in the taxonomy term data that you entered?
17
Appendix: Resources
Node attribute denitions
The following chart denes each node attribute available in the core Drupal installation. Keep in mind, when you are looking at your own site, that community modules may load additional attributes into a node. Please see the modules documentation or code for information on those attributes. Some core modules use alternative methods not covered in this material to either create new node types or to modify the node structure (i.e. forum module). Some of these methods are not necessarily recommended over the methods presented in this session and may still be used because of reliance on legacy code. nid vid The unique node ID. The unique revision ID for the node. This allows Drupal to store revisions of node data. type status created changed comment The type of the node (i.e. story, blog, page, etc.). Whether or not the node is published. 0 means unpublished, 1 means published. The time the node was created, stored as a Unix time stamp. The time the node was last changed, stored as a Unix time stamp. The comment status of the node. 0 means comments are disabled, 1 means comments are now read-only, 2 means comments can be read and written. promote Whether or not the node is promoted to the front page. 0 means un-promoted, 1 means promoted. sticky Whether or not the node should be listed at the top of lists of content, regardless of publish date. 0 means un-sticky, 1 means sticky. revision_timestamp title body teaser log format The time the nodes last revision was created, stored as a Unix time stamp. The title of the node. The raw content of the nodes body eld. The Drupal-processed teaser of the nodes body eld content. The log message associated with the last revision of the node. An integer representing the ID of the input format lter that should be used when rendering the nodes content. uid The unique user ID of the author of the node.
18
The username of the author of the node. The path to the user avatar of the author of the node. Other, miscellaneous data stored in the node. Some modules occasionally use this eld, but it is not generally used for vital node information.
last_comment_timestamp
Used by the comment module to dene the time the last comment was left on the node. By default, it is set to the creation time of the node.
last_comment_name
Used by the comment module to dene the username of the author of the last comment on the node.
Used by the comment module to dene the total number of comments on the node. Used by the taxonomy module to dene an array of terms associated with the node. The primary taxonomy term ID for a forum node. This denes the forum in which the node is contained.
Used by the book module to dene a hierarchical structure for nodes. Used by the book module to dene a hierarchical structure for nodes. Used by the path module to dene a URL alias to the node. Used by upload module to list les attached to the node.
19
hook_nodeapi
modules
hook_nodeapi("load")
Editing node?
Viewing node?
hook_nodeapi("prepare")
hook_nodeapi("view")
hook_form_alter
modules
20
Useful Links
Website for this session http://edt502.jeffbeeman.com Devel module project homepage http://drupal.org/project/devel Pro Drupal Development http://www.drupalbook.com Intro to developing Drupal modules http://drupal.org/node/292 Overview of Drupal hooks http://api.drupal.org/api/group/hooks/5 API Documentation for hook_form_alter http://api.drupal.org/api/function/hook_form_alter/5 API Documentation for hook_nodeapi http://api.drupal.org/api/function/hook_nodeapi/5
21