EZ Help parsing - Githubissues

GoogleCodeExporter commented 8 years ago

'''Since you haven’t gotten to the Help side of EZ Access very much, I wrote 
some code to help you along. I started a function to parse an element and its 
descendants to find help layers. This isn’t high priority yet, but I wanted 
to give you a head start. You can add this code to the main code or keep it as 
a separate module (which is what I recommend). The main module (or perhaps the 
help module itself?) would need to get the help string array and then put it 
into the lightboxes appropriately as layers.

Currently, the module only gets help layers that are directly written into the 
data-ez-help attribute. There is currently no support for URLs or any other 
kind of references to separate help files. When you get to implementing that, 
we can discuss the pros and cons of different files and structures.

The js and a basic test page are attached.

--Bern'''

This is some parsing code for the potential EZ Help lightbox.

Bern -- as layers, do you mean the user presses ez help, and then a trigger for 
more help (a button on the bottom or something) would give the more general 
(parental) help?

In terms of data structure, I think a JSON or something is a little 
underpowered/not as flexible as we need, since it doesn't work with raw HTML as 
well. I propose we do something similar to what the vast majority of lightboxes 
use to store the content before being clicked: Simply have a hidden div on the 
page that the lightbox (or in our case, ezhelp) reads from.
An example: http://jbutz.github.io/bootstrap-lightbox/

In our case, the div24-1 (or whatever) would reference an element on the page 
with content inside, as so:
{{{
<div class="ezhelp" id="div24-1">
    For more help, click <a href="here.html">here</a>.
</div>
}}}
Where the ezhelp class is a helper class embedded with EZ Access's CSS 
stylesheet that has the hidden element CSS stuff so it's not viewed on a normal 
page.

Original issue reported on code.google.com by aeharding on 31 May 2013 at 6:39

Attachments:

GoogleCodeExporter commented 8 years ago

How EZ Help layers should work:
When the user presses (and releases) the EZ HELP button, the lightbox pops up 
with the first help layer.
When on a help lightbox, the user can go to a previous layer with EZ UP or a 
later layer by EZ DOWN.
Each layer has an automatic message at the bottom saying how to continue/exit.
The user can exit the help lightbox by (1) pressing EZ HELP or (2) "falling 
out" of the top or bottom with EZ UP or DOWN respectively.
 >> This behavior is exhibited in the demo and you can find more detail there.

Original comment by jbjor...@gmail.com on 31 May 2013 at 7:24

GoogleCodeExporter commented 8 years ago

My intent with the data-ez-help attribute is that it would support both regular 
strings or references to other content. Layers associated with an element would 
be delimited by a pipe (|).

Example:
data-ez-help="This is the first layer of 
help|#layer2|helpdoc.html#layer3|helplayer4.html|This is layer 5"

This example has five layers
1 = the string "This is the first layer of help"
2 = a reference to #layer2
3 = a reference to helpdoc.html#layer3
4 = a reference to helplayer4.html (where the <head> and <body> tags would be 
removed, I think)
5 = the string "This is layer 5"

Original comment by jbjor...@gmail.com on 31 May 2013 at 7:29

GoogleCodeExporter commented 8 years ago

The Help Layer "cascade":
In general, help layers of an element are followed by help layers of a parent, 
grandparent, etc. all the way to the help layers of <body>.

This behavior can be overriden by terminating a data-ez-help attribute value. 
If the attribute ends with the terminator ('||' in the code), then the 
"cascade" ends and no additional help layers are provided.

So this would terminate the cascade:
data-ez-help="Layer 1|Layer 2|Layer 3||"

But these would not:
data-ez-help="Layer 1|Layer 2|Layer 3|"
data-ez-help="Layer 1|Layer 2|Layer 3"

Original comment by jbjor...@gmail.com on 31 May 2013 at 7:34

GoogleCodeExporter commented 8 years ago

Note, that often a person will press EZ HELP when EZ Access is not activated. 
For example, the speech idle loop often will instruct a person to press EZ HELP 
in order to get initial help in getting starting with EZ Access.

