[Levelbuilder] The Foorm Editor
‘Foorm’ is our in-house survey (or form) system. The second ‘o’ in Foorm is not a typo; it is there to distinguish from all the other forms we use. It is currently used for professional development workshop surveys, facilitator surveys, and occasional one-off surveys on our site. In its most basic form it is a standardized way of defining surveys and getting survey results.
Terminology
- Foorm Editor: Editing interface located here
- Form/Survey Author: The person writing the form/survey configuration
- SurveyJS: Survey configuration system we built Foorm on top of
- Simple Survey - a one off survey being created to gather information once. A great use case here - a survey collecting addresses to mail PD materials that we want linked to a user account. Also allows survey author to specify if a user can only fill out the form once.
If you are writing a new survey, the best way to get started is to use the SurveyJS creator. The creator has a drag-and-drop interface for adding new survey questions and will generate the configuration for you automatically.
Survey Creation Guidelines
- Questions need a ‘name’ and a ‘title’. The name is the key we will use throughout survey processing, and should be all lowercase with underscores to separate words (ex. ‘sample_question_name’). The title is what the user will see.
- Answers need a ‘value’ and a ‘text’. For multiple choice questions (checkbox, radiogroup, matrix), give choices both a ‘value’ and ‘text’. The value is the key (like the name for the question), and the text is what the user sees. You can use the “Fast Entry” option on the surveyjs creator to make adding both easier--you write the options there as ‘value|text’. See this section at the bottom for how to set up answers for a matrix question in the "Fast Entry" option.
Adding an “Other” answer. If you want an ‘other’ option that allows the user to fill in text, use the “Has other item” checkbox--this will add ‘other’ at the end of the list of options. If you want an ‘other’ option that does not fill in text, do not give it the value of ‘other’; this will confuse surveyjs.
Headings. If you want a heading in the middle of the page or a block of text, use the ‘html’ question type. We generally use <h2> for headings mid-page. Here is some helpful HTML if you want to add a scale describing a set of matrix questions.
Variables. If you want a variable to be filled in later (ex. the name of a course), surround the variable name with {}. See Variables for more details. For most questions you can make the key (‘value’ for a multiple choice question, ‘name’ for the question title) whatever makes the most sense, keeping it lower-case with underscores for consistency. There are a few exceptions to this, see Rollup Questions.
Once you have the questions you want, go over to the “JSON Editor” tab in the SurveyCreator. Copy the json and go to the Foorm Editor to get a preview of what it will look like on our site!
The Foorm Editor is located here. You need an account on levelbuilder with levelbuilder permissions. Talk to an engineer if you don’t have an account set up yet.
On opening the editor, either click “Load Form” and select a form, or “New Form” if creating a new form. You will then see a json editor and preview panel. Any changes you make to the json will be visible in the preview within a second. If you don’t want to see changes as you write, you can turn off the live preview with the toggle at the top of the page.
If you want to test variables in your form, you can use the predefined set of variables in the editor on the “Variables” tab next to the editor. These variables are available for our professional development surveys. If you need a new variable for a PD survey and/or are writing a form for a different use case, talk to an Engineer.
As you write your form, you can click the “Validate” button at the top of the page to see if you would get any validation errors on saving the form.
Foorm allows you to use variables in your survey. In a workshop context, we make available certain information about the workshop available in predefined variables (eg, course).
With simple surveys, you can specify any variable name you'd like, and then specify the value for that variable when you make the simple survey available to the public.
Finally, there's the case of using responses to previous questions in the survey to gate showing other questions, etc., which also uses a similar syntax.
When in doubt about adding or updating variables, reach out to an engineer
If you have a json parse error, the preview will turn off and you will see error messages next to your json. Sometimes the errors can be a little confusing. It is helpful to know the basics of JSON to fix these. For example, if you have a list of items, it will be surrounded by ‘[‘ and ‘]’. If you are missing the starting ‘[‘, the error message will show up on the closing ’]’ and say it expected a different symbol.
Most validation errors are around missing name/value for a question. The error will be specific about the question/choice with an issue.
If you aren’t using the advanced feature of [library questions](insert link here), you won’t see this message. If you have a library error, the preview will disappear and the message will be something such as “There is an error in the use of at least one library question. The error is: cannot find library item with library name surveys/pd/workshop_element, version: 0 and question name survey_preamble_header_and_text.”. This means the library question referenced in the form cannot be found--usually this is due to a typo in the reference.
Forms have a concept of published and draft. A published form is ready for use in production or is already in use. A draft is still in progress and not ready for use in production. This is currently a convention and is not enforced on our backend, but is helpful for marking survey status. When editing a published form, take care to only make safe edits. If you need to make an unsafe edit to a published form, consider versioning instead. Safe Edits to Published Forms The reason to be careful when editing a published form is any old survey responses will now be referenced against the configuration you have made edits to.
If you are sure the published form has not been used yet, you can make any changes you want.
You can always fix a typo or grammar issue in a published form, as long as it doesn’t change the meaning of the question. It is generally ok to add a question or add an option to a question, as long as you are aware that old form responses will never choose that option or answer that question.
There are some cases when you must version to make a change to a published form. Some known situations are:
- If you want to remove a question or choice, you need to version, as old responses will look invalid after the question/choice is removed.
- If you want to change the meaning of a question you will also need to version.
- There are some common use cases where what Survey.JS gives us does not play well with our CSV export. For instance, Matrix questions are automatically labeled ‘Row 1,2,3, etc’ - we need more descriptive and unique names. If these need to be changed, we need to version.
Updates from Survey.js to our system
Matrix questions on Survey.js automatically give Matrix rows the name “‘Row 1,2,3, etc’”. We need to update those names on Levelbuilder to be unique and readable. Ctl F for Row and rename those
There are 3 matrix questions that we show as “rollups” on the workshop dashboard. These are the only questions that have prescribed keys, so that we can combine questions across multiple surveys. We only combine questions for the same course (ex. CS Fundamentals). These questions only show up on post-surveys. The easiest way to ensure the questions match is to copy them over from an existing survey for the course you are adding a survey for, then make any required changes. The three questions to look for are (samples from the csd/csp summer workshop post-survey):
Overall_Success
Teacher_Engagement
Facilitator_Effectiveness
- Note: this is a per-facilitator question, see Per-Facilitator Questions for more details.
Many of our surveys ask the same set of questions for each facilitator of the workshop. We implement these sorts of questions as a panel in SurveyJS. This panel is very similar across workshops/surveys, so the easiest way to set it up is to find an existing survey having a question element with the type ‘paneldynamic’ named ‘facilitators’ and copy it over, then make any changes required. If you use the ‘facilitators’ name for your panel you will get the following variables:
- panel.facilitator_name
- panel.facilitator_position
Where each iteration of the panel will contain a single facilitator’s name and the index of that facilitator (ex. {Alice, 1}, {Bob, 2}).
Our current system lets you write and save forms into our database. If you need a new form added to our site, reach out to engineering on #foorm as soon as you are aware. You will need to know: what the form will be used for, when it needs to be on the site, any variable requirements (it’s ok if you don’t know specifics here but a general idea is good), and how you want to get the response data. Note that engineering may not be able to immediately add the survey to the site, so give plenty of notice. For a simple survey - expect a few days lead time. For surveys that need results embedded on our site (post workshop surveys) we will need a month's lead time. Check in with engineering once you are happy with your form configuration so they can connect the backend with your form.
JSON stands for “Javascript Object Notation”. It is a way to structure data--in our case, the configuration of a form. The JSON structure surrounds objects with curly braces: {}, and consists of key/value pairs, where the values can be JSON as well. Here’s a simple survey configuration:
{
"title": "A Sample Form",
"pages": [
{
"name": "page1",
"elements": [
{
"type": "checkbox",
"name": "question_1",
"title": "The First Question",
"choices": [
{
"value": "option_1",
"text": "First Option"
},
{
"value": "option_2",
"text": "Second Option"
},
{
"value": "option_3",
"text": "Third Option"
}
]
}
],
"title": "Page 1",
"description": "The first page"
}
]
}The curly braces surround the entire object. The “title” key is a property for the entire form, so it is inside the first set of curly braces. The value for “pages” is a list (indicated by [ ] at the start and end) of pages, which are themselves objects. Each key/value pair in a list or object is separated by a ‘,’. Useful survey snippets Here are a few snippets that may be useful to copy and paste when creating or converting a survey. Set up values 1-7 on for a matrix question 1|1 2|2 3|3 4|4 5|5 6|6 7|7 Add a header describing a matrix question
If you want to have a header for a matrix question that looks like the following:
Copy/paste the HTML below into a HTML element in SurveyJS (with updated text that you want under each set of numbers):
<table style="width: 100%; border: 1px solid black; margin-left: auto; margin-right: auto;" cellpadding="1px"><caption> </caption>
<tbody>
<tr>
<td style="width: 23%; padding-top: 3px; text-align: center; vertical-align: top;"><strong><span style="font-size: 10pt;">1<span style="color: #FFFFFF;">----</span>2</span></strong></td>
<td style="width: 24.7981%; text-align: center; vertical-align: top;"><strong><span style="font-size: 10pt;">3<span style="color: #FFFFFF;">----</span>4<span style="color: #FFFFFF;">----</span>5</span></strong></td>
<td style="width: 20.2019%; text-align: center; vertical-align: top;"><strong><span style="font-size: 10pt;">6<span style="color: #FFFFFF;">----</span>7</span></strong></td>
</tr>
<tr>
<td style="width: 23%; text-align: center; vertical-align: middle;"><span style="font-size: 10pt;"><strong>Not true of me now</strong></span></td>
<td style="width: 24.7981%; text-align: center; vertical-align: middle;"><span style="font-size: 10pt;"><strong>Somewhat true of me now</strong></span></td>
<td style="width: 20.2019%; text-align: center; vertical-align: middle;"><span style="font-size: 10pt;"><strong>Very true of me now</strong></span></td>
</tr>
</tbody>
</table>
###For Advanced Users
Libraries/Library Questions
"Libraries" are collections of questions that can be reused across multiple Forms. Each Library consists of "Library questions", which are individual questions that can be inserted into multiple Forms.
Creating and Editing Libraries/Library Questions
The editing experience for Library Questions is very similar to editing a Form -- you can edit them on levelbuilder. You can:
- edit existing library questions by selecting one from the dropdown,
- create a new library, and
- add new library questions to an existing library.
Once you've loaded a library question, you'll be able to edit it in the same way you would a Form:
The syntax for creating a Library Question is the same as what's required for a valid Form element. It should be able to be substituted directly into a Form (more on how to do that in the next section), and would look something like this:
{ "type": "rating", "name": "feel_prepared", "title": "I feel more prepared to teach {workshop_course} than I did at the beginning of the day.", "rateMax": 7, "minRateDescription": "Strongly Disagree", "maxRateDescription": "Strongly Agree" }
``
Once you've created a Library Question and want to use in a Form, you can reference your Library Question in your Form by doing the following:
- Reference the Library Question it in the "elements" section of the JSON,
- Specify what Library Question you want to be shown by specifying:
- the type (always "library_item"), as well as
- the identifying information for the Library Question ("library_name", "library_version", and "name"). "name" references the library question name you specified when creating it ("feel_prepared" in the example above)
Here's what an example Form that uses a Library Question looks like:
{
"published": true,
"pages": [
{
"name": "preamable_page",
"elements": [
{
"type": "library_item",
"library_name": "surveys/pd/workshop_elements",
"library_version": 0,
"name": "feel_prepared"
}
]
}
]
}"Simple surveys" are a way to easily conduct a survey of your choosing. You can specify the URL suffix where you can direct respondents (eg, studio.code.org/form/your_url_suffix). The process to create and launch a simple survey looks like the following:
- Create a Form on levelbuilder. Instructions for creating a form can be found previously in this document.
- Pick a URL where your survey should appear: log in with an admin account (ie, your Google SSO @code.org account to studio.code.org (production), and visit this page. You can specify the following options:
- Path suffix where survey will appear (required): the base URL for all simple surveys is studio.code.org/form/. You specify what comes after the slash here -- lower case, numbers, and underscores only.
- Form to appear on page (required): select the Form that you'd like to appear on this page (the Form you created in step #1).
- Survey identifier (optional): if you are running the same survey in multiple iterations (eg, annually), you can use this field to tag all submissions for a given iteration (eg, iteration2021). Helpful for analysis primarily.
- Allow multiple submissions by the same user (default false)
- Variables (optional): if your Form uses variables (see this section above on how to use variables), you can specify what the names of those variables are, and what value you'd like to appear in place of those variables in this Simple Survey.
- Check out your new survey. The list of all available simple surveys can be found here -- once you've created your new survey, you can visit the URL you created (or updated, if it was already previously in use) to make sure it looks as you'd expect.