MASTER DRUPAL 7 MODULE DEVELOPMENT

Transcription

1 MASTER DRUPAL 7 MODULE DEVELOPMENT by blair wadman sample available for purchase at

2 LESSON 1 INTRODUCTION

3 In this section, you will be introduced to the core Drupal concepts required to develop modules. Goals Gain a basic understanding of core Drupal concepts like Nodes, Entities and Forms API Drupal Concepts included Nodes Comments Blocks Entities Hook system Menu and Routing Theme system Forms API Users Devel Drush Drupal code Drupal s code is split into three main areas: core, contributed and custom. Drupal Core When you download Drupal, you are downloading Drupal core. It consists of a set of library files and core modules. It is relatively lean and provides the base level of functionality. The library provides a set of tools for interacting with database, form building, translating etc. The core modules are essential modules that cannot be turned off. Core modules include node, taxonomy and user modules. Master Drupal 7 Module Development 1

4 You might have heard the phrase Do not hack core before. This simply means, do not change any of the core code. In Drupal, if you want to add functionality, or change the way Drupal behaves, you do this either by downloading a contributed module or creating your own custom module. Contributed Projects Drupal core is extended via contributed modules and themes. There are thousands of modules on drupal.org and they offer a huge variety in extra functionality. Contributed modules are developed by Drupal developers who are contributing back to the community. They maintain, develop further and deal with the issue queues on a voluntary basis. This forms an important part of the essence of the Drupal community. Custom Modules A custom module is a module that you (or your team) have developed yourself. It may become a contributed module if you make it generic enough so that it is not tied to your specific instance of Drupal. Drupal Structure When you download Drupal, you will find all the folders and files shown below, with the exception of sites/all/modules and sites/all/themes. You have to create those manually. Master Drupal 7 Module Development 2

5 Figure 1-1: Drupal files and folders Master Drupal 7 Module Development 3

6 Folder/File Type Description includes folder Library of common functions misc folder Javascript, icons and images modules folder Core modules profiles folder Installation profiles scripts folder Various scripts for syntax checking etc sites folder Contributed & custom modules, themes, settings themes folder Default themes and template engines cron.php file Runs periodically for specific tasks index.php file Entry point for all requests install.php file Installer file robots.txt file Robot exclusion standard, used to instruct search engines update.php file Run to update the database during Drupal core and module updates xmlrpc.php file Receives XML-RPC requests Table 1-1: Description of main files and folders As you can see, modules other than core modules go inside the sites folder. You will probably see variations on this in other books and online, but the pattern of sites/all/ contrib and sites/all/custom is one that I have seen the most success with on real projects. A note on multi-sites Drupal has the ability to run more than one website from the same code base. This is known as a multi-site. If you are running a multi-site, you would create a folder per site inside the sites folder. For example, if your site was called example.com, you would create a folder inside sites called example.com. Inside that folder, you would create a folder for modules, themes and files. It would also contain a settings file. Any modules and themes that relate to all sites running off this code base live in sites/all. Nodes In Drupal, a node is a primary piece of content. When you create content in Drupal, you are in fact creating a new node. Master Drupal 7 Module Development 4

7 Figure 1-2: Add content If you view that content at its URL, you are viewing the full node. Figure 1-3: Viewing full node Different types of nodes can be created. These are often referred to as content types. Master Drupal 7 Module Development 5

8 Each content type can have its own set of fields. For example, you could have a Blog post content type, with title and body and an Image content type with title and image field. Nodes are stored in the node table in the database and this is one of the most important tables. Each node has a unique ID called the Node ID, or nid for short. When you view a Drupal page, even if you are using an alias, you are actually calling node/nid. For example, the first node will be node/1. When developing modules, it is important to understand the node object. The node object contains all of the important information about a particular node. If you know the node ID, you can get the node object by calling node_load(), as follows: $node = node_load($nid); We will talk more about this when you start developing your own module. Comments Comments are generally attached to nodes and are an integral part of encouraging user engagement. In its simplest form, comments can be made against blog posts. But it does not end there. The Drupal Forum module is actually a collection of nodes and comments. Each topic is a node and replies are comments. Master Drupal 7 Module Development 6

