FREELessons: 7Length: 56 minutes

Next lesson playing in 5 seconds

  • Overview
  • Transcript

2.1 First Steps

Stimulus takes a different approach to other frameworks and allows us to separate markup and behavior. But this means we need a way to connect our JavaScript code to our elements. I'll show you how it works in Stimulus in this lesson.

2.1 First Steps

There are many ways that we can get started with Stimulus. One of them is a starter package. If you go to the GitHub repository for Stimulus, you will see the Stimulus starter. Now I personally don't like using these starter projects. Primarily because when it comes to actually writing an application, I don't start with these starter projects. I start with whatever I'm using for the server. So that could be a Laravel project, an ASP.NET project, an Express project, things like that. So if you want to start with the Stimulus starter, then feel free to do so. I mean, it's great to get up and running quickly to play around with. But as far as this course is concerned, we're not going to be using this, instead we're going to start completely from scratch. Because the idea is we are either creating a new project or we're wanting to add Stimulus to an existing project. That makes much more sense to me instead of using the startup project. So, we're going to start by using a CDM and then eventually we will pull in Stimulus using node package manager and we will add it to a build process. So it probably goes without saying that if you don't have Node and NPM installed on your machine, that you need Node and NPM installed. And especially for this course, because we are going to be using some Node packages to run an HTTP server. It's not going to be an express application or anything like that but when working with anything web related, I like to have an HTTP server to actually serve my files. So that's what we will be doing. So if you don't have Node, just download the latest LTS. Make sure that NPM is checked whenever you are installing it, it is by default, and then just go from there. So once you have Node and NPM, the first thing we're going to do is create a project. So I'm just going to create a folder called stimulus. You can call it whatever you want. And we will say npm init, and I'm going to force all of the default settings, because well, I just don't need to set any of those things. And the node package that we're going to be using for the HTTP server is called lite-server. And let's save that as a dev dependency. And then once that is installed, we can actually get in and start writing our application. Now there's a few things that we need to do in order to finish setting up this project. The first is going to be adding a script to package.json, I am just going to call this dev, you can call it whatever you want and it's simply going to call lite-server and we're done there. Now, we are going to create a new config file for lite-server, it needs to be called a bs-config.json, and this is going to have a single property called server. Now what we want to do is tell lite-server where the public folder is. That would be where all of our HTML, the things that are actually going to be served. That property is called baseDir directory. And then we simply specify what that directory is going to be. I like using the folder called public for the public things. Once again, you can call it whatever you want., but I am going to stick with public and we're good there. So now we just need to create that public folder and inside of here, we're going to put all of our files. So the first is going to be an index.html file. Let's create another file called app.js. This is going to have the code for bootstrapping our application, as well as our first controller class, and those are really the only two files that we need to create right now. And we're going to start with the mark up because in a traditional web application that's where we typically start. Now I use the term traditional web application. Stimulus is not something that we would use to write a single page application. We have many frameworks for that purpose. Stimulus is not one of them. It doesn't track state, it doesn't automatically update the DOM when state changes or anything like that. Instead it gives us a better way of writing traditional web applications. The applications that we have been writing for many, many, many, many, many years. So, the project we're going to start with is going to be a simpler greeter, where we have an input element. We click on a button and we get a message saying hello and then whatever we type into the input element. So in a traditional application, we would start with a div element that has an ID of greeter-container. And then we would have our input elements that would normally have an ID of greeter-name, things like that. Then we would have our button, which would have an ID so that we could find it and hook up a click event listener. And then we would need something for the output. It could be an alert box. But it's more fun to have an actual element that we can display in the document. So that's what we would have, one, two, three, four elements all with ID attributes that we would then have to use inside of our JavaScript to find those elements to hook up whatever events we needed. And then the code for grabbing the value from the input element then using that in the output. Well, the problem there is all of the ID attributes that we have really tightly couples all of our markup to the JavaScript that is looking for those IDs. Now, yes, we can get around that by using other attributes, and that's exactly what Stimulus does. So what we're going to do is add an attribute called data-controller. So the idea is we have these controllers that are going to have properties that map to what we call targets instead of our markup. So like we have our input element here, this would be where we would type in the name. So this would be a target, the target is something that we want to retrieve from the DOM either to get the value of or to set the value of, or to set the HTML. So we would say data-target, and then we would give it a name. Now, in this case, we don't just say name, or who to greet, or things like that. Instead, we use the name of the controller and then dot, and then whatever name or property that we want to say. Property makes more sense because what we end up with is very much a property in the JavaScript object that is bound to this markup here, so we have a target. And this p element would also be a target that would be where we output things. So let's go ahead and say data-target and that would be greeter,output. Now you might think why do we have to specify the controller here when we are inside of a containing element that has controller. Well we will see that because we can actually have multiple controllers connected to a single element. So that's kind of neat and we'll see that here in the later lesson. So let's go to our JavaScript and let's have an immediately invoked function. We're going to wrap all of our code so that it is protected. Now I'm going to be using all of the new wonderful syntax. So for right now you definitely want to use a browser that supports it, Chrome, Firefox, I don't know if Edge does, but if it does then feel free to use that as well. Eventually we will get to where we're using Babble and all of that so that it doesn't matter, but for right now it kind of does. Now, since we're using a CDM to pull in stimulus we're not going to be able to put any of our controllers inside of any external modules. We could, but then we would have to incorporate require or some module loader so that it will load those and then bring them in. And so we're just going to keep things simple. And the first thing we want to do is create our app. Now it doesn't matter how we get Stimulus. We always need to create our application. So we do that by calling a start method on Stimulus.Application. That's going to start our application. Then we can use that app object to register our controllers. So we start with passing in whatever name that we want to use for the controller. So if it was a helloWorld, we could do something like that. In this case, we want to use greeter. So we have a controller called greeter, and then we need to specify the class for the greeter controller. And so it's going to be just a normal JavaScript class. It extends stimulus.controller and then we have our code for the controller. Now, there is a method that every controller has called connect. Whenever a controller connects to the elements in the document then this connect method is going to execute. So we could say console.log, then we could say "Greeter controller connected to element". And then whenever we view this in the browser we're going to see the message in the console. Now we haven't started our application so let's say npm run dev. That's going to start the web server, and it's going to pop up whatever your default browser is. Let's see if this works. Let's pull up the console. And yes, Greeter controller connected to element. So apparently Edge does support all of that new, wonderful syntax. I'm not going to use Edge, I'm going to use Chrome. So there, and once again, if we pull up the console, we see greeter controller connected to element. So remember that we specified a couple of different targets. We have the name and the output. So what we want to do then is tell our class that hey, we have some targets out there. Now, we need to specify this as static, because that's what the controller is going to be looking for. A static property called targets, and this needs to return an array of the names of the targets. Now in this case, we don't have to say We just use the simple names, name and then output. Although let's do this. Instead of using name, let's say input output. That makes a little more sense and that way, we're not confusing a name with anything else. So we have our two targets, input and output. What this is going to do is create two automatic properties inside of our class. One of them is going to be called input target, the other is going to be called output target. So we could do this, we have connected to the controller, and then let's say this.inputTarget. Now this.inputTarget is the element itself. This is that input element. So that means that we have at this point in time all of the properties and methods for that input element object. So we can say value = Bob, and that is going to put Bob inside of the input element. So that's whenever we go to the browser, there it is. That also means that our output target is that actual p-element. So we can say outputTarget and then innerHTML and 'This is the output'. And once again, whenever we go and view this in the browser, we don't see that text there. Instead, we have an error, cannot set property 'innerHTML' of undefined. And that is because I misspelled output. So there you go, and now we see this is the output. So in this lesson, we set up our project and we saw a little glimpse of what Stimulus can do for us. We created a controller. We connected that controller to an element and we set up a couple of targets. In the next lesson, we are going to do two things. We are going to set up an event for our button element and then we are going to re-use our controller for a completely different set of elements.

Back to the top