Module Investigator: Drupal 7 Email Field part 2

By shane
Wed, 2012-11-28 09:09
Daily Dose of Drupal Episode #56

Share with Others

In the second part of this module investigator episode, I continue looking at the Drupal 7 Email field module and how the module implements Drupal 7 hooks to interact with the Drupal 7 Field API.

This is part 2 of the Daily Dose of Drupal episode 55. Unfortunately this one was even longer than part 1. I will try to shorten these videos up a little bit going forward.

In this episode you will learn:

  • How to add and modify Drupal Field API display formatters
  • How to add and modify Drupal Field API widgets
  • How sometimes you just need to clear the Drupal cache to get things to work

Welcome to another Daily Dose of Drupal, today we’re on Episode Number 56 and if you didn’t follow yesterday’s episode, we’re learning about the E-mail Field Module and we weren’t only going over with the e-mail field module did, we’re actually going to the code in figuring out why it works the way it does and learning how it interacts with the Field API in Drupal 7 to actually work the way that you know that it works based on the previous episode of the Daily Dose of Drupal Episode Number 42 and probably your uses for the module which I’m guessing you may have had if you worked on a few Drupal websites.

Last time it went a little long so we’ll try to keep it a little shorter this time but we basically got down to this Hook Field Formatter Info and we’re learning about Field Formatters. So we’re going to go ahead and get started; but first you can follow me on Twitter @smthomas3 or you can go over to and sign up for the newsletter if you haven’t already.

Okay so Field Formatters and Hook Field Formatter Info; as we did last time we pulled it up and it exposes Field API Formatter Types. This is displayed in the Manage Display section and as you can see there are three formats here; and as I mentioned before I sometimes like to change code if you’re not sure what it does and that’s a good way to figure out and be able to turn how it’s interacting, you’ll notice nothing changed there.

So we’ll take a look, we’ll refresh again juts to make sure and again; although I did changed the label here for default e-mail link it’s still is not showing up. So the next solution is let’s go ahead and clear the cache, let me go ahead and get to this Drupal site and I’ll use Drush to clear the cache, now if I come back to this page you can see that the asterisk I added are now showing up. Now it’s just a lesson that some things are dependent on the cache, they actually are cache, in this case this Field Formatter Info, this Hook Field Formatter Info information is actually cache.

So by clearing that it was able to show up … it should be able to show up correctly again, you’ll notice it still have the asterisk, go ahead and cleat the cache, refresh the page and it will go away. Okay the next step; let’s actually figure out what these are doing. So this Hook Field Formatter Info; this corresponds with the Hook Field Formatter View.

The Hook Field Formatter Info Hook actually defines which to show in that list so what formatters are available and this Hook Field Formatter View will actually define how to display this by building a renderrable array and you can check out some previous episodes of the Daily Dose of Drupal to learn about renderrable arrays or you can of course find plenty of information on

So as you can see there are three formatters here and one conditional that I talked about last time. Each one of these; for instance e-mail default corresponds to a case statement in this Hook Field Formatter View. So if you selected e-mail default it’s going to use this case statement, if you selected e-mail content or contact we’ll use this one and so on and so forth. Let’s go ahead and give it a try.
So I’m going to go ahead and pull up this piece of content, I’m going to actually add a valid e-mail address here and save it and you will notice that if I go to this page there is … it says contact person by e-mail. And that is because I’m using this e-mail contact form formatter, if I use the default one and go ahead and save it and refresh this page you can see that it creates a mail to link as if you look down at the bottom left corner and that is created by this section right here.

So as you can see it uses this mail to link, we can go ahead and add some extra text here just to make sure that we know how it’s working so I’m just going to add a little bit of text out in front and I’ll refresh it, you can say now it says e-mail ***, I’m going to go ahead and get rid of that, the e-mail contact formatter goes through so all this one does it it sets element delta to a renderrable array of mark-up and then it goes ahead and it returns this elements so it’s returning this renderrable array or render array.

And if you want to look what all these parameters are you can of course hop over to documentation and it’s going to give us some more information. The first is Entity Type which is the actual type of entity, in this case the Use Object Type but it’s the same thing, Display Type is the name of formatter to use so that’s important to know this Display Variable at the end has a type item in the array and this Type Item is going to correspond to one of these Hook Field Formatter Info items what we’ll declare up above.

So we’re going to go ahead and just create a new one just to show how it works and ours is not going to be anything realistic but you’ll probably use an actual module but it’s just going to show an example. So e-mail example; so as you can see I’m just … copied the previous one and I created another item in this Hook Field Formatter Info Array, this formats array that get’s returned, if I save this hop over and clear the cache and I hop back over here, you’ll notice now I have my e-mail example format, I’m going to save that but before anything is going to actually work I’m going to need to define a case statement for that.

So Case E-mail example and I’m going to follow the same format as it show above and I’m basically going to loop through all the various items and for each item; what this allows you to do is it could be multiple … this Delta Value, there could be multiple e-mail addresses for this fields. Some Fields allow you to define multiple items, in this case it’s only one but it could be multiple so you need to be able to handle that option and we’re going to just keep really simple and as I said before this won’t actually to be something you would use but you can really see how it works.

And then we’re going to go ahead and just add that e-mail address so it’s going to be some extra text here, I’m going to go ahead and save that, now I’m going to refresh this page, now it says my example e-mail formatter is and then it has my e-mail address. Like I said before not really a real life use case but you can see how easy it is to add an additional Hook Field Formatter or an additional Field Formatter I guess. The important thing to note is although I just showed you you can do this, this isn’t the correct way to actually add an additional formatter.

