Forking instructions - nfischer/framily-tree GitHub Wiki

Fixing a bug?

Just fork this like any other git project. Pull requests are welcome!

Want a similar family tree for your fraternity?

At the time of writing, you should do the following:

Google Spreadsheet

You'll first have to set up the Google Spreadsheet. To do this, you should go to my google spreadsheet. Make sure you're signed in to a Google account, and click "File > Make a copy." You can delete the data rows if you want a different data set, but make sure to keep the header row the same.

In your new copy, click "File > Publish to the web." This is necessary so that the Google Spreadsheets npm package can download the data as JSON.

Keep this browser tab open; you'll need the spreadsheet ID later.

GitHub repository

Go to https://github.com/nfischer/framily-tree and click the "Fork" button. Your new fork can be either public or private.

Clone the repository to your local machine (remember to change the URL to use your username):

$ git clone https://github.com/[YourUsernameGoesHere]/framily-tree.git
$ cd framily-tree/

Edit the README.md. Go to the bottom of the page and search for "Forking instructions" to change the URLs to match your project.

Next, edit the file scripts/getData.js and change SPREADSHEET_ID to be whatever your spreadsheet ID is on your forked Google Spreadsheet (it's the part of the URL between spreadsheets/d/ and /edit#gid=0).

Get a Google API key (free)

This project has an automated script which you can use to sync the data from the Google spreadsheet to the JSON data in this project. This automated script requires a Google API key which you can get for free.

You can create an API key here: https://console.developers.google.com/apis/credentials. Give it a descriptive name (ex. "family tree spreadsheet") and make sure it has access to the Google Sheets API. Copy the API key—it looks like a string of 39 numbers, letters, and hyphens ('-')—and go back to your cloned GitHub project. Create a file named local-api-key.txt in the cloned project on your computer. Edit the file and paste in the API key you copied in the previous step.

Do not git commit this file. The local-api-key.txt file should only exist on your computer (do not push this file to GitHub). The file should automatically be ignored due to a rule in the .gitignore file.

Adding your data

Add in whatever data you like in your new spreadsheet. You can append to the data I have, modify it, or write in completely new data (but it must follow the same schema, so don't change the header row). Once you've done that, go to your terminal and run:

$ npm install
$ npm run getData
$ git diff # see what has changed

You should see that relations.js has now changed. This means you've downloaded the new data. Run npm start and see it live in the network graph (family tree).

Publishing to your own fork

Once you're satisfied with the changes, commit the changes (git commit -am "Update data"), push the changes (git push origin master), and deploy them to GitHub Pages (npm run deploy). After a minute or two, you should be able to view them at https://[YourUsernameGoesHere].github.io/framily-tree.

Automating data updates directly from the spreadsheet

On the original spreadsheet, if you did choose to clone it, in the Apps Scripts comes with it a script that provides a menu of options that lets you directly update the repository from the spreadsheet. This actually calls the GitHub API from the sheet to trigger a workflow in the repository that pulls the data from the spreadsheet and merges them to the appropriate branches, effectively updating the site within seconds.

This is optional, but to get this functioning, there's a couple tokens and secret variables you have to setup:

GitHub Token

Go to your Account Icon in the top right of GitHub → Settings → Developer Settings (at the bottom of the toolbar on the left) → Personal access tokens → Fine-grained tokens

  • Click “Generate new token” in the top right
  • Name the token whatever you want and add a description if you want
  • Set the Expiration to No expiration
  • Set Repository access to Only select repositories and select the framily-tree
  • Under “Add Permissions”, add read + write permissions for Actions, Contents, and Pull Requests

Secret Variables on your Forked Repository

Go to the forked repository → Settings → Secrets and variables (left sidebar) → Actions

Add the following two repository secrets which our workflow will reference

  • SPREADSHEET_API_KEY: Your Google API Key (to access the spreadsheet)
    • If you don’t have one setup (you probably already do) go to https://console.cloud.google.com/apis/credentials
    • Select “Create credentials” up top and make a new API Key with no settings changed
    • Under “Enabled APIs & Services” on the left sidebar enable the Google Sheets API
  • TRIGGER_SECRET: The word that you set in your Google Apps Scripts Property that it will crosscheck to run the GitHub Action. Make it any word and be sure to set it to the same word in your Google Apps Script in the next section

Google Apps Script Properties

On your spreadsheet in the top menu toolbar go to Extensions --> App Scripts → Project Settings (Gear Icon in Left Sidebar) --> Scroll to the bottom of the page with Script Properties Several “Script Properties” (Secret Variables basically) have to be defined for the script. Set it to the appropriate values else the script will fail.

  • ACTION_NAME: update_data
  • GITHUB_OWNER: Set this to your GitHub username
  • GITHUB_REPO: framily-tree (unless you named your fork something different)
  • GITHUB_TOKEN: Your fine-grained access token associated with the repository that we setup earlier
  • TRIGGER_SECRET: Whatever word you want the GitHub Action to check before proceeding, just make sure it is the same as whatever you setup in the Secret Variables on the repository (think of this as a canary just in case someone tries to call the workflow from outside our script)

Further reading