9 Figure 1-4: A comment attached for a simple node Blocks A block is a secondary piece of content that is usually displayed in regions around the main content, such as the header, sidebars and footer. Common examples of blocks Navigation menu Search form Logo Copyright message You might occasionally come across a grey area where you are not sure if a particular piece of content should be defined as a block or a node. As a general rule of thumb, if a piece of node is meant to be displayed on multiple pages (not necessarily every page), it probably should be a block. Master Drupal 7 Module Development 7

10 Figure 1-5: Blocks Entities, Fields and Bundles Entities, Fields and Bundles are all new to Drupal 7. Entities provide a mechanism to create types of data that are not nodes. In times past, you might hear developers saying everything is a node. This no longer holds true. Nodes, comments, taxonomy and users are all types of entities that come with Drupal. You can create your own entities and some contributed Drupal projects come with their own. For example, Drupal Commerce defines its own entities such as Product entity, Customer profile entity, Line item entity, Order entity and Payment transaction entity. In these examples, using a simple Node entity would have been too restrictive. Fields are re-usable pieces of content which can have validators, widgets and formatters. Master Drupal 7 Module Development 8

11 A bundle is a sub-type of an entity and you can attach fields to it. An example of a bundle is an Article, which is a subtype of the node entity. This is similar to a content type in Drupal 6. To illustrate the concept of entities,bundles and fields, take a look at the illustration below. This is an example of the node entity which contains two bundles, Article and Gallery. Article has two fields, title and body. Gallery has three fields, title, image and summary. node entity article gallery title field title field body field image field summary field bundle bundle Figure 1-6: Entity, bundles and fields Comparison to Drupal 6 Fields and bundles are closely related to CCK in Drupal 6. An Article would be a content type in Drupal 6 and it would have fields attached to it. Request and Reponse When a user requests a page on a Drupal site, a lot happens behind the scenes to generate that page. The following illustration is a summary of the steps Drupal goes through to generate a node page. Master Drupal 7 Module Development 9

12 Request Bootstrap - load libraries & initialise Drupal Menu System - decide how to handle path - does user have access? - map to callback function Node Module - load node Theme system - format & style data HTML & CSS Response Figure 1-7: Request and response process Hook system The hook system is central to Drupal. Pretty much anything and everything that happens in Drupal happens because of a hook. During the request and response lifecycle, Drupal and modules fire off events and listens for a response through its hook system. It checks all enabled modules and looks Master Drupal 7 Module Development 10

13 for functions that follow certain patterns. For example, if it is checking for blocks, it checks all modules with the <modulename>_block(). After finding these functions, Drupal executes them and uses the data they return as part of the response to the page request. You can listen for an event by calling a specific function, and then adding something that will happen when that event is fired. Let s take another look at the Drupal request and response process with hooks added in. Request hooks Bootstrap - load libraries & initialise Drupal hooks Menu System - decide how to handle path - does user have access? - map to callback function hooks Node Module - load node hooks Theme system - format & style data HTML & CSS Response Figure 1-7: Request & response & hooks Example The best way to understand this is by way of an example. A user logs on the website. Master Drupal 7 Module Development 11

14 The act of logging in is an event. You can call a function called hook_user_login() in your module which will listen for this event. You add some code to display a hello message if a particular user logs in. User logs in hook hook_user_ login Display message Figure 1-8: Hook user login example Modules can either define or implement a hook. Implementing hook: A hook has been defined by another module and you are implementing it. In our previous example, we implemented hook_user_login(). hook_user_login() is defined by the User module. In most cases, you will be implementing a hook. Invoking a hook: When you write a module, you can define a new hook. By doing so, you are allowing other modules to implement the hook and further extend functionality. Master Drupal 7 Module Development 12

15 Menu & Routing The Drupal menu system is one of the most import concepts to understand in order to develop Drupal modules. The menu system handles 3 areas: 1. Callback mapping (menu router) 2. Access control 3. Menu customisation Menu Router & Callback Mapping You were introduced to hooks in the previous section. Like most of Drupal, the Menu System uses hooks. One of the most important parts of the Menu System for module development is hook menu (hook_menu()). Hook Menu is a function that we use to define menu items and callback functions. hook_menu() allows your module to register paths and information on how it will handle requests to that path. The second step on Figure 1-7 (Request and Response) is the Menu System. If it wasn t for the Menu System, Drupal would not know what to do with a request for a URL. The Menu system decides what to do with the path and which callback function to fire. Access Control When handling a request, the menu system must decide if the user has the necessary permission to view the content being requested. Menu Customisation The menu system also helps with the structure of a Drupal site through menus. Menus are hierarchical and a menu item can have any number of children. Figure 1-9: Example of a menu, the navigation menu Master Drupal 7 Module Development 13