When nothing is highlighted and EZ HELP is pressed, the help layers associated 
with <body> should be provided.

We probably should provide a generic <body> help text in a separate HTML file 
if <body data-ez-help=""> is not specified. The text from the demo would be a 
good start. I will prepare and attach a generic Help file later.

Original comment by jbjor...@gmail.com on 31 May 2013 at 8:13

GoogleCodeExporter commented 8 years ago

The EZ Highlight does not appear in the lightbox. The help text is read.

If the highlight was active when the user pressed EZ HELP, it remains on the 
element that was highlighted. The lightbox will be in front of the highlight.

When the user exits from help, there should be a sound.

If the user ONLY heard text from the first help layer (i.e., they only pressed 
EZ HELP) and exited Help by pressing EZ HELP again, the system should not 
re-read the highlighted item.

If the user took any action in EZ HELP and then exited (in any manner), the 
system should say: "Exited Help:" + re-read the element that is highlighted.

Original comment by jbjor...@gmail.com on 31 May 2013 at 8:18

GoogleCodeExporter commented 8 years ago

I would like your feedback on this, Alex...

It could be potentially annoying for a designer to have to do this on every 
page:
data-ez-help="help.html#layer1|help.html#layer2|help.html#layer3"

The layers could potentially be designated in the HTML file in addition to the 
pipe-separated notation. For example:

<div id="alllayers">
<section id="layer1"> text... </section>
<section id="layer2"> text... </section>
<section id="layer3"> text... </section>
</div>

Where each <section> is treated as a different layer, so the developer could 
just write:
data-ez-help="help.html#alllayers"
...and get three help layers.

I think that <section> might be the best way to do it. If there is content not 
enclosed in a <section>, I'm not entirely sure what to do with it 
though--perhaps discard it (which would allow for annotations).

So, a <div> or whatever that contains no <section>s would be used as a single 
layer.
If the <whatever> contained at least one <section> then only the content in 
each <section> will be used for each layer.

Original comment by jbjor...@gmail.com on 31 May 2013 at 8:43

GoogleCodeExporter commented 8 years ago

Are you sure that you want it on a separate HTML page?

If we're going to be referencing data in a different file, I don't think HTML 
would be the best bet, but JSON looks more appealing... I know I'm going back 
on forth on this but I am changing my views as I think about this more/you show 
me more on how this feature would work.

Either that on XML, which as you know is data in HTML-ish form.

Why do you want to use HTML?

Original comment by aeharding on 3 Jun 2013 at 5:18

GoogleCodeExporter commented 8 years ago

I think that there should be support for Help layers on separate pages. Most 
help files will be related to the application, not a screen. Thus it would be 
easier to maintain things if the help content could be edited in one place. 
That being said, I think it would be fine to support same-page help content as 
well.

I do not actually care what format the help layer data is in. I want there to 
be a simple way (plain text) and a way that allows for rich text formatting 
(like HTML). The rich text formatting would mostly be for visual effect because 
help layers are supposed to be read as a page--although it might be useful to 
have the data-ez-sayalt attribute for times when the speech engine badly 
mangles phrases, for example.

XML would be fine by me, but the biggest trick is that you cannot use some 
common JavaScript features such as document.getElementById() unless a DTD 
defines an attribute as an ID type. XML could easily encapsulate HTML data.

HTML has the downside of not being particularly well-formed and easy-to-parse 
in general. Of course we can require whatever we want for help files.

I'm not so familiar with JSON... I don't know how well it can encapsulate 
HTML-like data.

Original comment by jbjor...@gmail.com on 3 Jun 2013 at 3:26

GoogleCodeExporter commented 8 years ago

These are good points!

http://globalelearning.wordbank.com/best-practices/cdata-encapsulation-for-html-
inside-xml/

This might be messy for the EZ Access content designer. Perhaps we should just 
use straight HTML and spec it. It's not like we're loading a page with it (just 
loading directly with Javascript), so I have no problem with this.

