Example Lesson Videos - Drupal 8 Module Development: Blocks: Part 1 - Creating Blocks (Part 2 of 2)

Lesson Notes
Playlist
Transcript

Lesson Notes

These are two example lesson videos pulled from our Drupal 8 Module Development course.

See Full Course Syllabus and Schedule

Example Code For This Course

All the example code you see me using in this course is available as a git repository. This allows you "checkout" different versions of the code to move to any point in the course. Your primary assignment each week is to follow along with creating the modules you see me create in the lesson videos. You have two ways you can do this. Personally, I prefer to copy and type out the programs I see on screen, because I find it helps me remember things better. However, this can be fairly time-consuming, so there is a second option. Since I have provided many different versions of the code in the example git repository, you can watch the videos, and when you get to a checkout point (there will be an on-screen prompt), checkout that version of the code, read through it, and run it to confirm you understand what you've just watched. That will take less time, but I will leave it to you to decide how you learn best. Be sure you perform the clone operation in the correct folder, depending on whether or not you want to copy the code yourself or just use the example code to follow along. I discuss the appropriate locations in the code repository video.

Frequently Asked Questions

Do the lesson videos play on iPads and iPhones?

Yes, they work on both desktop/laptop computers and iOS devices.

How can I ask questions or get help?

You can ask questions about the lesson or get help with your assignment by posting to the class discussion forums and attending the weekly live Q&A sessions with the instructor. (online via webinar software)

Do I need to have my own website or hosting account to work on?

No, we will provide you with a development environment you can install on your computer. Installation and configuration of the local development is covered step-by-step in course lesson videos.

Playlist

Transcript