16 Theme System The Theme System controls the display and presentation (look and feel) of content. The theme system is not confined to just themes. Core libraries, modules and themes all make up the theme system. The core library initialises themes and locates theme functions and templates to use. Modules can define default theming for the content that it is responsible for. A theme can then override that theming. Figure 1-10: Files included with the bartik theme Templates for content types One of the templates that you can use is node-content_type.tpl.php. That is a node template that is specific to a particular content type. For example, if we had a content type called blog_post, the template file would need to be called node-blog_post.tpl.php. In theory, this file could exist in either the theme, or in the module that creates and controls the content type. It is quite common for content types to be created in the Drupal UI (CCK in Drupal 6, Fields in Drupal 7) and not controlled by a module. In those cases, the templates tend to reside in the theme layer. We are focusing on module development in these lessons, so we will not cover developing in the theme itself. However, theming in the module will be included. Render Arrays Drupal s theme system uses render arrays to generate HTML pages. This system allows module developers or themers to change the page content or layout before it is Master Drupal 7 Module Development 14

17 displayed to the user. When creating a render array, you create a simple array with a defined set or properties. Properties include a prefix, suffix and markup. Drupal takes these arrays and converts them into raw HTML to return to the browser. Do not worry at the moment if this does not make sense, it will be easier to understand when you implement it for yourself in a later lesson. Forms API Forms are an essential part of most websites, and Drupal websites are no exception. They are the primary method for users to submit data to the website, whether it be to login, comment on an article or create a new article. In Drupal module development, you use the Form API to define a form. Drupal then builds the form, displays it, validates it and collects the data. By using an established API and using it correctly, we are going a long way towards protecting our application against a whole range of possible security vulnerabilities. It also takes advantage of the hook system. When you create a form, another developer can hook into your form and change it. And you can hook into any other form and change it. That is an amazing powerful feature. There is an extensive list of elements/properties you can use on api.drupal.org 1. Users A user can be anyone who visits a Drupal website. Some users are registered with the website and some are not. If a user is not registered with the website, they are called an anonymous user. A user who is registered is called an authenticated user. Roles and Permissions Authenticated users may belong to one or more roles. A role is a set of permissions that all users who belong to it share. For example, a publishing website might have content editors who belong to the editor role. The editor role might have permission to add and edit nodes of a certain type. All users who belong to the editor role will have that permission. Profile Each user can have a profile and a profile can have any number of fields. User Object User data is stored in the database and is available in the user object. Drupal as a social network Many people think of Drupal as a CMS. It can be a CMS, but it can also be a lot more than that. Drupal s User system lends itself very well to that of a social network and it is not uncommon for developers to build quite advanced social networks in Drupal. Master Drupal 7 Module Development 15

18 Devel The Devel module is an essential part of a Drupal developer s toolbox. It includes a range of tools designed to make developers and themers lives easier. When you get more experienced with module development, you will probably use it for things like identifying slow database queries. But at this stage, we will use it for one really simple time saver - Drupal Print Message. Give it an array or object and Drupal Print Message will enable you to visually walk through its data in a message on the page. As an example, consider this simple array: $diet = array(pizza, fruit, beer, water, toast); dpm($diet); This will print out the following: Figure 1-11: Devel dpm This is a very simple example. When you start developing modules, you will have to deal with some large arrays and objects, such as the node object. Visually walking through them will help you pin point that data that you need. Drush Drush is a command line utility for Drupal. It provides developers with the ability to manage a Drupal installation from the command line, rather than having to always use the Drupal admin interface. Once you get used to it, it can be a real time saver. You will be using Drush through this book. Summary In this section, you were introduced to some of the key Drupal concepts that are required for developing modules. It is a very high level explantation and you will be exposed to the technical implementation of these in the remaining lessons. 1 Form API elements and properties Master Drupal 7 Module Development 16

19 %21forms_api_reference.html/7 Master Drupal 7 Module Development 17