Module Development: Drupal 7 Renderable Arrays

By shane
Mon, 2012-10-29 19:19
2 comments
Daily Dose of Drupal Episode #39

Share with Others

Printing out straight HTML in your custom modules was so Drupal 6. Learn all about Renderable Arrays in Drupal 7 to make your Drupal 7 pages even more flexible.

In this episode you will learn:

  • The basics of Drupal 7 Renderable Arrays
  • How to implement a simple Renderable Array Drupal 7 example

Welcome to another Daily Dose of Drupal today we’re on Episode Number 39. Today we’re going to be talking about Render Arrays in Drupal 7, as always I’m Shane, you can follow me on Twitter @smthomas3 or you can go to codekarate.com and check out my other post and videos and sign up for the Code Karate newsletter.

So Render Arrays; if you’re anything like me, you maybe have worked on some Drupal 6 Module at Drupal 6 websites and you’re very familiar with how to output straight HTML using just a simple function for me.

There are Hook Menu or maybe in a Block. But what Render Arrays are, they’re replacement to the standard outputting of the Straight HTML and you should definitely go to this page on drupal.org if you’re not familiar with the Render Arrays to learn a little bit more because it’s very detailed, they walk you through why you should use them, why is it done, that type of thing.

It’s Node 930760 on drupal.org. I’ll go over just a real quick summary and I’m going to show you a quick example and then we’re going to get out of here. So Render Arrays; basically it allows you instead of putting just a string with HTML it allows you to output just the standard Drupal structure array with specific elements or items in that array.

So if you go down here it tells you why it was done and one of the reasons or the main reason is because you could alter things using Hook Form Alter in Drupal 6 but you couldn’t really alter what was showing up on the page.
So with Renderable Arrays it allows you to use Hook Page Alter to change the layout or content of the page right before it gets output. So if you look … this is the example down here that I’m going to show you so you can see it in action and you can of course read this things, it goes through on the bottom and it tells you the different types of properties.

So there’s a Type Property Mark-up and it says that’s the simplest property you can use, we’ll show an example with that, there’s a Theme Function and in the next episode I’m going to go over Hook Theme and how to create Custom Templates within a Custom Module so this is kind of the getting started before that but you can call a theme function whether it’s Drupal Theme function or a Custom Theme Function from one of your Modules, you can have Theme Wrappers which be an array of Theme Hooks and we’ll go from there.

We’ll start with a quick example; so as you can see I have a module, I’ll just call it my example and I’m going to use this module in the next episode or two to go over just different theming or Hook Theme type examples within a module.
Also I have my module page and this is pretty much taken almost exactly from here with just a few minor modifications so you can grab that on your own as well but we’ll go through it here. We have our Standard Hook Menu which just defines a page, it’s called My Page – HTML, gives its title, the Callback and it just sets Access Callback to True which means everyone will be able to go ahead and access this URL.

We also create a MY Page – Renderable where we’re going to show an example of a renderable array and give it a title, a callback and allowed everyone to access that as well and our first callback function; this is the My Page – HTML, it’s going to go ahead and create a variable printout, a simple paragraph tag and it’s to then create a simple list that has a first item, a second item and third item in it, at the end of it it’s going to return the output.

This is going to look very familiar to how you probably have built things in Drupal 6 and I know it looks familiar for me using a single variable and just adding on strings of HTML to it until you get to the end and you go ahead and return it, so that’s the first, we’ll go ahead and take a look at that.
So I’ll go to My Page – HTML on a Drupal site, if you’ll notice I’ll swing in here and show you that I already turned the module on, so I have the My Example Module that I turned on, go ahead and go to My Page – HTML and you’ll see my title is My Page with HTML Style Function and it has the Paragraph tag and it has the three items. Let’s go ahead and take a look at this second option; if you go onto My Page – Renderable.

So what this is going to be is it’s going to use just a renderable array and this is probably the most basic examples you can get but at least it gives you an idea of how it can be used to build a complex layout with this function. So it has one variable output and it’s an Array and it’s just a structured nested array.

The first item in the array went ahead and call it first_para … we can call that anything we wanted but that’s what we decided to call it here and it’s an array of type mark-up, which mark-up just means it’s going to be just simply HTML ,in this HTML we have a paragraph tag that’s going to be spit out that says a paragraph tag about some stuff.

Immediately following that we have another item of the array called Second Para and this one is going to have an item in the array and it has first item, second item and third item and then it’s going to use the Drupal Theme Function Item List. So then it’s going to output this as unordered list.

So we’ll go ahead and come back and try this page and you’ll notice it’s almost completely identical but it’s very different way s to get results. So you’ll notice if I flip back and forth it’s like almost completely identical, if you look here you’ll notice it’s just a very simple unordered list, if we go here you’ll notice that it’s basically the same thing but there are a few extra classes on it because Drupal … using that Theme Function gives it this item list class and adds a first and the last class to the list.

But besides that they’re virtually identical but what you get with this second option is you get the ability to then use as specified here. If needed you can use this Hook Page Alter to change the layout or content of the page at the last minute.

So in all honesty you may not need this if you’re building an one off simple module for some site just as a simple one page but if you’re going to be building a module that may need to be reused at some point or that you’re going to want to use a multiple sites using a Renderable Array adds a lot of flexibility if you ever need to comment and change it without having to actually modify the output or the HTML in the module itself.

So go ahead and go over this Rederable Array documentation, tomorrow we’re going to go over a Hook Theme Implementation and how to use some theme functions and template files within a module. That’s it for this time on the Daily Dose of Drupal and I will be back again tomorrow, thanks for watching.

Comments

Really good tutorial thanks a lot!

Post new comment