Prepare the Example App as a Public Example Page

[00:00 - 00:08] So far we've been using the example application solely for our own internal testing. But with a bit of effort, we can turn it into an interactive example page.

[00:09 - 00:18] We'll use Bootstrap to style the example app. The Create React app documentation recommends the following steps for adding Bootstrap to a Create React app.

[00:19 - 00:24] First, we install Bootstrap. Make sure that we're in the example folder here.

[00:25 - 00:54] Then in the index file, we can import the root Bootstrap CSS file. In app.tsx, we'll get started creating markup for our example page.

[00:55 - 01:16] So the first thing we'll do is wrap the entire content in a div with the class name of container. And this is a Bootstrap class that makes the page responsive for any device type so that the content of our page will look nice no matter what device the site will be shown on.

[01:17 - 01:40] And I've started up the app here so we can see what we're building as we go. So the first thing I'll do here is add an H1 tag and I'll also add a preform atted tag so it will look like code.

[01:41 - 01:55] And we'll just put the name of the package. And in an H2 tag, we can copy the description and I'm going to copy that from the root package JSON description.

[01:56 - 02:08] Now for each parameter that we can pass to use, please stay, we'll make a track able state value for it. And then further on throughout this lesson, we'll build a proper UI element for each to update those values.

[02:09 - 02:14] So let's just start with the state values themselves first. So I'll put them right up here at the top of app.

[02:15 - 02:42] And so we know we have the titles and we can use the use state hook for this. And we'll just provide some sensible defaults for each as we go.

[02:43 - 03:02] So I'll just put new line and TypeScript as the titles. And we have the interval time here.

[03:03 - 03:17] We can take one second. We've got the animation type.

[03:18 - 03:38] And we'll take the animation type loop as the default. We have our favicon links, which I'll paste in here so you don't have to watch me type it all out.

[03:39 - 04:02] And we have our should always play and set should always play. And we're going to set that to true so the hook will be immediately running as soon as somebody opens this documentation page.

[04:03 - 04:20] And now instead of leaving these hard coded values into our actual hook call, we will use the state values themselves. And I'm going to modify this to just be interval.

[04:21 - 04:28] So it matches the name. And favicon links is expecting this type, not a string array.

[04:29 - 04:38] So let's be sure to set that in the use state call. And we need to import that from our package.

[04:39 - 04:53] Now let's get into building an interactive form for each of these fields, each of these state variables. So for the titles, we can use a text area and tell the user that they can comma separate each title.

[04:54 - 05:06] So I'll create a form group div, which is the bootstrap class for a nice looking form. And we'll add the label.

[05:07 - 05:26] This will be for title or rather titles. And we'll also use a pre tag to denote that this is an actual code based field for our hook.

[05:27 - 05:48] We'll do a line break and we'll use the small tag with the class form text and text muted. So it's a bit of a muted text color and you can comma separate multiple titles.

[05:49 - 06:05] And we'll add our text area, the ID of titles, form control. The value is of course the titles themselves.

[06:06 - 06:20] And on change, we've got our event. And the titles we want to set is the event.target.value.

[06:21 - 06:34] And we can split by the comma and set titles. We could try and pass the titles, but because of our array of one or more, we have to do a bit of a fancy setter here.

[06:35 - 06:58] So we'll basically confirm to type script that if the titles.length is greater than zero, then we can set those titles. So at least the first value, and then if there are more, the rest of them using slice.

[06:59 - 07:10] And otherwise, we just pass an empty array with an empty string. So that means our array of one or more type is satisfied.

[07:11 - 07:33] So we can format that so far so good and if I add something like title number three, I should expect that to start showing up and it does. And we can go down the line here for each of our state variables, adding an additional form group for each state variable.

[07:34 - 07:43] So for the interval, we have an input of type number, and we set the interval on the change of that input. That looks like this.

[07:44 - 08:11] For the interval type, I've decided to go with a radio button group because you can only pick one type of animation at a time. For the favicon links, I've also chosen to take a text area and also minded just as we did for the titles, the type criteria so that we need to check if favicon links is greater than one, then we set the state variable in this way.

[08:12 - 08:26] So type script is satisfied. So that looks like this, and I thought it was nice to add some existing fav icons to help the user add additional favicons to experiment.

[08:27 - 08:42] And finally, for should always play, I thought a checkbox would be a nice way to do it. And as we toggle here, we convert the boolean to a string so that when you un check this box, we see that it's false.

[08:43 - 08:52] So let's clean up what we have in our app so far, save that. And there's no warnings, so far so good.

[08:53 - 09:15] And now to take this interactive example page to the next level, it's fair to say as developers, we always appreciate a solution that's as easy as copying and pasting into our own code base. So let's create a code block component that will display the corresponding code associated with calling use, please stay.

[09:16 - 09:23] So to do this, we'll have to install a new library. So I'm going to kill the app process here.

[09:24 - 09:34] And I'm going to use the Prism React renderer library. So let's install that now.

[09:35 - 09:47] And within the SRC folder, let's make a new folder called components. And within this folder, a new file called code, highlighter.

