Organizing code

Purpose

Encapsulation: "The goal of encapsulation is the bundling or co-location of information (data) and behavior (functions) that together serve a common purpose."

"The idea is to group alike program bits together, and selectively limit programmatic access to the parts we consider private details. What's not considered private is then marked as public, accessible to the whole program."

Functions

There is a concept in programming called DRY. Don't Repeat Yourself. Which means that if we are coding and find ourselves doing the exact same thing more than once...we should find a way to re-use. Functions are made for this.

Three ways to declare functions in Javascript

Function Declaration


function mySuperFunction() {
   // Do stuff here
}

Function Expression


const mySuperFunction = function() {
    // Do stuff here
}

Arrow Function (Lambda)


const mySuperFunction = () => {
    // Do stuff here
}

Which should I use?

For the most part it really doesn't matter. Choose the one that makes the most sense to your brain and be consistant with it. The arrow function notation is more concise that the others, and so is used more often in callbacks, but the methods really are pretty interchangable.

Parameters.

Functions become much more reusable when we can customize them when we use them through parameters.


// not very useful
function doubleTwo() {
  return 2 * 2;
}


// more useful
function double(num) {
  return 2 * num;
}


// another example--single usecase
function selectNav() {
  return document.querySelector('nav');
}
// or making it more general and more reusable
function qs(selector) {
  return document.querySelector(selector);
}

Object literals

These are fantastic for organizing...but stay tuned for next week...

libraries/Modules

Dividing our code up into related functions is a great start to higher level organization, but we can take it a step further with ESModules.

First a few important facts about ESModules

ESModules are based around files...one module per file.
ESModules are strict by default
ESModules establish their own private scope.
Anything that you need access to outside of the module must be exported.
Exports can be default (one per module) or named (as many as you need)
You use the import command to use a module.
When you use ESModules you need to let the browser know by adding type="module" to your script tag ie.
```
<script src="main.js" type = "module"></script>
```

If we had a simple module for utility functions it might look like this:


// filename: utility.js
// wrapper function for querySelector
export function qs(selector) {
    return document.querySelector(selector);
}

// create an alert at the top of the page for 3 seconds
// requires the message to be displayed and the time in milliseconds.
export function alertMessage(message, duration=3000) {
  const alert = document.createElement("p");
  alert.innerHTML = message;
  alert.setAttribute(
    "style",
    "background-color:lightpink; border: 1px solid red; position:absolute; top:0; left:0; right:0; padding: 1em;"
  );
  document.body.appendChild(alert);
  setTimeout(function () {
    document.body.removeChild(alert);
  }, duration);
}

To use this we would import the functions we wanted to use in our main javascript file


// main.js...this is the file that you added to the html through a script tag
import { qs, alertMessage } from './utilities.js';
// now you can use those functions just like if they were declared locally.
alertMessage("I'm from the module!");

Examples

GPA Calculator

If we think about a gpa Calculator app that runs in the browser, how would we organize the code for that? What does it need to do?

Display the options for the user
Accept input from the user
Perform the requested operation with the user provided arguments
Display the result of the operation

Our program could be organized into two sets of functionality: code that is responsible to receive and display information, and code that will calculate the GPA with the user supplied input.

Let's break down our functionality a bit further:

Display input box for user to enter grades along with a button to kick off the calculation.
Add an event listener to the button that will do the following when clicked:
1. Get the string of grades from the input
2. Convert the string to an array (String.split(',')), clean up any extra spaces, and make the grades all uppercase.
3. Do a lookup on each grade to convert it to it's point value (ie A = 4.0)
4. Total up all the point values, and divide by the number of grades to get the GPA
5. Output the GPA to the browser

Steps

Start by creating two files in the sandbox: week3.html, and main3.js. Just like before add the HTML for a basic page, and a script element linking our JS to our HTML

Copy the following HTML into the body of your HTML file:


  <h1>GPA Calculator</h1>
  <p>Enter a comma separated list of grades.</p>
  <p>
    <label for="grades">Grades</label>
    <input
      type="text"
      id="grades"
      placeholder="comma separated list of grades"
    />
  </p>
  <button id="submitButton">Generate</button>
  <p id="output"></p>
  <script src="main3.js" type="module"></script>

Create two additional files. Call one gpa.js and the other ui.js.
Copy the code from the utility module example above as a starting point into the ui.js file.

Add two more functions to ui.js:


export function setHtml(selector, text) {
  qs(selector).innerHTML = text;
}

export function setListener(selector, event, callback) {
  qs(selector).addEventListener(event, callback);
}

Now we need to import in the functions we need from ui.js into main3.js. Add the following line to main3.js:
```
import { setListener, setHtml } from "./ui.js";
```

Moving to gpa.js we need probably 3 functions and a place to store our list of grades:


          let grades = [];

          function setGrades() { 
            // get grades from the input box and split them into an array
          }

          function lookupGrade(grade) {
            // converts the letter grade to it's GPA point value and returns it
          }

          export default function calculateGpa() {
            // grabs a list of grades from the input, converts them all to gpa points, and calculates the GPA from that. Should return the GPA
          }

Notice that only the calculateGpa function is exported. That will be the only thing we need to expose for this to be used. Everything else is only used inside the module and so we want it to be private. Since there is only one thing we are exporting it is also using a default export.
We can import in our gpa function to main3.js with the following:
```
import  calculateGpa  from "./gpa.js";
```
See if you can complete the module. (continue into next week) Earlier this week we saw examples that should help with the lookupGrade and calculateGpa functions.
Finally we need to connect all the dots. We need to attach a listener to the button, when it is clicked it should calculate the gpa, and then display the result in the #output element. Give it a try to code this with your teams. When you are done you can look below:
Finished Main3.js
```
import { setListener, setHtml } from "./ui.js";
import calculateGpa from "./gpa.js";

function submit() {
  const gpa = calculateGpa();
  setHtml("#output", gpa);
}

setListener("#submitButton", "click", submit);
                        
```
You may have noticed the alertMessage function we placed in the ui.js module. It will place a colored box at the top of the screen for a few seconds then it will disappear. How would you use that in this application to make the GPA show in the alert? Try it...
Here is a link to the completed exercise