drupal node overview - jeffbeeman.com node overview... · 2011-01-13 · drupal node overview 8 1...
TRANSCRIPT
Drupal Node Overview
Attendee Guide
Prepared for: EDT502, Fall 2007, Dr. Savenye
Prepared by: Jeff Beeman
November 26, 2007
EDT502 Final Project
Table of Contents
Introduction 3
Program Content and Purpose 3
Program Objectives 3
Getting Started 4
Thinking of nodes as objects 5
Key attributes of nodes 5
Practice 6
The devel module 9
Enabling the devel module 9
Using the devel module 11
Practice 12
Modifying the node structure 13
Creating a vocabulary 13
Introducing hook_form_alter 15
Introducing hook_nodeapi 16
Practice 17
Appendix: Resources 18
EDT502: Jeff Beeman
Drupal Node Overview 1
Node attribute definitions 18
Understanding hook_nodeapi and hook_form_alter 20
Useful Links 21
EDT502: Jeff Beeman
Drupal Node Overview 2
Introduction
Program Content and PurposeDrupal provides an elegantly designed and powerfully implemented mechanism for storing content as extensible,
modifiable 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 Drupal’s node system works is important to understanding Drupal
itself, both as a developer and an administrator. It can, however, be difficult to understand just how nodes work. In
particular, administrators and developers tend to have a difficult 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
Drupal’s 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 Drupal’s node
system, how and when nodes are modified, and being able to identify where and when that modification 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 Drupal’s node system.
Program ObjectivesThis workshop for potential and current Drupal developers
• presents an overview of Drupal’s 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 modified.
EDT502: Jeff Beeman
Drupal Node Overview 3
Getting StartedYou are participating in an overview of Drupal’s node system. The term node, in Drupal, refers to any piece of content
within the site. When you’ve worked with Drupal before, any time you’ve 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 Drupal’s node system. Understanding just how Drupal’s flexible 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 node’s structure
To help you get more hands-on with the material, a demo site has been setup specifically 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.
EDT502: Jeff Beeman
Drupal Node Overview 4
Thinking of nodes as objects
Drupal nodes are objects that have properties. Objects are just like any physical object in the world. For example,
automobiles have a type, like sedan, sport utility vehicle, truck or van. They also have a make, like Toyota, Ford or
General Motors. They are usually made in a year, such as 2006, and have other properties like exterior color, interior
color, engine type and engine size. Drupal nodes, although virtual, are similar to any other physical object. They have
many properties, just like an automobile. Some of these properties are vital to a node’s existence.
Key attributes of nodesNode ID: The unique, numeric identifier of each node, also known as nid. Every node in Drupal can be accessed
through a URL following the pattern example.com/node/x, where x is the node’s ID.
Type: The type of the node. Common types include Page and Story.
Title: The brief title of the node.
Created date: A time stamp indicating when the node was created. This is stored in the database as a Unix time
stamp.
Author: The ID of the user who created the node, also known as uid.
EDT502: Jeff Beeman
Drupal Node Overview 5
PracticeYou will now practice creating some content and identifying the key attributes of the resulting nodes.
EDT502: Jeff Beeman
Drupal Node Overview 6
Navigate to Create Content and create a new story. Choosing to create a story node has cause Drupal to set the new node’s type to story.
EDT502: Jeff Beeman
Drupal Node Overview 7
Enter a title for the node and expand the Authoring Information rollout. You’ll 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.
Repeat the process of creating a node a couple more times. Each time you create a new node, pay special attention to
the five key attributes of the resulting node.1
EDT502: Jeff Beeman
Drupal Node Overview 8
1 The node type is not displayed on the resulting page. The next topic will show you how to discover this and many
other attributes.
On the resulting page, find and note the key attributes of your new node, including the node ID, title, created date and author.
The devel module
The devel module2 contains utilities and functions that assist Drupal developers and site administrators in developing and
debugging their site. If you are doing any sort of module or theme development for Drupal, it is a “must have” module.
You’ll use it in this lesson to view the key attributes and other “raw” data about the nodes you created.
Enabling the devel moduleThe devel module can be enabled through the standard module installation process. During the session, the instructor
will enable the module for you, but on your own site you can follow the instructions below. These instructions assume
you have already downloaded the devel module and placed it into the appropriate modules folder on your web server.3
EDT502: Jeff Beeman
Drupal Node Overview 9
2 The devel module can be downloaded from http://drupal.org/project/devel
3 A tutorial covering module installation is available at http://drupal.org/handbook/customization/tutorials
Go to Administer -> Site Building -> Modules
EDT502: Jeff Beeman
Drupal Node Overview 10
Check the box next to the Devel module and save the configuration
Go to Administer -> User Management -> Access Control
Using the devel moduleThe devel module has one particularly useful tool that allows you to view the structure of a node. By visiting an individual
node, users with the access devel information permission can click on the “Dev load” tab to view the complete data
structure of the node. This data structure contains the key elements you learned about in the Thinking of nodes as
objects section (node ID, type, title, created date, and author) as well as every other attribute of the node that Drupal
loads.
Once the devel module is enabled, go to one of the nodes you created during the Thinking of nodes as objects section
and click on the “Dev load” tab.
EDT502: Jeff Beeman
Drupal Node Overview 11
Grant the “access devel information” privilege to appropriate user roles
Note: It is generally only recommended to grant this privilege to trusted users.
As you can see, the display is essentially the raw data of the node’s contents. With the devel module, you can quickly
and easily see attributes that would otherwise be more difficult to find, such as the node ID and node type.
PracticeUsing the steps below, view the attributes of various nodes you have created on the site.
1. Using the node ID of one of the nodes you created in the previous section, navigate to that node.
2. Click on the “Dev load” tab visible on the page.
3. Locate the node ID, type, title, created date, and author.
4. Find the node’s body text and changed dates.
EDT502: Jeff Beeman
Drupal Node Overview 12
Modifying the node structure
The key to the strength of Drupal’s node system is that nodes are extensible and modifiable through modules. Some
modules, such as comment and taxonomy, are enabled by default in a Drupal site and extend nodes by adding data to
them that those modules then use to format and display additional information about the node to users.
Navigate to the “Dev load” tab of one of the nodes you previously created. Notice the attributes of this node related to
comments and taxonomy. Currently, the taxonomy attribute of this node is empty, but if we added terms to this node
you would see them here. You are going to use a free tagging vocabulary (a set of related terms) that can be assigned to
the nodes you have created to see how this works.
Creating a vocabularyDuring the session, the instructor will create the vocabulary for you, but on your own site you can follow the instructions
below.4
EDT502: Jeff Beeman
Drupal Node Overview 13
4 You can learn more about taxonomies and their various configurations by clicking on “more help” on the categories
administration page.
Go to Administer -> Content Management -> Categoriesand choose “Add Vocabulary”
EDT502: Jeff Beeman
Drupal Node Overview 14
Enter “Story tags” into the “Vocabulary name” field, check the box next to “Story” under “Types,” check the box next to “Free tagging,” and submit
the form to create the vocabulary.
Introducing hook_form_alterNow that a vocabulary has been assigned to the Story node type, edit a story node that you created earlier. The
resulting form is a modified version of the form you used to create the node before. You can now see a field labeled
“Story tags” that allows you to enter a comma-separated list of terms describing the story. This field 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 module’s 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 modifies it to add the “Story tags” form element.
Doing so allows users to add terms to the story. Here’s how it works:
EDT502: Jeff Beeman
Drupal Node Overview 15
Add a few terms to the “Story tags” field and submit the changes.
On the resulting node page, you can see the terms displayed.
Introducing hook_nodeapiAs you saw, the “Story tags” form element on the node edit form was put there through the taxonomy module’s
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, that’s the only thing that it does. In this case, hook_form_alter’s 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 module’s implementation of hook_nodeapi. Try
to find where the module handles loading and updating node data.
EDT502: Jeff Beeman
Drupal Node Overview 16
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.
Taxonomy module’s 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); }}
Practice1. Go to the form for creating a new story node
2. What is the name of the hook that inserts the “Story tags” text field?
3. Finish creating the new node by filling in and submitting the form.
4. What hook is called when you submitted the form that saves the “Story tags” data?
5. What hook is called to helps display the tags when the resulting node is shown?
6. Click on the “Dev load” tab.
7. What hook is called to pull in the taxonomy term data that you entered?
EDT502: Jeff Beeman
Drupal Node Overview 17
Appendix: Resources
Node attribute definitionsThe following chart defines 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 module’s
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 The unique node ID.
vid The unique revision ID for the node. This allows Drupal to store revisions of node
data.
type The type of the node (i.e. story, blog, page, etc.).
status Whether or not the node is published. 0 means unpublished, 1 means published.
created The time the node was created, stored as a Unix time stamp.
changed The time the node was last changed, stored as a Unix time stamp.
comment 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 The time the node’s last revision was created, stored as a Unix time stamp.
title The title of the node.
body The raw content of the node’s body field.
teaser The Drupal-processed teaser of the node’s body field content.
log The log message associated with the last revision of the node.
format An integer representing the ID of the input format filter that should be used when
rendering the node’s content.
uid The unique user ID of the author of the node.
EDT502: Jeff Beeman
Drupal Node Overview 18
name The username of the author of the node.
picture The path to the user avatar of the author of the node.
data Other, miscellaneous data stored in the node. Some modules occasionally use this
field, but it is not generally used for vital node information.
last_comment_timestamp Used by the comment module to define 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 define the username of the author of the last
comment on the node.
comment_count Used by the comment module to define the total number of comments on the node.
taxonomy Used by the taxonomy module to define an array of terms associated with the node.
tid The primary taxonomy term ID for a forum node. This defines the forum in which the
node is contained.
parent Used by the book module to define a hierarchical structure for nodes.
weight Used by the book module to define a hierarchical structure for nodes.
path Used by the path module to define a URL alias to the node.
files Used by upload module to list files attached to the node.
EDT502: Jeff Beeman
Drupal Node Overview 19
Understanding hook_nodeapi and hook_form_alter
EDT502: Jeff Beeman
Drupal Node Overview 20
View or edit
request to node
Viewing node?
hook_nodeapi("load")
hook_nodeapi("view")
hook_nodeapi("alter")
modules
Modules
modify
the node
hook_nodeapi
Editing node?
hook_nodeapi("prepare")
moduleshook_form_alter
Editing or
viewing node?
Modules
modify
the form
Render the
node
Render the
form
Useful LinksWebsite 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
EDT502: Jeff Beeman
Drupal Node Overview 21