Dynamic Phrase Builder?

[terracoda]

@emily-phet and I have bounced around a few ideas about how to make a simple but effect tool that helps with description design.

Our ideas have ranged from a fully editable A11y-Vew-Type interface to this simple phrase builder that uses the select element to play with phrase parameters.

I'd like to know if this little phrase builder in a very simple form would be something useful to designers and feasible to build in a short amount of time. It doesn't have to be pretty.

I uploaded a sample static HTML file with some potential specs: https://github.com/phetsims/a11y-research/blob/master/tools/phrase-and-parameter-sketcher.html

Here's a snap shot that I made in the W3 School's code builder:

[terracoda]

Tagging @emily-phet , @jessegreenberg, @zepumph, @twant, @Matthew-phet for potential feedback.

[terracoda]

This issue is related to #136

[jessegreenberg]

@terracoda, this looks really cool! Can you comment on what this will provide that is currently not supported by current design tools like spreadsheets and docs? Is it mostly to help identify the parameters of a phrase and then see the sentence in full with params filled in or are there other things too?

https://github.com/phetsims/a11y-research/blob/master/tools/phrase-and-parameter-sketcher.html gave a good sense of what you are looking for, thanks! I think it would take a few hours to make a prototype.

[terracoda]

@jessegreenberg, this doesn't add a huge amount of functionality that a table in a design document would actually achieve. However, it is surely more interactive than a table in a design doc.

I think a tool like this might aid a designer in playing with the phrase and the parameters to carefully refine wording and perhaps splicing before implementation.

I think by being able to play with the phrase more directly might help find edge cases that require special wording or identify annoying splicing errors.

[terracoda]

@jessegreenberg, I have a feeling that it could potentially make the design and development process more efficient be reducing wording/splicing errors, and reducing the number of required updates to tables of examples or walk-throughs.

It could aid the designer in walking through the idea more completely in a direct way.

If the tool could actually export any useful results of the exploration then it could really reduce the need for a designer to document a robust series of examples. This would make documentation of the design more efficient and less verbose.

[terracoda]

It's taken a long time (various reasons) to get to the final phrase and parameters in the provided example.

[terracoda]

Here's the example in HTML preview: https://htmlpreview.github.io/?https://github.com/phetsims/a11y-research/blob/master/tools/phrase-and-parameter-sketcher.html

[zepumph]

Here is a link that you can use to look at the first prototype:

https://htmlpreview.github.io/?https://github.com/phetsims/a11y-research/blob/master/js/phrase-builder/phrase-builder.html

Basic instructions:

1. Add your sentence into the first text area, with {{templateVars}} annotated with the double curly braces around the sides. You can only use letters inside the braces, no spaces.
2. Once complete with the sentence, you can add the options for each var in the text areas below, each option gets its own line, and if you want an option that is blank, you can just include a blank line. Click the button for each templated var to add the options to the output sentence.
3. The output sentence should have the updated options in the select box.
4. You can edit the sentence all you want, but note that if you change a variable name, or remove it (even to copy paste it somewhere else), you will lose the options that were associated with that templated var.

Let me know what you think!

[zepumph]

Also assigning @emily-phet if she wants to comment.

[terracoda]

There are some bugs, but looks promising. I added a {{templateVars}} after the original set and I got some weird repetition and no new select box maker-thingy.

[terracoda]

@zepumph, I'll have to do some more investigation, but I won't have time today, I don't think.

[jessegreenberg]

Really cool @zepumph, I like it a lot. Nice work!

[zepumph]

Sorry if I wasn't clear, it is designed so that each is named differently, like "templateVar1" etc.

[terracoda]

each is named differently, like "templateVar1"

I was wondering about that. I hadn't yet tried it, but will ;-)

[zepumph]

This is becoming a priority again, as much as it is helpful to designers. I think we will work on it more this corner.

Here is a wishlist for me after looking at it again for only a few minutes:

• local storage saving so that refresh doesn't make us lose work
• "save/load" feature so that you can download work, and then load it again, or perhaps send that to someone else to load
• Instructions on top
• It would be nice if you didn't need to manually "add" options, what if each dynamic element adder could be a bit more graceful, and automatically populate the select boxes with the best available info.

[terracoda]

Other things to keep in mind:

• keep the text on the add buttons as short as possible, e.g. [[Add fruits]].
• The instructional part of the button label text could be put in single general location.
• Perhaps the flow could be improved with input or edit buttons?
• I agree, some option for saving the results is essential.

[zepumph]

I got through everything in the above bullets. @terracoda let me know how this looks. I made it so that much more is just done automatically. Please review.

