DPS909 & OSD600 Fall 2019 - Lab 2
Contents
- 1 Programming with git and GitHub
- 1.1 Due Date
- 1.2 Introduction
- 1.3 Walkthrough
- 1.3.1 Step 1: Create a new GitHub Repo
- 1.3.2 Step 2: Clone your GitHub Repo on your Local Machine
- 1.3.3 Step 3: Write some Code in your Local Repo
- 1.3.4 Step 4: Mirror your work on GitHub
- 1.3.5 Step 5: Adding Features
- 1.3.6 Step 6: Push and Setup Gh-Pages Hosting
- 1.3.7 Step 7: Add Something Cool
- 1.3.8 Step 8: Blog about Your App
- 1.4 Submission
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.
NOTE: You are free to collaborate with others in the class, share ideas, code, and help one another debug. However, every student must follow the steps to completion so as to create the necessary work products.
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
- Create a new GitHub repo (instructions here):
- Name it something like my-note, micro-note, whiteboard or something else that makes sense to you
- Add a Description, for example: "A web based note taking app".
- Set your repo to be Public
- Initialize it with a README.md and License. For your License, choose BSD 2-Clause "Simplified License" (see BSD 2-Clause).
- 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
- 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:
- Change the default editor Git uses from Vim to your preferred editor (e.g., Visual Studio Code)
- Make sure you use Git from the command line and also from 3rd-party software when adjusting your PATH.
- 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.
- You now need to copy your repo onto your local computer. To do this, use the
git clonecommand. Theclonecommand 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, usegit clone https://github.com/username/repo-name.gitto clone it locally on your computer. - You should now have a new directory with the same name as your GitHub repo. Type
cd repo-nameand 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
- 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.
- In your index.html file, create a basic HTML5 document.
- Try opening your index.html page in a browser, and make sure it works as you expect.
- Once you're convinced that everything's working, commit your work to git. To do so, use the following commands:
-
git add index.html -
git commit -m "Adding a basic web page"
-
Step 4: Mirror your work on GitHub
- 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.
- 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. - 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
- 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.
- Add a
scripttag to the bottom of your HTMLbodythat uses the following src: https://unpkg.com/filer/dist/filer.min.js:<script src="https://unpkg.com/filer/dist/filer.min.js"></script>
- Below this, add a second
scriptthat initializes a filesystem:<script>const fs = new Filer.FileSystem(); ...
- The
fsinstance can be used to call any of the filesystem operations like readFile() or writeFile(). - Write some code to accomplish the following set of steps:
- 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., iferris non-null), use a default string like "Welcome to my notepad!". If the file does exist (i.e.datais non-null), use that for your string instead. - 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):<div id="note" contenteditable></div>
- 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. NOTE: recall that you can use
document.querySelector('#note').innerHTMLto get/set the contents of the div. - When the user refreshes the page, or loads it after closing it, the contents of the /note file should reappear.
- When the page's DOM is finished loading (use the DOMContentLoaded event), try to
Step 6: Push and Setup Gh-Pages Hosting
- Once you have the basics working from Step 5, use
git add,git commit, andgit pushas discussed above to sync your GitHub repo with your local machine. - 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:
- Click Settings in your GitHub repo's main page header
- Under the GitHub Pages > Source dropdown, choose the master branch option.
- Click Save
- 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
- Make the UI responsive, so it works well on mobile, tablets, or desktop.
- 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 (i.e., "Saving..." vs. "All changes 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.
- Add a word count feature. There are lots of existing JavaScript text analysis libraries you could use, or write your own.
- Instead of a plain DIV using contenteditable, switch to a rich text editor control using an open source component like Trix or Quill (there are dozens if you do some research).
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.
