Description

Output the HTML template to a file

9.5: Handle Node.js Asynchronicity

Could consider this application complete.
Created a Node.js application that asks for your input & creates an HTML page => the main objective at the the outset of this project.
If we open the generated HTML file in a browser the output looks like the following image:
NEXT: To complete this portfolio is to add a style sheet, as per the final GitHub issue.
In this lesson, TO DO: -- Understand how to use the fs module to copy files from one location to another. -- Create JavaScript Promises to handle asynchronous functionality in a cleaner way.
NOTE: Up until now, only worked with executing asynchronous JavaScript code that returns a Promise, but haven't really looked to see how Promises work.
Will create our own PROMISES to clean up & handle asynchronous code.

GOAL: final portfolio website, complete with a style sheet that looks like the following image:

Final portfolio website with style sheet

Will download a style sheet & use that instead of creating one. Can reuse it for future projects.

STEPS:

Finalize output with a style sheet:
- Download a style sheet & use the <**fs***> module to copy the file when we generate the HTML code to create a finished directory for the portfolio.
Write a file using Promises:
- We want to remove the use of callback functions & clean up the code. Let's create our own PROMISES to use instead.
Copy a file using Promises:
- Because we know how to create our own Promises, let's apply that knowledge to copy a file as well!
Export the functions and wrap up:
- Export our 2 functions for handling the project's output from the generate-site.js file & import them into app.js to include in the Promise chain.
Save your progress with Git:
- Merge our feature branch & close the GitHub issue to finish up our application.

9.5.3 Finalize Output with a Style Sheet:

Download the style sheet it to the <src> folder in the project's directory to keep it in the same place as the HTML functionality: https://static.fullstack-bootcamp.com/module-9/module-9-stylesheet.zip
Should look at how we expect the finished output to work, before we write the function for copying this CSS file.
Currently, we're writing the finished HTML file to the root of the application. Need to create a subdirectory for the final output, because we will have a finished product with 2 files.
Create a folder called <dist> in the project's directory. This stands for "distribrution", which is a common name used in web development to indicate that the contents of that folder are exactly what we need for the final product.
We only need the HTML & CSS FILES, & none of the JavaScript we used to create them, for the deployment of the portfolio site. -- This <dist> folder can help us distinguish the production-ready code to deploy from the working code that gets us there.
Change the <fs> code in <app.js> to have the file written to this path instead of <index.html>.
Update code as follows:
The <index.html> file will be created in the <dist> folder, when we run the code.
IMPORTANT: The <dist> folder needs to exist for a file to be created inside it. If it doesn't exist, you'll get an error. The fs.writeFile() method WILL NOT CREATE a directory to place the file in if it doesn't already exist. When using <fs.writeFile()>, we need to make sure the directory we're writing a file to already exists. This can be done manually or by using the <fs.existsSync()> method. -- The <fs> library has functionality to create a directory, however, so you can always read the documentation for it and implement such a system yourself!

Copy the Style Sheet:

Add the functionality to copy the <style.css> file from <src> to <dist> every time we create a new portfolio.
Use <.copyFile()>, another method of the <fs> library. Refer to the Node.js API documentation for the File System library: https://nodejs.org/docs/latest-v12.x/api/fs.html#fs_fs_copyfile_src_dest_flags_callback
<.copyFile()> method works similarly to the <.writeFile()> method ==> Provide 3 sets of data as function arguments:
1. The source file's location, so they know what file we want to copy.
2. The copied file's intended destination & name.
3. A callback function to execute on either completion or error, which accepts an error object as a parameter so that we can check if something went wrong.
The implementation of <.copyFile()> will look like the following:
When we place this code into the application & run it, it will find <style.css> in the <src> directory & create a copy of it in the <dist> directory.
Rename it to <style.css> because we're working with a style sheet - can rename it to whatever we want upon copying.
Then if there's an error, we'll let the user know & stop the <.copyFile()> method from running with a <return> statement.

Where do we want to include this functionality?

