How to edit the JSON file - osulp/dcwizard GitHub Wiki

Writing JSON File Guide for DC Wizard

By Sam Young

Disclaimer: This is a rough draft and still will have a lot of changes added on as the application is being completed. Please don’t hesitate to e-mail me at [email protected] or message me on Slack if there is any questions.

Table of Contents:

  • 1 - Title Page
  • 2 - Table of Contents
  • 3 - Why use JSON?
  • 4~5 - Title Type
  • 6~8 - Question Type
  • 9 - Finished Type
  • 10~11 - How to Write More Questions

Why use JSON?:

Features of JSON: JSON provides an easy way to store text based information like the questions and store them all in one file. High-leveled Language and requires little to no coding knowledge to write one. Able to separate certain value types. Can be used with any text editor.

Cons of JSON: Messy formatting at times Some variables need to be explained.

In this JSON file I currently have 3 types of “formatted data types”, Title type, Question type, and Finished Type. In the following pages, I will be separating these in to these three sections and talking about how to write/edit them.

*NOTE: Most data types will have this variable called "comment", this shouldn’t be considered a variable type and isn’t used for the application. This is purely to document usage within the JSON file. You will not and usually should not have to touch this variable type.

JSON has some special syntax to note: Everything is formatted in the way shown as - "Key": Value The Key is the variable name that will be used to refer to the Value next to the key. For example, "questionid":"/Q1_2" calling questionid in the javascript code will return /Q1_2.

These Keys should always be contained within quotation marks. You are allowed to put any type of characters in these Keys.

The values in our case can either be a string contained in a “” or a number value (1, 2, 3, 4, etc.)

Important Key variables will be denoted by two “!!” since it has changed since the google spreadsheet was created.

