DPS909 & OSD600 Fall 2019 - Lab 2

Programming with git and GitHub

Due Date

Friday Sept 13 before midnight.

Introduction

This lab will get you started using git, GitHub, and also introduce you to an open source project called Filer, which we'll be working with in Release 0.1.

Our goal is to create a single-page, serverless web app for note taking, and host it on GitHub.

Walkthrough

The following steps will help you get things setup and working. If you need help with any of these, make sure you ask. If there are things you want to know more about, do some research and follow the links provided.

Step 1: Create a new GitHub Repo

1. Create a new GitHub repo (instructions here). Name it something like my-note, micro-note, whiteboard or something else that makes sense to you, and add a Description: "A web based note app". Set your repo to be Public, and initialize it with a README.md and License. For your License, choose BSD 2-Clause "Simplified License" (see BSD 2-Clause).
2. Your new repo will have a URL that combines your GitHub username and chosen repo name: https://github.com/username/repo-name. Understanding this URL scheme is important when you're trying to make sense of which version of a repo (i.e., which fork) you're reading.

Step 2: Clone your GitHub Repo on your Local Machine

1. Install git if you don't already have it on your computer. You can download it here. NOTE: if you're on Windows, I suggest that you override the following settings while running the installer:
   1. Change the default editor Git uses from Vim to your preferred editor (e.g., Visual Studio Code)
   2. Make sure you use Git from the command line and also from 3rd-party software when adjusting your PATH.
   3. When configuring line ending conversions, choose Checkout as-is, commit as-is. This will make sure that Unix style line endings don't get converted to Windows line endings, and vice-versa.
2. You now need to copy your repo onto your local computer. To do this, use the git clone command. The clone command requires a git URL to a repo. NOTE: this is NOT the same thing as your GitHub URL for your repo; a git URL ends in .git. You can follow these instructions to find your repo's git URL. When you have it, use git clone https://github.com/username/repo-name.git to clone it locally on your computer.
3. You should now have a new directory with the same name as your GitHub repo. Type cd repo-name and look at the files. There should be LICENSE and README.md files. Open them in your code editor, and compare them to what you see on GitHub.

Step 3: Write some Code in your Local Repo

1. Create a new file named index.html inside your local repo's directory. You can use any code editor you like--I'd suggest using Visual Studio Code.
2. In your index.html Create a basic HTML5 document.
3. Try opening your index.html page in a browser, and make sure it works as you expect.
4. Once you're convinced that everything's working, commit your work to git. To do so, use the following commands:
   1. git add index.html
   2. git commit -m "Adding a basic web page"

Step 4: Mirror your work on GitHub

1. Our code is committed (i.e., saved) in our local git repo, but at some point we should also push the commit(s) to our GitHub repo too. Each repo is a copy (i.e., clone) of the other, but they don't stay in sync automatically. We have to tell them when and what we want to sync by using git's push and pull commands.
2. Use the following command to push your recent change (i.e., commit) to GitHub: git push origin master. Here we tell git to push commit(s) to the origin repo (i.e., the one from which we cloned originally), and to use the master branch. We'll discuss branches more in coming weeks. For now, it's enough to know that master is the default branch of development.
3. Any time you want to sync what's on your local computer with GitHub, you can follow these steps to push any missing commits.

Step 5: Adding Features

1. Our note taking web app needs a way to save and load our work. To prepare you for your 0.1 Release, we'll use the FilerJS Browser Filesystem library.
2. Add a script tag to the bottom of your HTML body that uses the following src: https://unpkg.com/filer/dist/filer.min.js
3. Below this, add a second script that initializes a filesystem: const fs = new Filer.FileSystem();
4. The fs instance can be used to call any of the filesystem operations like readFile() or writeFile().
5. Write some code to accomplish the following set of steps:
   1. When the page's DOM is finished loading (use the DOMContentLoaded event), try to fs.readFile('/note', 'utf8', function(err, data) {...}). If there is an error (i.e., if err is non-null), use a default string like "Welcome to my notepad!". If the file does exist (i.e. data is non-null), use that for your string instead.
   2. Use the string from the previous step to display in a <div> that you add to the page. You can give it an id="notepad". Also make this <div> editable using the contenteditable attribute (i.e., the user should be able to edit the text in the page).
   3. Use a setInterval() call to register an interval callback that saves whatever is in the notepad div every 2-5 seconds (try different amounts of time to see what works best) to the /note file.
   4. When the user refreshes the page, or loads it after closing it, the contents of the /note file should reappear.

Step 6: Push and Setup Gh-Pages Hosting

1. Once you have the basics working from Step 5, use git add, git commit, and git push as discussed above to sync your GitHub repo with your local machine.
2. Next, we'll enable Gh-Pages for our master branch. This will tell GitHub to create a web server to host our content. Follow these steps:
   1. Click Settings in your GitHub repo's main page header
   2. Under the GitHub Pages > Source dropdown, choose the master branch option.
   3. Click Save
3. Your site will get built and hosted at https://username.github.io/repo-name. Every time you push new code to your master branch, these changes will get rebuilt and hosted again. NOTE: it may take some time between when you push, and when it shows up on github.io.

Step 7: Add Something Cool

For the final step, add something unique, interesting, fun, cool, etc. your app. Here are some ideas, but you are free to do anything you'd like:

• Update the "save" logic so it uses keyboard shortcuts. You could use a library like Hotkeys.js. If you use this library, make sure you see the note about enabling it for contenteditable.
• Add some UI, maybe a toolbar with a Save button.
• Change the fonts using something like Google Fonts
• Use a CSS library to make the UI look like it's using being done with hand-drawn, paper sketch styles (e.g., PaperCSS)
• Use a background image instead of a pure white document
• Add some kind of Google Docs style indicator to tell the user when their changes are saved
• Make it possible to support multiple pages/files. For example, if the user loads index.html?p=note you load the /note file, but index.html?p=opensource would cause the app to use the /opensource file instead.
• Add the ability to download and save your notepad. You can use a library like FileSaver.js.

Step 8: Blog about Your App

Write a blog post about your app. Include links to the code on GitHub, as well as the live version on github.io. Explain how it works, and which extra feature(s) you added. Also discuss any new technical things you learned along the way.

Submission

Complete the steps above and then add your information to the table below.

Name	GitHub Repo (URL)	GitHub Pages (URL)	Blog Post (URL)
Example Name	https://github.com/example/notepad-app	https://example.github.io/notepad-app	https://examplestudent.wordpress.com/2019/09/05/introducing-notepad/