If you agree, I say lets get something written on paper and start it.

Original comment by aeharding on 5 Jun 2013 at 1:23

GoogleCodeExporter commented 8 years ago

Let's do this...

>> In the data-ez-help="" attribute:
Layers are delimited by |
A layer may be plain text-in which case that text is put in the lightbox
A layer may be a reference to another file (such as .txt or .html)-in which 
case, the whole of that document is but in the lightbox.
A layer may reference an ID of an HTML file (the current one or another)-see 
the next section...

>> References to a part of an HTML file (an id)
If the referenced element does not have a data-ez-help attribute, then just put 
the entire referenced element into the lightbox as a single layer.
If the referenced element has a data-ez-help attribute (with any value), then 
assume it is written correctly and has layers and see the next section...

>> Layers in a referenced element
Look for <section>...</section>. Each <section> contains a help layer. So the 
first <section> goes in the lightbox, then the second <section> and so on. Any 
content not in a <section> gets completely discarded.

For example
data-ez-help="Layer 1|#div1|Layer 2|#div2|Layer 3"

And in the HTML
<div id="div1">This is div1</div>
...
<div id="div2" data-ez-help>Some comments
  <section>Layer A</section>
  <section>Layer B</section>
  <p>More comments</p>
  <section>Layer <strong>C</strong></section>
</div>

Help layers/lightbox pages
1: "Layer 1"
2: This is div1
3: "Layer 2"
4: Layer A
5: Layer B
6: Layer <strong>C</strong> //Note, rendered as HTML like others
7: "Layer 3"

Let me know if anything is unclear or you think something different should be 
done.

Original comment by jbjor...@gmail.com on 5 Jun 2013 at 9:02

GoogleCodeExporter commented 8 years ago

Attached is the start of a layered help file that you can use in testing. This 
file will change in the future, but should be made part of the EZ Access "core."

Original comment by jbjor...@gmail.com on 5 Jun 2013 at 10:02

GoogleCodeExporter commented 8 years ago

Awesome. Thank you, Bern.

Original comment by aeharding on 5 Jun 2013 at 10:31

GoogleCodeExporter commented 8 years ago

Original comment by aeharding on 6 Jun 2013 at 3:20

Changed state: Started

GoogleCodeExporter commented 8 years ago

r152 makes a huge dent in the ez help project.

Only thing left is to make navigation to further more generalized help (but I 
can easily do this... just have to stop since I'm getting pretty tired).

Original comment by aeharding on 6 Jun 2013 at 6:28

GoogleCodeExporter commented 8 years ago

Oh, and I dealt with not finding an ID or file by giving it the unchanged ref 
(i.e., 'blah.html#hello') and throwing an error to the console for debugging.

One other thing... To determine if it's *not* a string:
 1. I check for a '#'
 2. If nothing before, I look for that ID
 3. If something before, I look for a '.' with 'htm' or 'html' afterwards.
 4. If I find this, I attempt to look for the filename.

Original comment by aeharding on 6 Jun 2013 at 6:32

GoogleCodeExporter commented 8 years ago

I made a small change to the default help layers file to replace that which I 
had attached in Comment #11.

Original comment by jbjor...@gmail.com on 6 Jun 2013 at 1:59

Attachments:

defaultEZHelp.html

GoogleCodeExporter commented 8 years ago

Perfect. Just got to get that <section> thing supported now.

Original comment by aeharding on 6 Jun 2013 at 3:43

GoogleCodeExporter commented 8 years ago

<section>s supported. All EZ Help parsing/retrieving complete. Now just 
navigation through help layers.

Original comment by aeharding on 6 Jun 2013 at 5:24

GoogleCodeExporter commented 8 years ago

Did some work today, including adding default ez help support.

Original comment by aeharding on 23 Aug 2013 at 8:18

GoogleCodeExporter commented 8 years ago

This issue was closed by revision r262.

Original comment by aeharding on 26 Aug 2013 at 8:32

Changed state: Fixed

minutekey / ez-access-web

EZ Help parsing #33