Module Investigator: Drupal 7 Email Field part 1

By shane
Tue, 2012-11-27 12:24
Daily Dose of Drupal Episode #55

Share with Others

This is the first ever Module Investigator episode of the Daily Dose of Drupal. In a Module Investigator episode, I walk through the module PHP code of a module that I have covered in another Daily Dose of Drupal episode.

In this episode I look at the code of the Drupal 7 Email Field module that I covered in the Daily Dose of Drupal episode 42.

This is a rather long episode, but it covers a lot of important topics.

In this episode you will learn:

  • The basic architecture of a Drupal module
  • What the LICENSE and README files are for in a module
  • How the .info file is used to tell Drupal about the module
  • How various Drupal hooks are used to integrate a module with Drupal
  • How the Email Field module uses the Drupal 7 Field API to create a new Drupal Field Type

Hello there and welcome to another Daily Dose of Drupal. Today we’re on Episode Number 55, as always; I am Shane, you can follow me on Twitter @smthomas3, also go ahead and go to if you haven’t already and sign up for the newsletter here left. I send out a newsletter every once in a while that has some links to popular articles on my blog, also some other Drupal insights and eventually I’ll be sending out a couple of courses that only people from my newsletter will be able to access so go ahead and get signed up and we’ll go ahead and get started today.

I’m pretty excited about today’s episode; it’s been something I’ve wanted to do for a while, I believed it was originally recommended from the Contact Form on the website but basically I’m going to go ahead and call it a Drupal Module Investigator episode. I found that there’s a disconnect between writing your first module and actually understanding how a more complex module works.

So what I’m going to do is I’m going to take what’s going to start as in simple Drupal modules and I’m going to break them down and go over the code and show you not only how it works but why it works the way it does. And this is hopefully going to fill the gap between if your module developer just starting out and actually being able to build some pretty cool modules so let’s go ahead and get started. I’m going to go over this e-mail field module today and I’m going to look at the code, I’m only going to focus on the field, the API portions on the code mainly because I don’t really have time to go over all f the code but I’ll just go over the portions that I think are important to get started or at least an important portion of the module.

If you haven’t already watched episode number 42 I believed, yes 42, it goes over the e-mail field module and it will show you some of the basic on how the module actually works. Today we’re going to focus on some more on the code behind the e-mail field module and how it works the way it does and how I go about deconstructing a module if you need to figure out why it’s working the way it does or if you need to figure out how you can interact with that module.
So the first thing; let’s go ahead and open up all of the files from this module, you can see it’s the e-mail module, it has … looks like 7 files in it, I’ve went ahead and opened all of them here. The first is the license file that’s added on by Drupal so we’re going to go ahead and ignore that, the next is a read me file; this is an important place to start if you’re looking at module and you’re not sure what it does or how it works. The Read Me file could be very helpful so you could read through that.

This; this is a … it just integrates with the Feeds module, we’re not going to go over this part today but you can of course take a look and figure out what it’s doing, also this e-mail.migrate; this is support for the migrate package, I believe this is for migrating from Drupal 6 to Drupal 7, we can ignore that one today as well, we’re going to take a look at the Info file.

The Info file is basically the configuration file for your Drupal module. In this case it says the name is e-mail, it gives it a description, the core is 7.x because it is a Drupal 7 website, it’s a Drupal 7 module intended for use on a Drupal 7 website. You can see the package is fields that will put it in the Fields Set on the modules page and it also includes that file that we’re going to ignore.

So go ahead and close that one out and I’ll show you if you go onto the modules page, into the field section, that’s where that package comes in, you can see the e-mail module has been enabled. We’ll now go to the Install File; we have e-mail field schema and this as you can see this comment is very helpful, it tells you it’s implementing Hook Field Schema.

So we’re going to actually take a look at what that does and this is very helpful when you’re trying to look through and figure out what a module was doing. So I’m just going to Google search that Hook, you can use any search engine you want of course and I’m going to go to the page on Hook Field Schema. And you can see this defines the Field API Schema for Field Structure.
What this module does … and you can go back and watch the previous video, it creates an e-mail field that you can use inside a content type in Drupal. So in this example I have a content type called Test Fields and one of the fields in there is an e-mail field. So what this does is this defines a way to store that data from the field, you can see that it defines the column as e-mail, the type is a var_char which is a variable character and length of 255 and this actually creates that database table to store this e-mail field data.

So that all that works from the install file, we’ll not take a look at the module file. As I said before; we’re only going to look through about the first 200 lines of it today just to save time but you can of course take a look at the rest.