Also, it’s important to note that in JSON file, you don’t include a comma for the last Key variable in a data set. For example "optionlink":["/Q1_1", "/Q2_1", "/Q3_1 ], you don’t include a comma after /Q3_1 because that is the last option.

Title type:

The title Type is currently formatted like this:

Description: You should only be editing this data type and not be making any more new ones because there is only one title type throughout the whole application. This one is relatively simple compared to the Question Type.

*"comment": Refer to Note Above about what this is for. "Questionid": For this type, don’t touch this variable. "Option": This variable is where you put your question names, currently as stated by Clara, there will only be 3 question types right now ( "Me With Others", "Others With Me", "Me With Me"). If there happened to be more questions later on, one would need to add a comma after (Me with Me) and the title name. "optionlink": This variable is used to set the first question link. For example, once the user clicks the button with “Me With Others” then it will go to question /Q1_1. Make sure the question name and the questionlink is in the same corresponding order. Note: The way it is set up Me With Others has Q1… as the start, Others with me has Q2..., and Me with Me has Q3… this is used to discern between each question. "Questionorigin": Leave this empty and as is because it is only included to not break the application.

Question type:

The Question Type is currently formatted like this:

Description: This data type is what will hold your questions, where it will lead to, and where it originated from. I will be listing out what each lines means and why you need it. Every Question type will always have the same Key variables. You shouldn’t be adding any more Key types.

• ("questionid":"/Q1_2") - This is the "questionid" key which takes a value of a question number. When writing this make sure you include the “/” before every “Q…”. This is so the pathname can be read from the URL.

• ("question":"Does the data have a license?") - This is the "question" key which holds the question being asked. This holds the actual question and what needs to be asked for the application. This should be put with the corresponding question.

• ("explanation":"If a license has been applied to a copyrighted work …") - This is the "explanation" key which holds the explanation of the question. This just explains what the question means. This should be put in the same corresponding questionid.

• !!( "numoptions":2) - This is the "numoptions" key which holds the number of answer options there will be. This is IMPORTANT to have because the app keeps track of how many options there are using this number. For example, in this case the "numoptions" value is 2 because there are two options total (a yes and a no) to answer this question.

• ("explanationresources":"Creative commons licenses: https://creativecommons.org/licenses/") - This is the "explanationresources" key which holds the resource from where the explanation is from or whatever link holds more information about the question. Make sure this is with the correct corresponding questionid.

• !!( "questionorigin":["/", "/Q1_1"]) - This is the "questionorigin" key which holds all of the questions past answers to get to the current question. This is another IMPORTANT one. The values are held in what is called an array denoted by the []. The values inside the array are the past questionids.

For example for questionid of “/Q1_2”, its past questions are “/” which is home and “/Q1_1”. When putting these in the array make sure the most earliest past question is on the left side and the most recent is on the right side in that order. This means “/” should always be the first on the left and the question just prior, “/Q1_1” in this case would be last on the right.

• !!("optionid1":{ "option":"Yes", "nextsteptype":1, "nextstepcontent":"/Q1_2_1" })

  • This one is very important since it holds a lot of steps. I will be separating each one into bullet points. For this one, this is "optionid1" key holds all the data for the first option choice. This means that if there is another option we will call it "optionid2", and if there is another then "optionid3" and so forth. The values each optionids hold are "option", "nextsteptype", and "nextstepcontent. These values will be the same with every optionid1, 2, 3, etc. It holds these values by encapsulating them in a {} as shown above.

◦  ("option":"Yes") - This Key variable "option" that holds the option name of the optionid. In this case the option would be “Yes” since it is a yes or no question. ◦ ("nextsteptype":1) - This Key variable "nextsteptype" that holds the next step type of the question. If the value is a 1 that means the next step is another question, if the value is a 0 then the next step is a finished question. (Currently in the Javascript code this doesn’t do anything but it is good to keep to keep track of what type of question it will be). ◦ ("nextstepcontent":"/Q1_2_1") - This Key variable "nextstepcontent" that holds the next step of the question. That means the value will be the direct next step if you click this option. For example, in this case if you click “yes” from “/Q1_2”, it will lead to “/Q1_2_1”. This is very important the slash is included so it will lead the user to the correct next step in the URL.

Finished type:

The Finished Type is currently formatted like this:

Description: This data type is for the last step of a question path. This one is relatively simple compared to the question types because it only holds 3 Key variables (4 if you count the comment).

• !!("questionid":"/Q1_2_1_yes_done") - This is the "questionid" key which takes a value of a question number. This is slightly different than the normal questionid. When writing for a finished make sure you include the last option chosen to get to the finished step (yes in this case) then underscore and then lastly a “done” in all lowercase. Just like this "/Q1_2_1_yes_done". This is because this is how the javascript file reads that it is at a finished step.

• !!( "questionorigin":["/", "/Q1_1", "/Q1_2", "/Q1_2_1"]) - This is exactly the same as in the Question Type. This is the "questionorigin" key which holds all of the questions past answers to get to the current question. This is another IMPORTANT one. The values are held in what is called an array denoted by the []. The values inside the array are the past questionids.

• ("finished":"Excellent! Hopefully you now know exactly what you can and cannot do with the dataset.") - This is the "finished" key which holds the final message the user needs to read for the data set.

• Note: We may be adding more variables to this for the user log.

How to Write More Questions:

Currently, for Q1 (correlates and holds questions for all of “Me with others Data” all of the questions are finished and all the routing is done through those JSON file as an example. When writing the JSON file, please refer to those to get an idea of how steps works. The order of where you put each grouping (grouping denoted by {} and a comma ,) don’t matter as long as you have the correct next step written in the current question.

I have started Q2 for the JSON file. This Q2 should hold all of “Others with Me Data” questions. This is what it is as shown below. ______________________________________________________________________________ { "questionid":"/Q2_1", "question":"Testing for others with me", "explanation":"Test Description", "explanationresources": "", "numoptions":2, "questionorigin":[ "/" ], "optionid1":{ "option":"Yes", "nextsteptype":1, "nextstepcontent":"emptypageyes", "clearsteps":[

     ]
  },
  "optionid2":{
     "option":"No",
     "nextsteptype":1,
     "nextstepcontent":"emptypageno",
     "clearsteps":[

     ]
  }

When creating Q2, you should only be making Question Types and Finished Types. For the code above there are only a couple things you need to change.

"question" "explanationresources" "explanation" "nextstepcontent"

“Question”, “explanationresources”, and “explanation” need to be changed to what they are supposed to hold for that questionid at /Q2_1.

For the nextstepcontent of each option, change those to which question it’s supposed to lead to next. Usually if its optionid1, the question will go to /Q2_1_1. If it’s optionid2, the question will go to /Q2_1_2. If there’s more it will be Q2_1_n, with n being the id number it is on.

Then, create another Question type by follow the path you made using the nextstepcontent as the questionid for the new Question type. For example in the case above, we would have to make two new question types with the questionid /Q2_1_1 and /Q2_1_2 and so forth.