2.2 Create the Module Routes

Now we're going to get into one of the more fundamental aspects of module development with Drupal 8. Now, when we are typically creating modules, it has to do with defining some functionality, some custom logic, within the web application. And a lot of times, along with that comes custom routes, and what do I mean by custom routes? Well, a custom route is nothing more than a specific URL area of my site that I wanna define within my application, in this case, within my module. And I want my custom code to execute and handle that request to that URL and do something with it. Output something to the user, do some sort of calculation, hit a database, go to a web service, any number of things. Now in this course, we're going to keep things rather simple because we're creating a calculator. But I'm gonna show you now how to create custom routes to be handled by your module. So just like before, when we created our calculator.info.yaml file, I'm going to create another YAML file within the same directory. And this time I'm going to call it, calculator.routing.yaml. So as you can see here now, I'm going to find some routes within my application, or within my module. Now, there's several different pieces that you can define for this particular route, or for all the routes that you're handling within your application. And we're gonna define several over the duration of this course, but for now, let's just kinda keep things relatively simple. So what I wanna do now is first specify the name that I want to refer to for this route. So this going to be kind of the quote-unquote machine name of the route that I can refer to all throughout my application. So in this case, I'm just going to keep it fairly simple, I'm going to call it calculator, and then within here, there's going to be several different key value pairs. Now, there's many different options in here, and you can spend a lot of time looking at the different routing options for this particular file. But I'm gonna keep it down to the absolute basics, so you can get up and running as quickly as possible. So the first thing that I wanna define here is a path, so I'm gonna use the path key. And within here, I'm going to define the route that I want to place my custom functionality. Now, this is going to be a relative path, meaning that if I had a website at www.myawesomewebsite.com, where do I want to put this logic? Well, maybe I wanted to put it at /my/calculator. And whatever requests came into that particular route, my application is going to handle. So in this case, I'm gonna keep things fairly simple, and I'm gonna put my path to be my/calculator. Nothing really crazy, but this is gonna kind of be the entry point into my application, or at least into my custom logic, for this module. Now, I mentioned before, I wanna be able to handle requests to that particular path, but how do I handle those requests? Well, that's the next thing that we want to define, so I have another category of name value pairs here, known as defaults, which is gonna be required as well. Now, there's a couple different things that you can put in here, but the first thing that we're gonna start with, is the idea of a controller, not only a controller, but _controller. Now, within this particular key value pair, what we're looking to define is a fully qualified class name, that's going to handle the requests that come into this path. And not only a class name, but also a method name that's going to handle this particular request, so what does that look like? Well, in single quotes I'm gonna specify a fully qualified name, which means the full name space as well as the class name. Now, we're gonna start to get into some object-oriented topics, and we're gonna start to dig into the world of PHP. If those things are a little outside of your comfort zone, I am going to take you through some of the absolute basics. But it would definitely behoove you to spend some time looking at some PHP fundamental courses within Tuts+. To really get a better understanding of it, if you want to really dive in and write some complex logic. But I'm gonna walk you trough the basics of the things that you need to understand in order to follow along with this course. So the fully qualified name here is going to be Drupal\calculator\Controller\, and then the name of my class, and I'm gonna call this CalculatorController. Now that's gonna be the class name, CalculatorController, the name space is gonna be Drupal Calculator Controller. But now I also need to define the method that's going to handle requests coming in to this route, and I do that with two colons, and then I specify a name. And we're just gonna say hello for now, we're gonna make some modifications to these in some upcoming lessons, but I just wanna get you started with something. So now we have our controller and our method that's gonna handle our request. There's one final piece of the puzzle that we're gonna need to put in here. And it's one final kind of key grouping that we're gonna put in here, and this is going to be requirements. And within requirements, we can specify a number of things as well. But in this case, what you're typically going to see is an _permission, and what that's going to allow us to do is to specify the permissions that are required. For a user that's attempting to access this path and this functionality, what's the absolute basics they have to have in order to get access to this? Now, what you're typically going to see when you're dealing with public-facing or application-facing modules and functionality, you're gonna see access content. So basically, what that means is that any user that comes into this particular path has to at least have the permission of access content. And basically by default, that's gonna be just about anybody that has a username and login, that can come into your site, come into your application. So this is the basic building blocks, we'll add a couple things to this and delete a couple things from this as we go throughout the course. But this is basically what you're looking at and needing, you need a path, you need a default section, which has an _controller. And then you need a requirements section that has an _permission, so what the heck does all this really do? Well, we only have one piece of the puzzle, but I wanna show you one more thing before we move onto the next step. So now I've saved my routing file, and as you can see here, I have my calculator. So ultimately, what I wanna do is, I want to be able to go into my application, navigate to that URL, and see something happen. But like so many other things within Drupal, before I can start to see some of my custom functionality, I have to clear my caches. So let's go back over to our website, and let's go into configuration and performance, and click clear all caches. Now odds are, we're gonna get an error, and you're gonna see something like this. Now, if you see something like this when you're doing your module development, don't panic, this is normal. You're gonna see this quite a bit, because this process of creating modules, it's a little finicky, and there's definitely some things you have to get used to doing as far as development. Not only with PHP, but understanding the ins and out of Drupal 8 and the APIs that are within Drupal 8, you're gonna see this from time to time. So what you need to do, or what you need to understand is basically, no matter where you see this, you're going to want to check the logs, well, what logs, Derek? Well, I'm going to tell you exactly which logs, so when you're dealing with Drupal 8, if you're doing it like I am, and I'm using MAMP, as I said before. So if I come over here into my applications directory, in my MAMP folder, if I scroll down a little bit into logs, you're gonna see php_error.log. So basically, whatever hosting environment you're using, you need to find your actual PHP error log. This is not gonna be in some Drupal 8 error log or anything like that, because typically what is going on here is, there are PHP errors. Maybe it's a syntax error, or something happened, so all you need to do is double click on that and open it up, and then scroll down to the bottom. And what you'll see down here is, you'll see a couple of errors, more than likely, or maybe one or two or something like that. Where you'll see an uncaught PHP exception, where class, and here's our fully qualified class name, does not exist. Well, thank you very much, console, that is exactly right, that is the problem. I haven't created that yet, even though I have defined it within my routing file. So that is exactly what I'm gonna do in the next lesson. I'm gonna take you through the process of creating your first controller.