 Okay, here we go We're going to talk about the theme API if My remote works It should which it doesn't I don't like that Anyway, it's not just the remote that isn't working Just keynote crashed wait a second Didn't know it could crash, but it can and it did okay. Let's try the thing Yeah, that's better. Well, what are we going to talk about is the theme API? Well, first of all a few things to note I'm roof on the crew if you're not Dutch you won't probably be able to pronounce my name And we're going to talk about the theme API. I work at hoping her a Dutch web design company And we built sites for all signs all sites of companies and organizations like this branch organization a Local politics organization and this is us so Welcome to hopper Second thing if you have any questions Also, feel free to just ask them. Don't wait until the end and I say okay. I'm finished any any questions I will say that but if you get questions in the middle, then just ask them Good what we're going to do is take a look under the hood of Drupal This is the car of my father-in-law and he's really proud of the thing It's this is the actual car Well, I I'm not really a fan of those cars It's it's a Dutch make and he's really proud of of the car don't know why but it's his baby but it was nice for the Under-the-hood thing because He knows a lot about that car. He knows actually how the car works. She completely Stripped it out and build it up again from all the pieces. He knows every screw in the thing and He knows everything about the car. So and that really helps them to do everything you want with the car And I'm hoping to give you a little bit of that about the theme API of Drupal This should look familiar if you don't if you see this and you think well, what is this then you're going to have a hard time well the This is the call to the to the well-known theme function and it does a really a lot of magical things This function magically turns this into this And why and how that's what we're going to discuss and more importantly How can you change that behavior because you might like this output, but the theme function also outputs a lot of other different things and You probably don't like that. There's a lot of complaints about the HTML Drupal And even if you don't have any complaints about it then still you don't want you use sometimes for a theme once you change it because your client wants it to look some way and Your start if you're just stuck with HTML Drupal by default provides then you can have a problem well the function has What we call two parameters the first is the content of its links and We call that the theme hook It's actually tells the theme function what it is that you are going to give him and how it should Start how it should Should do something with it in this case It says I'm going to give you a list of links and I want it to be themed like a list of links and This part is called the variables and it's actually gives What should be themed so the content in this case the actual list of theme list of links and Which title you want above it? Well, you saw that in the HTML example that there was title up on top of it if you didn't well there was Back to the thing called the theme hook the theme function takes a look at what is called the theme registry To find out what it should do with the theme hook The theme registry is actually a Big filing cabinet it has a drawer for every available theme hook in Drupal if it if the theme function doesn't find your Your theme hook then it returns Nothing because it doesn't know how to do anything with it This is in the drawer for links. So if you specify links to the theme function, then it then it goes take a look at this first of all It has a list of What we call default variables so this are the available variables for the theme for the theming of links and This are and you see the default value. So for links the default value is nil There is a a part called attributes Which we didn't specify and there is a heading which by default is an empty array This is a variables array that we put in to the theme function in the example a few slides ago Then the theme function says, okay, I'm going to add those default variables to it and this is What we what you get them it? left the links and the heading part just unchanged and it added the attribute part so You can be sure that the theme function or template that you use Actually gets that attributes variable It's there by default and if the if the the user of your theme function doesn't provide it then the theme API itself will provide it for you the second thing that is in that list is What it actually should do in this case it says you should call a function and the function is called theme links That is a core Drupal function That's called that's located in theme dot ink if you want to look to take a look at it then you can and It defines all the logic that it needs to theme those links The second the the last thing that we're going to take a look at is called the origin information This defines where this see where this information that is in the in the theme registry actually comes from in this case It comes from the implementation of hook theme of the system module Well in this case it isn't that important, but you'll see a difference with this one This is what is in the in the registry for node It's a little bit bigger and we're going to step through it First it doesn't have variables array. It has something called a render element That means that we're going to put that it actually expects a render array and it's going to do something smart with that Well, this is an example of a render array for a node This I stripped off about everything only the real important parts the fact that it is actually a node Which node it is and in which view mode and language it is That's what I left the other on the on the dodge There's something like which fields are available and links that are been below the thing even comments and everything can be there But I left it out because it won't fit on the screen This somehow gets through Drupal render sometimes it's just Drupal render is called with that Build array that that render array in some cases. It's part of the bigger page array and Then some then in the end it will also run through Drupal render But Drupal render will call itself with that small part of the render array Drupal render will say ah, I've got a theme is node well, then I'm going to call the theme function with note as the theme hook and and the what I the rest I specify is just that render array and Then I leave it up to the theme function for the rest And I watch just yeah, then it creates then the theme function creates a variables array like this you saw from the the example on the on the previous slide that the value of render element was elements then it Gives the then it creates a new variable called elements and it just puts the whole render array in there and then the theme function just runs just as normal and It leaves it up to the rest of the definition of how it should be themed to handle with just that element spot You see that the other thing that is different is that it doesn't say you should call a function to theme this but it says you should call a template and the template is The node template node dot tpl dot PHP and it's located in theme says Bartek slash templates in this case I just used the default Bartek theme of Drupal and Well, it displays this the there is actually no real difference between a theme function and a template It's just an other way of writing things There is however the Difference in because it is a different way of writing things some solutions are more easy to write in a function than they are in a template I found a very short Theme function in Drupal in Drupal core. It's good. It seems just the more link At the top is a copy of the core theme function and I named it my theme So it is actually an implementation of that function in my own theme And I and at the bottom I created an equivalent template for that If I would create that template called more dash link dot tpl dot PHP then Drupal will say oh well now you created a template then I register a template for you no problem and Then it will ignore the default function that is in Drupal and it will be overridden by your template So it's just another way of writing things. You see that it actually is pretty much the same. It's just Just another syntax But some theme function in Drupal core and some if you do really fancy stuff of it Your theme functions can get pretty complex and then a template file becomes inconvenient so then you will If you experimented with the theme functions, then you will start using the more for the more complex parts of it the biggest part of the Note part of the note Entry in the registry is for the pre-process and process functions or most Themers actually think they're pretty scary They're not and I'm going to tell you what they do. So next time you won't think they're pretty scary What they do is the following We've seen that when you call theme note with some renderer array it creates a variable array like this This is a completely stripped-down version of the default Pre-process function for note that is in Drupal core or actually in the in the node module I left Actually, most of it out. It's a it's a very long function that will never fit on the screen and it's What it does it changes the variables array it gets the variables array as a parameter you see that here and You see that it has a Ampersand before the variables name that means that it is called by what's called reference and It means that the function is able to change the Variable variables array just like a hook alter would be able to change something You see that it adds a view mode from the elements parameter that it got and It finds the actual node object and it defines it puts it in an own variable and it puts it also in its own PHP variable so it can use it more easily in the other code You see that it defines the title there for example, but What we what we get if this would be the whole Pre-process function it isn't but if it would be Then this would be the new variables array it change the function changes the variables array to this and This makes sure that you can actually use dollar title in your template Because this variables array gets extracted to Normal PHP variables in your template and you can use them Another way of displaying the pre-process function is like some sort of pipeline the variables Start at the beginning of the pipeline and every function has the ability to change the To change the variables in the pipeline You see that I here also wrote down the process function There's actually no real difference between a pre-process and a process function The only difference is that the pre-process functions are run before the process functions That's really the only difference This is the list of pre-process functions that we saw a few slides ago for nodes Well, let's split them out a little You see that the first part starts with template the second part is about is Starting with module names and the third part is starting with a name of a theme so what it what happens is that first the the pre-process functions of Drupal core and of the fun of the module that actually defines the Theme hook so the node module defines that there is something called a note that Drupal can theme and It defines a pre-process function for it and that one gets up top and The others are just any other module that wishes to to alter the behavior of the default node processing and Bartik a theme also wants to change some things Well, you see that there are Functions called just pre-process and some are called pre-process node Well, the pre-process the normal pre-process functions are used for every template While pre-process node is Just used for the node templates There could have been some other functions. There are they don't exist, but those could have existed too So you can create a global pre-process function in your template that Every variables array that goes to a template comes through that function So you can change the behavior of every template And other modules can also add other pre-process functions Back to the entry in the registry. You see something actually pretty weird you Would expect that the theme and the the theme registry would say That's that new template that we found is defined by a theme, but According to the template to the theme registry. It's not defined by a theme It's defined by what is called a theme engine. The theme engine is a Piece of code that by default doesn't do very very much But what it does it calls some functions in Drupal core that Allows themes to be a lot more easy. You don't have to manually specify if you create a node tpl.php but Drupal will by default not recognize it if there would be no template engine the template engine goes Will search into your themes will find the template files that you create and will find the theme functions that you create and It will register them for you. So you don't have to specify that yourself The other thing that is displayed in this slide is that Actually the the base of the theme registry is formed by the modules the modules will define which things there are Available that can be themed and themes and basins can override the behavior So it's a very very uncommon that a theme will define a completely new theme hook for Most of the things already exist in Drupal and there's no real use case available for defining your own Theme hooks it is actually possible, but almost nobody does it this is the name of the default template engine in Drupal PHP template and Well, it inspects your theme and it finds every template and every theme function that is there for example, if you have a Set of templates like this No, that is page dot tpl dot PHP know a few few fields back links page dot tpl dot PHP and page from dot tpl this PHP well The the funny part about this is that actually in the theme registry by default there is no entry for no dash dash page it just doesn't exist and it will only exist if your If you define a node as a page dot tpl dot PHP in your theme Well first before we going to take a look at this these things A dash is equivalent to an underscore that sounds weird but in in in Drupal your theme Your templates all contain dashes your theme functions all contain underscores I don't know why that actually is theme functions can't contain dashes That's just technically impossible in Drupal in PHP because PHP will interrupt that that dash as a min sign and will try to to evaluate that expression and will go terribly wrong But I think somebody thought found that it was extremely ugly to have underscores in template in template file names, so All over the theme dot ink is logic scattered that converge underscores to dashes and the other way around The way that Drupal recognizes that node does this page to the tpl the PHP is By what we call a pattern for note the pattern is node dash dash because no doesn't explicitly define a Pattern then it will assume that this is the pattern for no to use so if your theme engine finds these The these templates in your theme and then we're going to take a specific look at No dashes page to the tpl the PHP it will strip off the extensions So only no dashes page is left and then it will convert all the dashes to underscores Because Drupal internally just uses everywhere underscores and then it will create a new Entry in the theme registry With the name no dashes page and this is what it contains. It says that it should It should call a template and which template well the no dashes page template and it is located in your theme and Well the render element part is just copied from the default node Entry in the theme registry and it says well actually I'm not a normal Theme registry entry. I'm just a special case of node base hook is node Well the same goes for theme functions For example links links but because links also doesn't define a pattern links and underscores assumed So you can create a function called my theme underscore links underscore underscore comments You can you can actually create it and it will it will be will be used sometimes It will be used to theme the links that are below comments then it will It will strip off the part that defines your theme name So the the my theme underscore part is ignored and this is the theme hook that will be created And this is what it will contain it will say okay, you need to call a function and That function is called my theme underscore links underscore comments and this is the variables that are that are available for that function and Again a base hook and a base hook is links in this case. It's just it just points to the other part and Well, we come up with what we've drippled will do with that those Drupal built in some cases Drupal will need to call this theme hook in Instead of the default theme hook because you don't want if you're theming the links below comments Then you want Drupal to pick up this well for links. It works like this Actually, this is done This is done somewhere in a render array, but to keep it a little bit Understandable you I wrote it down like this It will create a call to the theme function with a theme hook links underscore underscore comments And while it defines all sorts of variables array containing some links What you see is That That Drupal will Will start to look for a entry called links underscore underscore comments and if it doesn't find one in the registry It will take a look for links. Why it will find links because that's defined by Drupal core and Then it so if you don't define links underscore underscore comments, then it will Then it will automatically pick up the default This is what we call theme a theme hook selection by context because it is it actually which Theme who Drupal chooses doesn't depend on what is actually in the variables array, but it is depends on where it is used There is nothing in that array of links that makes Drupal say, oh, I'm think I'm theming links of comments and Drupal knows that because somewhere outside of the theme function the the logic says, okay, this is the links below comments You see that if you actually a little bit misuses that it Fuse creates a list of Available theme hooks and if you don't just specify one theme hook, but an array of theme looks to the theme function Then it will start at the top and take a look at the theme ratio. Well, can I just find this one? No, I can't well then I take the the next one and so on until it finds One that it can use With note, it's a little bit different Yeah We go back to to this build array We've seen this before and then theme node gets created and this is the variables array that it gets created And then we're going to take a look at that preprocess function again It gets the variables array and somewhere in that preprocess function is this code it creates a PHP variable for nodes and then it adds a Theme hook suggestion and there's a list of theme hook suggestions in your variables array and you can add items to that and That list of theme hook suggestions tell Drupal. Well, if you're going to theme this Then you might take a look at the registry again because maybe there will be an entry for a node There's this page and if that entry exists Then I want you to not to call the default behavior of nodes, but I want you to call The template is defined in that node dash dash page You see that views Back to the views call views misuses that Views could have also used that logic of the preprocess functions but it decided to to leave the old Drupal 6 behavior with a List of available theme hooks Well, because it in the logic of theme of views. It's a little bit easier to write it like that, but The problem with that is that it is actually impossible to change the order of those things so you cannot in your theme add something smart to Allow Drupal to pick up another template for a very specific use case. So this is not as flexible as this logic And that's the problem with you. So I think few should change that this but it requires a Real big change. So that will take some time Maybe I'll take I'll spend some time in it But it gets real complex when you want to do that. So I don't think that will be done soon Back to the node example You could for example change that array like this. I created I showed a little copy of Of that preprocess function for nodes at the top This is this is the Drupal the function that is in the node module and I stripped down About everything, but I left some important parts one is the view mode and the other is That it puts the node in another variable If you create a function called my theme preprocess node and your theme is enabled, of course then Drupal Will call this function after the default template preprocess node function and if you then create a line like this we At the first line of our function we create a specific variable for the view mode and at the second line We create a variable for the node and then we're going to use that we we add a theme hook suggestion for node for the node type followed by the view mode and For just node followed by the view mode and if you do that Then you can use these templates, so you can Change you can add this function and if you do that You can start creating a template just for a teaser view Well, actually that isn't always the smartest thing to do But it is a good example of the flexibility of the preprocess functions the well Some final things to note are the following Actually one final thing There is the develop module for those who have never seen that you should really check that out and it contains a A function that allows you to simply view the registry, so you install that module you enable it and and Then you go to the URL devels devels theme registry And it will show you the whole registry so you can take a look at what is there and what the theme function will do for you and It helps you with debugging Why Drupal won't pick up your template or all kinds of other? complex things Well, I promised you that I Would ask are there any questions? What is it? Yeah in Drupal 6 there is actually a real difference this is about Drupal 7 Now in Drupal 6 there were pre-process functions, but the pre-process functions just don't work on them on theme functions they just work on template files and And the other difference is the way that the overriding works You might have noticed in Drupal 6 that if your theme doesn't have its own node dot tpl dot PHP than a node page dot tpl dot PHP won't work You can try that if you create a node dash page dot tpl dot PHP in your theme You might you would expect it to pick up But it doesn't if there is no node template in your theme or actually More complex if the node template isn't in the same directory or a directory below the template Below the location where your No, there's a no dash page dot tpl is located You can experiment with that you can create a real weird behavior with that well The the concept of a build mode is that allows you to specify different ways of looking at a node in Drupal 6 it is a very Very very limited thing It just has a full note view and a teaser view in Drupal 7 that got a little bit more flexible and it allows you to add own build modes If you want to know more about that there is I think a session about display suite This conference. I don't know exactly when but they will tell you a lot more about that because display suite allows you to set up specific layouts for Specific view modes for an entity in general. So not just for nodes but also for users So if you want to know more about view modes, then that's a real real session. You should attempt Any other questions? well, then this was it well There there is they told me that there is a survey on on the Drupal Drupalcom website that allows you to to say what you think about the session. I will In the in my session, and I will upload the the slides there Thank you for listening and Have a nice conference