In this video, I'm going to show you how to create blocks programmatically. We will start off by creating a simple block that just prints "hello world." Now, of course if we are a site builder, we could just go on our Drupal site to structure, block layout and custom block library, and we could create a custom block that just said, "hello world" and then we could put that on the site. However, as a module developer, if we want to package up custom blocks and then ship them with our modules so that different site builders can load them on their site, then we need to follow a different process to declare those blocks programmatically in a module. And these programmatic blocks can be much more dynamic than what a site builder could do just manually typing something in. But we'll start with a very simple one that just has a static content, "hello world." To create a blog with a module, we will need to write a module that implements a plugin. The plugin system for Drupal 8 uses PHP annotations to declare certain functionality. PHP annotations are special type of a class comment on object-oriented code that allow you to give some configuration values to the system. So let's let's walk through an example and then I think it'll be a lot clearer. So we need to create a new module, and I'll call this module, block examples. So under the modules folder, under the custom folder, I will create a new folder, block examples, and then the next step is that I need to create a YAML file for that is the info file, so this should be block_examples.info. Now, notice NetBeans will automatically add the '.yml' for you. So now, I have my info file, let's put in some content. All right. I'll save that. I think that this '.info' file is mostly the same as we saw in the previous video. However, there is one new key that I want to point out which is the dependencies key. Dependencies allow you to specify that other modules that your module requires. So we're going to be writing some example blocks in this module so we know that this module cannot run without the Drupal core block module being enabled. So we can declare this dependency in our info file to make sure that no one can enable this module without the block module also being enabled. So the dependencies key is a list and so in YAML, because you can have more than one, you may want to specify three or four or five different modules that are dependencies for your module and you can do those. A YAML list just has this... the hyphen followed by the string. So if you had more than one, you know, you could put a second module that might be required, as well. For our case we only need the block module so we'll leave it just like this. So I'll save that file and now we need to create some code that implements the Drupal blocked plugin system. This code is going to be object-oriented, and it will use annotations as I said before to declare the plugin configuration. All object-oriented code in a Drupal 8 module should go inside a specific folder, the src folder. Okay. The src folder should be inside of your module folder. You don't really have any choice. You must put it in the src folder. Okay, inside of the src folder, you can write your object-oriented code. So this might be classes or interfaces. You can write that code in here and for the most part, you are allowed to decide how you want to organize that code inside of the src folder. Like other PHP code, the way that you organize the sub folders will affect your namespace as we'll see you in a moment, but you have the freedom to choose what you want. That said, there are some common conventions and in these videos when there's a strong convention about how the subfolder should be designed or what they should be called, I will tell you that there's a strong convention you should do it this way. That said, for plugins, if you are dealing with anything that is a plugin you do not have a choice. You must put plugins inside... classes that implement plugins must go inside of a plugin subfolder that's underneath src. Now, notice plugin starts with an uppercase P. Okay, you must have this exact same casing. And then inside of the plugin subfolder you also need to create a subfolder that is specific to what type of plugin you are implementing. So in our case, we're implementing a blocked plugin. So we must choose the folder name Block again with an uppercase B. So we now have some folders. We have underneath our module folder, we have src plugin block. Now that we have that, we can create a new file to hold our block class. So we'll call this file HelloWorldBlock. Okay, notice that NetBeans will automatically add the '.php' for you, so I'm just going to call this HelloWorldBlock because my class name is going to be called HelloWorldBlock. All right, so I have this empty file here. Let me paste in the code that we will use. Okay, and now I'll save this file and let's discuss what we have here. So let's start from the top. You'll notice the namespace line. So all of your classes this is not just four blocks but any object-oriented code that you write for a Drupal 8 module must have a namespace declaration. There is a built-in mapping for names spaces into Drupal modules so the beginning part here where you see the namespace Drupal\block_ examples, that is automatically mapped by the Drupal system to the src folder level of your code files. And that will happen for any module that you create. So we created in the previous video, we created this hello module. If we had created code files in there, the namespace would be Drupal\hello, because it always follows Drupal with the machine name of your module. After that, it follows the normal rules for namespacing so because we have a plugin and block subfolders underneath src, then our full namespace also includes that plugin and block after the automatically mapped part of the namespace. Okay, moving on to the next line, you see that we're going to use the BlockBase class. Our block... our hello world block class is going to extend this block base. If we take a look at that class... by the way in NetBeans, if you highlight a class name and hit either 'control B' on a Windows or the Mac 'command B' on a Mac, then you can jump to that class, and so if we look at BlockBase we'll see that it implements the block plugin interface, and this is actually what we need every class that is going to create a block, needs to implement a block plugin interface. So if I jump over there and take a look at that, you can see that there are several different methods that have to be implemented if you implement the block plugin interface, and you don't want to have to do this every time you're creating a block, a new type of block. So by extending the BlockBase class, it has some sensible defaults for most of these methods that have to be implemented for the interface, and so that way you can just, just override the specific functionality that you need to customize. This allows you to have a lot less code, less code for you to maintain, and so that's obviously good right there. So let's come back to the hello world block. This comment up here includes the annotation. Let's skip that and just go into the class. We'll come back and talk about the annotation in a minute. We have a single method inside of our class, and this is actually an overwritten method. It was defined in BlockBase but BlockBase gives its sort of an empty value. We have the build method here. The build method actually returns what we want our block to render. And it returns it in the form of something called a render array. In this video, I'm not going to go into detail about render arrays. There is another video where I will cover that in much more detail. But for now, let's just... what I have here is sort of the simplest render array. It is an array that is an associative array that has a single key markup or hashtag markup that returns a string, okay, hello world. And so this basically says we want this block to print hello world as its markup. So that's very simple. Now, you'll notice that it I don't just have the word hello world. I have this have this t, so I'm calling the T method that is part of this class. It's actually inherited here from BlockBase. And I'm wrapping the string in this call to the T function. So let's talk a little bit about what the T function is. Drupal has a very robust translation system or internationalization system built into it. Any content that is... or sorry. Any text that is generated by modules or Drupal core is able to be translated into other languages and by supplying basically a translation file and that translation file maps the original versions. So in this case, something like 'Hello World', the original strings with the strings in another language. So if this were being mapped to French, maybe it would say, "Bonjour mon" or something, whatever the French version was. And it could be translated to Spanish, in Swahili and many different languages by providing different translation files that map the English to those other languages. Now, I'm not going to show how to do that in this video, but it is important as a module developer that anytime you work with strings or text that will be displayed to the user, that you provide the opportunity for those strings to be translated, and that's what the T function does. Instead of just returning 'Hello World' by itself, I returned this t(Hello World) and that you can think of it as that routes the 'Hello World' through the translation system of Drupal. Drupal can then decide what language is the user that the actual person who's viewing the website, have they requested a specific language version and does Drupal have a translation of this string in that language? If so, Drupal will automatically make that swap. So if it does have a French translation of the string and the person is asking for French, it will automatically provide French to them. And as a module developer you don't necessarily have to do anything to enable this. Now, I will say, you can package, there is a way you can package some translation strings with your module. I'm not going to go into that. But even if you don't, if the end user wants to provide or the site builder, I should say, wants to provide strings to do these translations, they have the capability of doing that, because I've routed this through the translation system. So the key thing you need to take away even if you're not doing any translation yourself is any time you return strings that will be seen by... that are intended to be seen by users, you should wrap those strings in a call to the T function. Now, the T function is available in several different context for many of the object-oriented classes that we'll be working with. When you extend a base class such as BlockBase, it's actually available as a method in your own class. That's just there for convenience. But it makes it easy because you can call this T as the method and then pass the string. All right, so that is our build method that returns the markup that should be displayed. So let's turn back to the annotation now. The annotation is this part right here. It's the comment just before the class. Okay, so notice that the multi-line comment, it has two stars or '/**'. It ends with '*/'. The first part of this is actually a standard class comment. This is not part of the annotation. This is just a comment like you might put on any code. The annotation starts here at the @Block section. @Block says that this class declares or this annotation declares a block, a block plugin, and it takes two key values. The first is 'id' and the second is 'admin label'. The 'id' must be unique string that identifies this block or this block class. So it must be unique throughout the entire system. So in order to avoid any collisions with other modules, the convention is that you should use your module name, the machine name of your module, followed by some unique string that's unique between your different modules. So you can see my module machine name is Block_examples so my 'id' begins with block_examples (and then 'hello_world' is something I just added) that's unique to my module. Now, this needs to be a machine name so it needs to be all lower-case and underscores. It should be in quotes or double quotes like I've shown here, and then there should be a comma before the next key in the annotation. So the next key is admin_label. This is what the block will be called when the site builder goes to into the block interface to assign the block like on the sidebar. What is it going to be called? So in this case it's going to be called, Block Example: Hello World. Now, notice that I have that string wrapped in this @Translation function, I guess we can call it. This is the same thing as the key function. All right. It basically routes... because this string is going to be seen by humans. It's going to be seen in the admin interface, and so somebody might want to translate the string and so we should route this through the translation system so that translations can be provided. So the way you do that is with the @Translation function. It works exactly like 't' down here when you're in the actual PHP code. So that's everything to this class. And now let's go enable the module and try this block out. So we'll go over to extend, and we'll scroll down to the training section and you'll see that Block Examples is here. So I'll check it and click install. Now that it's installed, we can go to structure, block layout, and we should be able to assign the block to the sidebar. So if we go... I'll go down here to sidebar first. I'll click place block and then notice right here that our block is listed. All right, the block is listed, Block Example: Hello World. That was the name of this block that we declared in the annotation, and the category is actually being set by our module name. It's taking the human readable version of our model name from the '.info' file, and it's using that as the category. So let's place this block, and we'll leave all the visibility settings exactly like they are. Notice that the title is by default, set to the admin label. We'll leave it. We could customize it here if you were a site builder, but we'll just leave it for now. All right, so I'll take that. I'll drag it up to the top of the sidebar, and then I will save and let's go to our homepage and see if it shows up. Okay, there it is. It works. We've created a custom block. All right, now notice that we can go into our block code now, and then let's change this a little bit. Let's add an exclamation point to 'Hello World' and save the file, and then come back and refresh. And we can see that the exclamation point did show up in my block content. Now, that worked right away. However, if you are trying this and that doesn't work but when you change things, you don't see the change immediately. If the block has already been assigned and you try to change the code and it doesn't change that could be related to the cache system of Drupal 8. And so I'll just point out here in an earlier video when I had you set up Drupal, I asked you to disable the caches to put the system in development mode, and we did that with the settings.local file, and in the settings.local file, we disabled the dynamic page cache and the render cache. And because we disabled both of those, changes that we make in this block class are shown immediately when we refresh. If that's not happening for you, that may be because you haven't disabled these caches. I will have another video. There will be another video where I will talk about the cache system in more detail. We don't know enough yet to really discuss it properly so I will come back later and talk about how you can properly handle dynamic code where you want code that automatically shows an updated value when you are... when the caches are turned on. We can't do that yet, but as long as the caches are disabled, we should be fine for the moment. One last thing I want to show you before we wrap this video up is there is an optional key that you can pass in the annotation for a block class. So if I add a comma, I can add an additional key here, 'category' and this allows me to set the category as it shows up in the admin interface. Now, notice that I said before that the category was automatically set by your module name, but sometimes you will have either you'll want to customize that category name or you might have multiple modules where you want all of their blocks to be in the same category so they're grouped together, and so this you can set the category manually. Notice I'm still using that @Translation function because again, these examples category is going to be shown in the admin interface, so it should be translatable. So if I save that file after that change, I will need to clear the caches before or rebuild the caches before this shows up. So I can rebuild the caches. I will need to log into my virtual machine. I can do this with Drush. If I go into my Drupal folder, so in sites/drupal, if I run to drush cr (that stands for cache rebuild), so this will take a few seconds. All right, the cache rebuild is complete. If I come over here to the structure and go to block layouts again and if I click to place a block, notice now that the category here from my example block is 'examples'. All right, so you can customize that using the annotation. I'm not going to place this block because we already have one of them here on the sidebar so I'll just close that down. But, yeah, so that's how you can create a very simple block using the plugin API for Drupal 8.