The first thing is Hook Field Info; we’re going to take a look at that one and you can see this defines Field API field type because the label, description, settings and a couple of other properties for the array that you can return. You can see that the key of this array is e-mail … the label is e-mail and it says … it gives a description; it gives it a default widget, default formatter and the property type.
So let’s go ahead and see how that works out; you can see the field type right there is set as e-mail, if you click this dropdown you see there is an e-mail field type. Let’s go ahead and change this to e-mails just to see how it works. It’s one thing you can do, it’s good to change the code, tweak it a little bit, save it and see how it has an effect because that will allow you to really dig in and find out how that’s working You’ll notice this was changed to e-mails and it says e-mails is now in the dropdown, so that is where that comes into play.

So creating a new field type is as simple as implementing that hook with your own different … based on the types of fields you need, different information. This is the Migrate API information that we’re going to go ahead and ignore, the next is Hook Field Validate.

We’re going to follow the same pattern we have before and go ahead and look that up and see what it does. It says it validates this module’s field data. So it goes ahead and says if there are validation problems it adds to the errors array which is passed by reference, so there is no return value because this is in fact passed by reference. You can see what it’s doing here is it’s looping through this items, all of the items from this content type and if there is an item that is an e-mail type which is what we defined up here then it’s going to try to validate this e-mail address by calling this valid e-mail address function.

If it is valid it’s going to just ignore it but if it’s not valid which is in this case the not valid is going to go ahead and said the message thing this is not a valid e-mail address and it’s going to pass in the error. So we’re going to go ahead and take a look at that, I am going to try to create a simple test fields content type and I’m going to try to create an example or an e-mail example but I’m going to put an invalid e-mail address, you’ll see that it says all the characters I entered is not a valid e-mail address.

I can of course change this; add a couple of exclamation points for instance, try to save it again and you’ll notice my exclamation point has come up so you can interact with the code that way and see how this validated function is working. Hook Field Widget error is another Hook and this does something a little bit different, this one it says flags a field level validation error.

So all these does is set an error on the widget itself I believe so let’s go back to this … on the widget form itself I believe is where this error comes into play but you can see all it’s doing is just setting … if there’s an error message it’s setting on elements. So that is all that is doing. Let’s go ahead and … just because I’m not 100% sure on this I’m just going to check it quick, this shouldn’t do anything in this case because I believe it’s on that widget page.

I haven’t actually looked over this code very much yet so I’m learning just as I’m trying to teach you guys and girls. Alright, so as you can see when I do not have that … so it is in fact using that or when I do not have this getting set, this is just setting this error getting pass through here. So when I comment to that out you’ll notice that what should have been an error was now passed through, if I uncomment that, save it, now the error is showing up.

So that’s … this actually is setting the error so in most cases this is probably pretty much the same thing regardless of what you have in your validated function, it could be different but I’m not exactly sure what cases that might be. I’m sure if you read the documentation on it will give you some additional information on what that can do.

The next is this Hook Content is empty and this one we’ll go ahead and take a look, I don’t … I’m not familiar with this one either and you can see it doesn’t look like there’s any documentation for that Hook so I’m not exactly certain. You can see it talks about some CCK so I’m not sure exactly what this does, maybe it has a purpose maybe it does not. You could of course change the code, test it out and see if it has any impact. This could be something legacy from the Drupal 6, it could have a purpose, I’m just not aware of it but go ahead and if you figure it out go ahead and let me know in the comments section.

This Hook Field Formatter Info; let’s take a look at that one, as you can see this process is pretty much the same and if you’re just getting new or getting brought up the speed on building Drupal modules, the process of deconstructing and existing modules pretty much the same. You look through the Hooks, you figure out what they do and then you can of course use those Hooks.

When you want to learn about the Field API you can just do a search for the Field API and learn about the various Hooks that need to be implemented, look at modules like the e-mail or link module and figure out how to create your own fields using the Drupal 7 Field API. So Hook Field Formatter Info exposes Field API format or types. You can see there’s e-mail default, e-mail contact and e-mail plane. Also there’s a conditional formatter; if the module exists which in this case means the module is downloaded and installed and this is the spam span module, it adds another format.

Let’s go ahead and take a look at what that means; so when you come over to the structure content types, I’m going to my content type, I go to Manage Display, you’ll notice there are a couple of different formats here; there’s the default e-mail link, e-mail contact form and e-mail plain text and that corresponds to this Hook or this Hook Field Formatter Info and I’m going to there for today because I don’t want to make this too long but I’m going to finish up the rest of this module or at least through all the Field API types tomorrow.

So I’ll be going over the rest of this tomorrow and I’ll actually go through and I’ll create a new formatter and I’ll show you how that shows up and how that can be used and I’ll also got through what these formatters are doing and how you can of course use this Hook on your own module.

So that’s it for today on the Daily Dose of Drupal, Module Investigator episode of the e-mail field module. We’ll be back again tomorrow and I will finish this up and then we’ll continue on learning other Drupal stuff. So thanks again for watching, as always, I’m Shane, follow me on Twitter if you haven’t already and I will be back again next time. Thanks again, bye.