[09:48 - 09:56] And this will be a React component, so we'll use the TSX file extension. And I use a React TypeScript plugin for templates.

[09:57 - 10:06] And for us, we want a React Pure Function component. And we can rename that to code highlighter.

[10:07 - 10:21] And I'll put in the lesson text the link to that Visual Studio plugin so that you too can also generate these templates. Now for this component, the only prop we should need is code, which will be a string.

[10:22 - 10:34] And we'll pull off this prop from the props value. And we can get writing the body of our function.

[10:35 - 10:44] And here in the return, I'm just going to paste in what Prism React renderer recommends as a default. Paste that in here.

[10:45 - 10:58] The only thing we're missing is a theme. And I'm going to import the Dracula theme because who doesn't like dark mode for all their code snippets?

[10:59 - 11:12] That's the themes and not star, but Dracula. So we can save this, format it, and let's use this in our app.tsx file.

[11:13 - 11:21] So I think it makes sense to put it right under the subtitle or the description here. So we can call code highlighter.

[11:22 - 11:34] And of course, we will need a code parameter. And the code we can construct by using string interpolation and all the various state variables here.

[11:35 - 11:50] So we'll do const code and back ticks for a multi line string. And we want this code string to essentially look like this call, but instead of these variables, we want the actual hard coded values.

[11:51 - 12:03] So it's immediately clear in our application what the use please stay call could actually look like. So we'll call the use please stay function.

[12:04 - 12:18] Then I'll do a new line here. And we have titles and we'll open the brackets and we'll take the actual titles state variable.

[12:19 - 12:30] And map over them. And we want to ensure that they are wrapped in double quotes.

[12:31 - 12:47] And then we want to join those back with a new line just for readability. And so far our code block is looking pretty good.

[12:48 - 12:53] I have to add a few spaces here. So it's nicely formatted.

[12:54 - 13:09] And let's continue on with the rest of our code block. We've got the interval, which is interval.

[13:10 - 13:25] We've got the animation type, which is animation type. And we've got the favicon links and this will look similar to our titles list here.

[13:26 - 13:49] We've got the favicon links, which we have to map over. And we want the favicon link wrapped in quotes.

[13:50 - 14:00] And then joined with a comma, a new line and some space. Let's see how that looks.

[14:01 - 14:04] Missing one space. And there we go.

[14:05 - 14:23] And finally we have the should always play, which is the should always play. And since it's a Boolean, we do have to call to string on it.

[14:24 - 14:34] And we get our should always play value. We can then delete the empty space here.

[14:35 - 14:43] And now it looks exactly as we would call it. And it's formatted as a linter might format a call to this hook.

[14:44 - 14:57] So this is already looking really good. As an additional nice to have, we can also reuse the code highlighter component to show the visitor to our documentation site how to install the hook.

[14:58 - 15:04] So I think the installation instruction supersede the code example. So I'm going to actually put it right here.

[15:05 - 15:26] And I'm going to use a paragraph tag and just put install with. I'll copy this code highlighter call and instead of this code, we can just put a hard coded NPM install dash, dash, save, react, use, please stay.

[15:27 - 15:45] And we may want to denote the second code block just by saying interactive code sample. Try changing some fields in the form below.

[15:46 - 15:59] And as yet another usability improvement, let's add a button to the code highl ighter component that will copy the code to the user's clipboard. So we'll hop into code highlighter.

[16:00 - 16:14] And here I'll add a fragment so we can add that button in below. And I'll do button with the bootstrap classes, just taking the primary color.

[16:15 - 16:28] So BTN primary. And we'll say copy code and on click.

[16:29 - 16:44] We will use the navigator API. clipboard and write text with this code prop that's passed in to our highl ighter.

[16:45 - 17:02] So we'll format this and we get a copy code button below each of our code blocks. And just to verify that it's working, if I copy this, let's paste it into a new terminal here.

[17:03 - 17:13] Looks like that works fine. And if I copy the hook code, also looks fine.

[17:14 - 17:30] Now just to clean up some spacings in app.tsx to make our page a little bit more readable, I'm going to add a top margin. So MT4 to this title here, just to move it down a little bit.

[17:31 - 17:49] And for each of these form groups, I'm also going to do the same and add a MT4. Just so each of these fields is a bit better spaced.

[17:50 - 18:02] And we can also add to our second p tag as well. And MT4 just to space it out from the first code block.

[18:03 - 18:11] So our example page has become a great documentation page. Use please stay is immediately running as soon as the page opens.

[18:12 - 18:23] And this code updates whenever any of these form fields change. And of course, the code is immediately copyable thanks to our copy code button.

[18:24 - 18:38] So in summary, we added the bootstrap library by installing the bootstrap package and importing it in index.tsx. We added state variables for each of the properties that can be set with use please stay.

[18:39 - 19:00] We changed use please stay to use those state values and then we created a UI element for each of the state values within our example app. After that, we created a code highlighter component which uses the prism react render library to render these very nice looking code snippets.

[19:01 - 19:08] So now that our example page is looking pretty good, in the next lesson we'll publish this site to github pages.