Programmer's Guide to Drupal

235 Pages·2016·2.1 MB·English

by  Jennifer Hodgdon

2
C n
o
v d
er E
s di
D t
r i
u o
p
Programmer’s al n
7
&
8
Guide to
D rupal
PRINCIPLES,
PRACTICES,
AND PITFALLS
Jennifer Hodgdon
Programmer's Guide to Drupal
If you’re a web programmer, your experiences have taught you certain “Anexcellent,concise
lessons—and only some of them apply well to Drupal. Drupal has its own treatisetofast-trackyour
set of programming principles that require a different approach, and many
Drupaldevelopment.”
programmers make mistakes when relying on skills they’ve used for other
projects. This book will show you which programming techniques you can —Karoly Negyesi
Drupal Core Developer
use—and which you should avoid—when building web applications with
this popular content management framework. “WrittenbytheDrupal
Updated to cover both Drupal 7 and Drupal 8, the guidelines in this book
community'sforemost
demonstrate which programming practices conform to the "Drupal way"
expertindeveloperdocu-
and which don’t. The book also serves as an excellent guide for Drupal 7
programmers looking to make the transition to Drupal 8. mentation,Programmer's
Guide to Drupal isa
■ Get an overview of Drupal, including Drupal core and add-on must-havereference
modules and themes
foranyonelookingfora
■ Learn Drupal’s basic programming principles, such as the ability
practical,example-driven
to customize behavior and output with hooks
waytodiveintoDrupal7
■ Compare Drupal 7 and Drupal 8 programming methods, APIs,
and concepts or8development.”
■ Discover common Drupal programming mistakes—and why —Angela Byron
hacking is one of them Drupal Core Committer
and Product Manager
■ Explore specific areas where you can put your programming
skills to work
■ Learn about the new object-oriented Drupal 8 API, including
plugins and services
Jennifer Hodgdon is an experienced software developer who has been working
with Drupal since 2007. She is a former leader of the Drupal Documentation Team
and currently acts as core maintainer/committer for Drupal API documentation, in
addition to doing Drupal programming as a freelancer and contributing code and
documentation to the Drupal project.
H
o
d
g
d
o
n
DRUPAL Twitter: @oreillymedia
facebook.com/oreilly
US $29.99 CAN $34.99
ISBN: 978-1-491-91146-4
SECOND EDITION
Programmer’s Guide to Drupal
Jennifer Hodgdon
Boston
Programmer’s Guide to Drupal
by Jennifer Hodgdon
Copyright © 2016 Poplar ProductivityWare, LLC. All rights reserved.
Printed in the United States of America.
Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472.
O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are
also available for most titles (http://safaribooksonline.com). For more information, contact our corporate/
institutional sales department: 800-998-9938 or [e-mail].
Editor: Allyson MacDonald Indexer: WordCo Indexing Services, Inc.
Production Editor: Matthew Hacker Interior Designer: David Futato
Copyeditor: Eileen Cohen Cover Designer: Ellie Volckhausen
Proofreader: Jasmine Kwityn
December 2012: First Edition
October 2015: Second Edition
Revision History for the Second Edition
2015-10-08: First Release
See http://oreilly.com/catalog/errata.csp?isbn=9781491911464 for release details.
The O’Reilly logo is a registered trademark of O’Reilly Media, Inc. Programmer’s Guide to Drupal, the
cover image of a French angelfish, and related trade dress are trademarks of O’Reilly Media, Inc.
While the publisher and the author have used good faith efforts to ensure that the information and
instructions contained in this work are accurate, the publisher and the author disclaim all responsibility
for errors or omissions, including without limitation responsibility for damages resulting from the use of
or reliance on this work. Use of the information and instructions contained in this work is at your own
risk. If any code samples or other technology this work contains or describes is subject to open source
licenses or the intellectual property rights of others, it is your responsibility to ensure that your use
thereof complies with such licenses and/or rights.
978-1-4919-1146-4
[LSI]
Table of Contents
Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
1. Overview of Drupal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
What Is Drupal? 1
Drupal Core 2
Drupal Add-Ons: Modules, Themes, Distributions, and Translations 3
The Evolution of Drupal 5
How Drupal Handles HTTP Requests 7
HTTP Request Handling in Drupal 7 8
HTTP Request Handling in Drupal 8 9
The Drupal Cache 10
Drupal 7 Cache API 11
Drupal 8 Cache API 11
Automatic Class Loading in Drupal 12
2. Drupal Programming Principles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Principle: Drupal Is Alterable 17
Setting Up a Module or Theme 20
The Basics of Module and Theme Hook Programming 23
Making Your Module Output Themeable 25
The Basics of Drupal 8 Plugin Programming 28
Drupal 8 Services and Dependency Injection 35
Interacting with the Drupal 8 Event System 38
Principle: Drupal Separates Content, Configuration, and State Data 39
Information Storage in Drupal 7 40
Information Separation in Drupal 8 41
Configuration API in Drupal 8 42
State API in Drupal 8 47
Principle: Drupal Is International 48
Internationalizing User Interface Text 49
iii
Internationalizing User-Entered Text in Drupal 7 50
Internationalizing User-Entered Text in Drupal 8 51
Principle: Drupal Is Accessible and Usable 52
Principle: Drupal Is Database-Independent 54
Setting Up Database Tables: Schema API and hook_update_N() 55
Querying the Database with the Database API 58
Principle: Drupal Is Secure; User Input Is Insecure 61
Cleansing and Checking User-Provided Input 62
Checking Drupal Permissions 64
Principle: Drupal Code Is Tested and Documented 67
3. Common Drupal Programming Mistakes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Mistake: Programming Too Much 71
Avoiding Custom Programming with Fielded Data 75
Defining Theme Regions for Block Placement 77
Mistake: Overexecuting Code 79
Mistake: Executing Code on Every Page Load 79
Mistake: Using an Overly General Hook 80
Mistake: Saving PHP Code in the Database 81
Mistake: Working Alone 82
Participating in Groups and IRC 83
Reporting Issues and Contributing Code to the Drupal Community 83
Contributing to the Drupal Community in Other Ways 85
4. Drupal Programming Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Registering for URLs and Displaying Content 88
Registering for a URL in Drupal 7 89
Altering a URL Registration in Drupal 7 91
Registering for a URL in Drupal 8 92
Providing Administrative Links 95
Altering Routes and Providing Dynamic Routes in Drupal 8 98
Registering a Block in Drupal 7 100
Registering a Block in Drupal 8 101
Creating Render Arrays for Page and Block Output 102
Render Arrays in Drupal 8 106
Generating Paged Output 107
Using the Drupal Form API 109
Form Arrays, Form State Arrays, and Form State Objects 110
Basic Form Generation and Processing in Drupal 7 112
Basic Form Generation and Processing in Drupal 8 114
Creating Confirmation Forms 116
Adding Autocomplete to Forms 119
iv | Table of Contents
Altering Forms 121
Programming with Ajax in Drupal 123
Setting Up a Form for Ajax 124
Wrapper-Based Ajax Callback Functions 127
Command-Based Ajax Callback Functions in Drupal 7 127
Command-Based Ajax Callback Functions in Drupal 8 128
Programming with Entities and Fields 129
Terminology of Entities and Fields 129
Defining an Entity Type in Drupal 7 132
Defining a Content Entity Type in Drupal 8 139
Defining a Configuration Entity Type in Drupal 8 149
Querying and Loading Entities in Drupal 8 160
Defining a Field Type 161
Programming with Field Widgets 164
Programming with Field Formatters 168
Creating Views Module Add-Ons 171
Views Programming Terminology and Output Construction 172
Setting Up Your Module for Views in Drupal 7 174
Providing a New Views Data Source 175
Adding Handlers to Views 177
Adding Fields and Relationships to an Existing Views Data Source 179
Providing a Style or Row Plugin to Views 180
Providing Default Views 183
Creating Rules Module Add-Ons in Drupal 7 184
Providing Custom Actions to Rules 186
Providing Default Reaction Rules and Components 188
Programming with CTools in Drupal 7 189
Implementing CTools Plugins for Panels 189
Providing Default CTools Exportables 195
5. Programming Tools and Tips. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Where to Find More Information 199
Drupal Site Building and General Drupal Information 199
Drupal Programming Reference and Background 200
PHP Resources 202
Database Resources 203
Other Web Technology Resources 203
Drupal Development Tools 204
Discovering Drupal API Functions and Classes 205
Other Programming Tips and Suggestions 207
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Table of Contents | v

Preface
Welcome! This book is meant to launch you into the world of programming with the
open source web content management system known as Drupal. My hope is that with
the aid of this book, you will pass smoothly through the stage of being a novice Dru‐
pal programmer, while avoiding the mistakes that many expert Drupal programmers
made in their first Drupal programming endeavors. If you make an effort to learn the
“Drupal way” of programming, you can look forward to many enjoyable and fruitful
years of programming with Drupal.
Probably every experienced Drupal programmer has a slightly dif‐
ferent definition of the Drupal way of programming, although
there are many commonalities. My interpretation of the Drupal
way is set out in Chapters 2 and 3; I’ve tried to stick to the com‐
monalities in the definition that most Drupal programmers would
agree on.
Intended Audience
The first edition of this book was written primarily for people with a background in
programming who are new to using and programming with Drupal. If you fit this
profile, the main reason to read this book is that whatever your programming back‐
ground, your experiences have taught you certain lessons—and only some of them
apply well to Drupal. My main goal in the first edition was to make you aware of
which lessons are which, and help you make a successful transition to being an expert
Drupal programmer: someone who knows just how and where to apply your pro‐
gramming skills to have the greatest effect.
The second edition of this book retains this goal but is also aimed at experienced
Drupal 7 programmers who want to make the transition to Drupal 8. Because both
Drupal 7 and Drupal 8 are included in this book, programmers who fit this profile
vii
will be able to compare the Drupal 7 programming methods, APIs, and concepts that
they are familiar with to their Drupal 8 equivalents.
In addition, this book should be useful for the following audiences:
• Anyone working with Drupal who wants to understand how it works “under the
hood”
• Drupal site builders and themers who have realized they need to do some pro‐
gramming for customization and want to do it the Drupal way
• Drupal users who want to contribute to the Drupal open source project by
programming
The backend of Drupal and most of its code is written in PHP, utilizing some variety
of SQL for database queries. Accordingly, this book concentrates on PHP and data‐
base programming for Drupal, although there are definitely opportunities to pro‐
gram in Flash, JavaScript, and other frontend languages with Drupal.
Because this book was written for a programming audience, it assumes knowledge of
the following:
• The basics of the Web and HTTP requests
• The basics of PHP programming and programming in general (standard pro‐
gramming terminology is not explained)
• Object-oriented programming in PHP, especially for the Drupal 8 sections
• How to use Drupal core and existing add-on modules to build web sites
See “Where to Find More Information” on page 199 to find resources about these
topics, if you need additional background.
How to Use This Book
In order to get the most out of this book, I would suggest that you start by reading
Chapter 1 and making sure you are familiar with all the material in it. If you have
never installed Drupal at all or tried to use it, you should definitely do that too. There
are installation instructions in the INSTALL.txt file that comes with Drupal (this file
is in the core subdirectory in Drupal 8), or at https://drupal.org/documentation/install.
Then I’d suggest reading Chapters 2 and 3 carefully, to learn about the dos and don’ts
of Drupal programming; there are also many programming examples in those chap‐
ters. If you’ve never before done any Drupal programming or looked at any Drupal
code, there are suggestions at the beginning of Chapter 2 for finding some code to
look at before or while you read those chapters. I would especially recommend down‐
loading Examples for Developers, which is a comprehensive set of programming
viii | Preface