It should probably go in the same <.then()> callback as the <.writeFile()> method -- so that it doesn't execute until we're done answering the prompts.
When dealing with asynchronous code: Must consider where to place code -- can have both <fs> functions run concurrently (because one isn't dependent on the other), but it makes it more difficult to determine what went wrong if an error occurs.
To execute the code in order: Have the <fs.copyFile()> functionality occur inside the callback function for <fs.writeFile()>. -- this way, we know that the <.writeFile()> method successfully created the HTML file before we attempt to copy the CSS file.
Update the <.fs.writeFile()> in <app.js>:
We wait for confirmation that the <.writeFile()> method ran successfully.
When we get that confirmation (which in this case, means not receiving an error), we then execute the <.copyFile()> method. -- this isn't mandatory for app to work, but it does make the app run its functions one at a time, making it easier to track what's going on when.
Run <app.js> & answer all the required prompts from the command line.
Both <index.html> & <style.css> should be created in <dist>.
If any error printed to command line/it doesn't look like this ==> check that <dist> folder is created in the correct location, directly at the root of the project's directory.
If run successfully, open <index.html> in the browser.
See new portfolio - should look like following:
DONE!
Current code in <app.js>: a mix of callback functions & Promises.
Both are completely valid ways to handle asynchronous functionality, but putting them together makes the code harder to read & understand (esp. in the <fs> methods (where we're executing a callback function inside of a callback function, which also occurs inside of a callback function. -- aka the Pyramid of Doom or Callback Hell. -- https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Introducing#promises

Refactor the current <fs> functionality to use Promises instead of callback functions in <app.js>

Refer to following code:
Note: <writeFile()> & <copyFile()> functions - where did they come from?? We will create these functions in a new file called <generate-site.js> in a new <utils> subdirectory.
Go to next page: 9.5.4 Write a File Using Promise.

9.5.4 Write a File Using Promises:

aka refactoring the asynchronous code with Node.js.

Callbacks and Promises:

2 ways to handle asynchronous code in JavaScript:
1. callback functions
2. Promises
seen & used before in previous projects.

Used callback functions as follows:

Browser event handling, (e.g., clicks, form submissions, change events)
Timers (e.g., <setTimeout>, <setInterval>) where we instruct the code to execute a function after a certain amount of time or on a schedule.
The <fs> library methods, -- when we instruct the computer to work with the file system in some way, & -- when it's done, it executes a function we provide to let us know how it went.

Used Promises as follows:

HTTP requests using the browser's <fetch()> functionality -- (once to make the request & get a response & then again to convert the response data to JSON format)
<inquirer>, which packages up user answers into an object & returns it into the function we include in the <.then()> method.

2 Examples of Asynchronous code:

(callback function vs a Promise-based function): Asynchronous code - callback function vs Promises

Lesson Goal: Learn how to set up this type of functionality.

Create the First Promise:

Create a <utils> subdirectory & a file called <generate-side.js> that goes inside it - in the application's root directory. -- (naming subdirectory <utils> because the functionality has to do with utilities used to get the app working.
Port all of the <fs> functionality (currently used in app.js) over to the file <generate-site.js>.

Note: To use the <fs library in a file, import it using the Node.js <require()> function.

Import <fs> into the file, with following line of code at the very top:

Will create 2 functions that return a Promise:

one function for writing a file (i.e. the HTML file).
another function for copying a file (i.e. the CSS style sheet). -- That means we'll execute an asynchronous function that enables us to use <.then()> & <.catch()> methods to handle its response.
- Create the function write files ==> take the <fs.writeFiles()> function & contextualizing it to be Promise based. -- First, create the Promise. -- Then, work in the <fs> functionality we're looking to achieve.
- Create the following function, the first JavaScript Promise, in <generate-site.js>:

What does that mean? -- Refer to when we used the browser's Fetch API <fetch()> to request data from a third-party server. -- We executed a function that had a goal of returning data we could work with in the app, but that data isn't present in the app at the moment. -- We use <fetch()> to ask for that data from another server. -- We can't control how fast that server responds to us ==> what happens next is out of our hands.
This is where Promises come in.

To create a Promise:

We need to create a new Promise object using the JavaScript keyword <new>.
This Promise object acts like a container that allows us to run code that at some point will be in a status of "pending", which means that the code has started to run but is waiting for a response.
This could be for HTTP requests like <fetch()> or even timed events like <setTimeout()>.
Inside the parentheses for the new Promise, we provide it with a function that accepts 2 functions as parameters: <resolve> and <reject>.
From there, we can write whatever asynchronous functionality we need to execute, & run: -- the <resolve() function when the code executes successfully or -- <reject()> when it fails to execute successfully.
Update our new <writeFile> function to actually write a file using <fs>:
We're using the same <fs.writeFile()> function that we have in .
This time, we're contextualizing it to a Promise and accepting the HTML file's content as a parameter.
If we were to execute it, it would look like the following code:

IMPORTANT Feel free to execute this code in generate-site.js. Just know that it will look for a dist folder inside the utils folder, and may throw an error if it doesn't find one. It's a good way to test the .catch() functionality, though!

Summary: Created first JavaScript Promise!

More JavaScript libraries have moved away from the classic callback function approach to asynchronicity & have adopted this Promise-based approach -- since their inception in the ES6 spec. -- makes the code more predictable & cleaner when we execute it.

NOW: We have the functionality for creating the HTML file handled as a Promise.

Compare how the code looks executed in <app.js> earlier, then look at how the <fs.copyFile() method's code looks.
How writeFile was executed in app.js earlier:
Current writeFile () in <generate-site.js>

9.5.5. Copy a File Using Promises:

Need to create one more function:
need to take the <fs.copyFile()> functionality & turn it into a Promise-based function.
just like the previously created <writeFile()> function.
Hints to create this function (refer to the <writeFile()> function that was just created in <generate-site.js>:
1. Create a new function called <copyFile> in <generate-site.js>. It doesn't need to accept any parameters.

Make <copyFile()> return a new Promise object, like we do with <writeFile()> above.
Move the <fs.copyFile()> code form <app.js> into the returning Promise object's function into the <copyFile()**> function:
- (use <writeFile()> as a guide:
If there's an error, <reject()> the error and return out of the function:
If it's successful, <resolve()> it with a success message:

Done with writing this JavaScript Promise for <copyFile()> function!

9.5.6. Export the Functions and Wrap Up:

Now we have the 2 functions for handling the project's output.
We need to export it from <generate-site.js> and import it into <app.js> to include in the Promise chain at the bottom!
Earlier, in <page-template.js>, Used <module.exports> to export only one function.
Need to export 2 functions both at once, using <module.exports>.
<module.exports> supports exporting data any way we need it to be exported.
module.exports can only be used once in a file. If we need to export multiple functions or data in a file, we need to set module.exports to an object or array.
Place the following code at the bottom of <generate-site.js>:
We're exporting an object with the two functions, <writeFile()> and <copyFile()>, used as methods, <writeFile> and <copyFile>. Very confusing & redundant to use the name of the function as both the method name and the value of the method.
Can simplify this by using another feature from ES6, as follows: -- This is aka shorthand property names: if we have a property key name with the same name as the value we're associating with it (e.g., <writeFile: writeFile>, we can just say , and Javascript ES6 (ECMAScript 2015 aka ES6 was the 2nd major revision to JavaScript) will understand that we're using <writeFile> for both the property name & its value.
Now we have the 2 functions (writeFile, copyFile) being exported from <generate-site.js>.
We can import them wherever we need them, i.e. <app.js>.
In <app.js>: -- Remove <const fs = require('fs')> at the top of <app.js> , as we're no longer going to use the <fs> library in this file.
Add the following line to the top instead:
This will import the exported object from <generate-site.js> allowing us to use <generateSite.writeFile()> and <generateSite.copyFile()>.
NOW, we can export & import multiple sets of functionality or data between files.

Simplify code, using object destructuring:

Change <generateSite> const variable to look as follows:
We exported an object from <generate-site.js>, so we can use object destructuring to create variables out of those properties instead of having to use dot notation. -- Keep code looking clean: use object destructuring instead of using <objectName.methodName()> notation to run the functionality.
Double-check the Inquirer prompt Promise chain at the bottom of <app.js> and confirm that we're now using these new functions instead of the <fs> methods.

NOTE:

A Promise chain is a series of *Promised-based functions that run in order. Instead of having each Promise return to its own <.then()> method, we can return the function within a <.then()>'s function and chain another <.then()> method onto it.

The Inquirer prompt Promise chain at the bottom of <app.js> should look as follows:

Inquirer prompt Promise chain at bottom of (app js)

CLEANER CODE! No more callback functions happening inside of callback functions.
All of the asynchronous functionality is now Promise-based.
We can continue to return the separate functions' output into the next <.then()> method.
BEST PART: We only need to write one <.catch()> method to handle any error that may occur with any of the Promise-based functions. -- If we need to execute a Promise's <reject()> function, it will jump right to the <.catch()> method.

Reiteration of this function's flow:

promptUser function

1. START: Ask user for their info with Inquirer prompts;

Inquirer prompts

this returns all of the data as an object in a Promise.

2. The <promptProject()> function captures the returning data from <promptUser()>.

promptProject function

We recursively call <promptProject()> for as many projects as the user wants to add.
Each project will be pushed into a <projects> array in the collection of portfolio info, and when we're done, the final set of data is returned to the next <.then()>.

NOTE: (a recursive function can be defined as a routine that calls itself directly or indirectly)

3. The finished portfolio data object is returned

as <portfolioData> and sent into the <generatePage()> function,
which will return the finished HTML template code into <pageHTML>.

4. We pass <pageHTML> into the newly created <writeFile()> function which returns as a Promise.

This is why we use <return> here, so the Promise is returned into the next <.then()> method.

5. Upon a successful file creation, we take the <writeFileResponse> object

provided by the <writeFile()> function's <resolve> execution to log it,
and then we return <copyFile()>.

6. The Promise returned by <copyFile()> then lets us know if the CSS file was copied correctly

If so, WE ARE DONE!

The Inquirer prompt Promise chain at the bottom of app.js

SUMMARY: PROMISES

benefit to code readability.
used to execute asynchronous functionality that reads in a step-by-step manner helps make code predictable.

IMPORTANT:

Now have the full application in the <dist directory.
Remove the <index.html**> file at the root of your application
don't need it anymore.

9.5.7 Save Your Progress with GIt

Commit and push your feature branch (feature/finished-site) to GitHub.
Merge your local feature branch (feature/finished-site) into your local develop branch and push develop to GitHub.
Close your GitHub issue regarding this feature.

Merge develop branch into main branch.

How to deploy this application:

Other people could see the output of the project in the <dist> on GitHub pages if you choose to create a repo for it and host those files. BUT NOT the PROJECT ITSELF.
This is a Node.js application that runs from a machine (specifically the computer it was created on) and not a browser.
Therefore, we CAN'T deploy this to GitHub pages.
If anyone ever wants to look at the application, they will have to CLONE it to their own local machine and run it from there.
IMPORTANT: create a solid <README.md> file with instructions and explanations for how to use this application.

9.5.8. SUMMARY RECAP:

We now know how to use the <fs> module to copy files from one location to another.
We've created our own JavaScript Promises to handle asynchronous functionality in a cleaner fashion.

And to recap the entire module:

We understand the purpose of Node.js and some of its uses in web development.
We know how to create and execute a Node.js application.
We learned a bit about the process for new features to be introduced into JavaScript and who is in charge of it (Ecma).
We can use new means of creating variables and functions in JavaScript.
We know a new way to concatenate variable data into strings using template literals along with some other new ES6 features such as destructuring and spread/rest operators.
We can modularize the Node.js applications to enhance code readability and reusability.
We know that Node.js has built-in tools and how to use them if we need to, such as the <fs> library.
We understand how and why to use the <npm init> command to create Node.js packages that are dependent on outside tools and libraries such as Inquirer.
We can use new array methods with object destructuring and -arrow function implicit returns_ to create succinct and readable code.
We can identify where the asynchronous functionality can be cleaned up and how to turn callback functions into JavaScript Promise objects.

This is only the first step to creating a back end for the applications.

*In the next module, we'll learn about two very important concepts in web development:

test-driven development (TDD) and
-object-oriented programming (OOP)-.

kitchen-boy / portfolio-generator

Title: Generate entire website #5