-
Notifications
You must be signed in to change notification settings - Fork 481
[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.
- Foorm Editor: Editing interface located here.
- Form/Survey Author: The person writing the form/survey configuration.
- SurveyJS: Survey configuration system used to build Foorm.
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.
-
Questions need a
nameand atitle.nameis the key we will use throughout survey processing, and should be all lowercase with underscores to separate words (ex.sample_question_name).titleis what the user will see. -
Answers need a
valueand atext. For multiple choice questions (checkbox, radiogroup, matrix), give choices both avalueandtext.valueis the key (similar tonamefor a question), andtextis 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 asvalue|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 itemcheckbox--this will addotherat 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 ofother; this will confuse surveyjs. -
Headings. If you want a heading in the middle of the page or a block of text, use the
htmlquestion 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 (
valuefor a multiple choice question,namefor the question title) whatever makes the most sense, as long as it is lower-case with underscores. There are a few pd-specific 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 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.
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 (ideally 1 month). Check in with engineering once you are happy with your form configuration so they can connect the backend with your form.