[emily-phet]

@zepumph - where can I find the latest?

[zepumph]

http://htmlpreview.github.io/?https://github.com/phetsims/a11y-research/blob/master/js/phrase-builder/phrase-builder.html

Does this work? Right on we don't have a better way to host it, but I will work on that.

[zepumph]

Also note I just tried opening on a mobile device and it didn't look right. We may need a few changes to be more universal.

[terracoda]

That link no longer looks like what you shared with me last on Slack. The link loads this:

But I expected something like this:

[zepumph]

Me neither! I just made it so that we are hosting that page through github. Please review with this link:

https://phetsims.github.io/a11y-research/js/phrase-builder/

[terracoda]

This is looking awesome @zepumph.

It could be possible to have the same list of parameters show up more than once per sentence. Is it possible to do a sentence like this?

• I like to eat, eat, eat, apples and {{otherFruit}} and {{otherFruit}}.

Or is it better to do this:

• I like to eat, eat, eat, apples and {{otherFruit}} and {{otherFruit01}}.

The reason I was thinking about this was because of phrases in BASE like:

• {{Yellow balloon}} has {{many more}} {{positive}} charges than {{negative}} charges.
• {{Sweater}} has {{many more}} {{negative}} charges than {{positive}} charges.

[terracoda]

@zepumph, could you replace the instructional content with a list, so the initial text reads like step-by-step instructions:

Dynamic Phrase Manipulator This phrase creator supports rapid prototyping and verification of dynamic phrases used in dynamic descriptions and responses.

To create a phrase with dynamic parts:

1. Type in a description phrase in the text area input.
2. For the dynamic parts of the phrase, create uniquely named variables surrounded by curly braces, e.g. "{{templateVariable}}".
3. A new text area input is created for each one of these curly-braced variables. In the newly created inputs for each variable, enter the options on a new line.

The output phrase will contain a select box for each variable populated with the entered options.

Refreshing the page will automatically load the most recently auto-saved phrases.

Input raw phrase with uniquely named variables within curly braces, {{exampleVariable}}:

...the rest looks good...

[zepumph]

Because of work done in https://github.com/phetsims/a11y-research/issues/161, I wanted to make sure this component still ran, so I wrote a bit of a build step for it. Please review and test by loading https://phetsims.github.io/a11y-research/js/phrase-builder/build/, which should be the exact same as the above, (before I broke it with the other issue's work).

[terracoda]

@zepumph, I tested a bit, and there are some issues on refreshing. I added a new variable (see resetHintTrue) and it didn't get loaded in the phrase down below. And I deleted a duplicate variable and it didn't get removed from the list (see 2 lightSource variables).

And I noticed an extra curly brace down below. I couldn't find a source from my example description.

[terracoda]

A screen shot may be helpful.

[terracoda]

@zepumph, I need this tool to be named "Phrase Builder".

When it is convenient to do so.

[zepumph]

How's that?

[terracoda]

The url and the title are good, but I would like the H1 to also be "Phrase Builder" in stead of "Dynamic Phrase Manipulator".

[zepumph]

Ahh gotcha, how about that?

[terracoda]

The H1 is great.

I decided to re-write the explanatory text. Let me know if there is a way for me to enter this new content directly.

If not, here's a link to the new content. https://docs.google.com/document/d/1XB7jhgr1ur6hMAh6rZgFYlzev9ALbr6ao_vBwnVqQg0/edit#

I rewrote everything using language we use in the course, and created a numbered list for the steps. I think it reads pretty well.

[zepumph]

I just spoke with @terracoda on slack, she will take a stab at updating https://github.com/phetsims/a11y-research/blob/master/js/phrase-builder/index.html, and then I will come in and ensure that the build still works. Thanks @terracoda!

[terracoda]

Ok, I added all the content for the instructions above where the text areas will begin.

For the first text area

Change the bold text (the text area label) to: "Your description idea:"

And add the following help text

<p>
Enter your idea for a dynamic description with named parameters in curly braces. For example, "Stars in night sky are {{starBrightness}}.":
</p>

Ideally, the help text goes between the label and the actual text area box, but if that can't happen, the help text can follow the text area.

Then there is a sentence starting with "As template variables are added..." Change this sentence to:

<p>
As the named parameters are added to the description above, a text area for each parameter will be added below. Enter options for each named parameter on a new line.
</p> 

Then, just above this changed sentence add bolded text, the same size as above, and the same size as the "Output sentence", ADD: "Options for named parameters:"

Last, change "Output sentence" to "Output description".

I think that does it.