You can actually implement your own Hook Field Formatter View and Hook Field Formatter Info in your own module and not actually have to modify the e-mail field module and that is in fact the way you should do it so this code here would actually need to be broken out in its own module just because you don’t want to actually modify contributed modules if there’s easy hooks that allow you to interact with them otherwise you’ll have update problems and it’s just not the best way to do things. However it does show you what the module is doing and how you can interact with it.

So the next step will go ahead and look at Hook Field Widget info and we’ll follow the same pattern as before and look up and see what Hook Field Widget Info does. You can see it exposes Field API Widget Types. That may not exactly tell you what it does but we’ll go ahead and take a look; so this returns and array e-mail_textfield and it gives us a label of text field.

The Field Types that it applies to is e-mail because that’s the e-mail filed that we are creating or that’s created up above and settings is a size of 60. So let’s go ahead and take a look at this; if you come back to Manage Fields you can see this widget shows up as Text Field, if I change this; Text Filed 2 for instance and I refresh you’ll notice that now it says Text Field 2 here and you can of course add additional widget types there just like we added formatter types. So I can create a second one that could do something else for instance.

So you have Text Field 2, it doesn’t seem to want to show multiple for some reason, interesting, go ahead and make sure we clear the cache, maybe that’s the cause of the problem and you’ll notice it of course was, so important note; when in doubt you may want to try clearing the cache. Again we’re not going to modify the original module, just know that you can play around with that and see how that works.

The Settings Form is actually the form that you will see if you go into Field Settings … well actually not Field Settings and go into the Edit and this here corresponds in this Hook Field Widget Settings Form which we’ll take a look at first but it’s going to correspond to this form in some way. So we’ll take a look at Hook Field Widget Settings Form, it says add settings to the Widget Settings Form.

Pretty straight forward answer I guess but it tells you of course the information that page is for these different hooks. They’re going to be extremely valuable when you’re trying to learn this information. So what this does is it grabs the widget and the settings, it does pull out the settings value that’s set from up here but it allows you to change the size of the text field, it does add a valid date, the valid date is a positive integer.

Let’s go ahead and change the title to size of e-mail text field and we’ll take a look, refresh and you’ll notice now down here it says size of e-mail text field, it does default to 60. I believe if I change this unless I’ve already saved it I’m not positive that this is going to show up but we’ll go ahead and take a look, clear the cache and we’re still set at 60. I’m guessing it’s because I actually had saved this form before so it overwrote that default value but you can of course change the default here, it defaults to 60.

The next is Hook Field Widget Form; now this one is a little different than the Hook Field Widget Settings Form. So even though … there’s a lot of Hooks that are getting thrown around for the Field API and it’s confusing even to me and I’ve worked with them a decent amount so don’t be worried that it might seem a like there’s a lot of hooks that’s going around, you can of course always look them up and you can use other modules as examples when you’re building your own.
So after you’ve seen how a couple of modules work you can go ahead and you can pull those examples up as you need them as you’re working on modules that you may need in order to know how those are set up and how they interact with Drupal core and the Drupal Field API.

So this returns the form for a Single Field Widget and this one is actually not the settings form here but if you go to the actual content type and click Edit it is this text field right here. So as you can see the type is Text Field, it gives it a default value which is going to be pulled in from the items array that is passed in using the correct delta so you can use multiple e-mail fields or multiple instances of one e-mail field and it pulls in the correct size, it gives it a prefix and a suffix as well.
So if we went ahead and for instance commented out the default value then when we refresh this page you can tell that there is no default value here. So although I didn’t go … that’s really it for the Field API stuff and it does some other things with allowing you or with a Hook Menu and the Form API, we’re not going to go through that because it’s already went on for quite a while.

The Field API; as you can tell there’s a lot of Hooks implement however if you look at the amount of code, each Hook does not actually contain a lot of code so you can actually take a look at it, go through it, find out what each line of code is doing. Don’t be afraid to … for instance; in this case if we’re going back to the Widget Type or let’s actually go Manage Display and let’s go to default e-mail link, okay so that is set up right and let’s go to actually view this.

Don’t be afraid to use some print statements or debugging statements to actually … for instance in this case I’m going to display the items, don’t be afraid to go ahead and add your debugging statements and look through what’s getting passed. As you can see there’s one item, it’s an array, the delta of it is 0 and it’s this e-mail address.

So as I said before; don’t be worried about changing the code or playing around with it when you’re learning because that’s just … I’ve found at least personally, that’s the best way that I learned, is actually digging in to the code, changing things, figuring out what I can do to improve the code, what I can do to break the code all different kinds of fun things to really learn how the module is interacting with Drupal.

That’s it for this time, keep in mind as you go through this module and other modules there are issue queues on for this module and other modules and maybe you will be able to find the bugs, fixed bugs, post patches and overall just help the Drupal community by promoting better modules and increasing the quality of the code and just all around making modules in Drupal even better.
So keep that in mind as you’re going through this and as you’re learning, it’s never too early to try to contribute and most of the times you’ll find other developers very helpful in helping you get started. If you have any questions as always you can contact me on Twitter, you can use which I urge you to subscribe for the newsletter, you can send me an e-mail, you can see the e-mail right there, go ahead and just send me an e-mail if you have any questions, I’ll try to answer every question that I get, I can’t always do it but I will give it my best attempt and I’ll try to get back to you.

If I don’t get back to you in the first few days don’t worry, sometimes especially around the holiday season and e-commerce shops getting launch, it’s been a little bit hectic but I will get to you, don’t worry and I will talk to you again next time and thank you for watching the Daily Dose of Drupal.