WebUI design choice: Accordion groups for the Create Job page

[Jostein Austvik Jacobsen]

As we discussed in Madrid, the /scripts and /scripts/{scriptId} pages will be merged, so you upload files, select a script and fill out the scripts options all on the same page. We talked about using accordion groups[2] for this, but I'm not 100% sure on what we agreed on based on the sketch we drew at the face-to-face[2].

I've drafted a couple of options:

1. Two accordion groups[3]; the first group contains both the file upload widget and the script selection widget. The advantage is that you may not need to upload files for some scripts, or maybe you just want to choose a script before you upload a file.
2. Three accordion groups[4]; first you upload your files, then you choose a script, and in the end you fill out the script options. This gives room for the script descriptions next to the scripts listing.

I'm leaning towards #1...

[1] http://twitter.github.com/bootstrap/javascript.html#collapse

[2] http://code.google.com/p/daisy-pipeline/wiki/WebUIDev#New_"Create_Job"_page_sketch

[3] http://wiki.daisy-pipeline.googlecode.com/hg/img/webui/createJob-option1.jpg

[4] http://wiki.daisy-pipeline.googlecode.com/hg/img/webui/createJob-option2.jpg

Jostein

[Javier Asensio]

I reckon #2 makes the whole process more consistent, one accordion for each step. but IDHASO*

*All rights reserved for @rdeltour

cheers,

Javi

--
You received this message because you are subscribed to the Google Groups "DAISY Pipeline Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to daisy-pipeline-...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Jostein Austvik Jacobsen]

Right, good point.

A related issue: we need a way to label/identify what kind of filesets a script accepts (and preferably also what it outputs) so that the Web UI can filter the scripts list. So again, two options comes to mind:

1. The client could infer the fileset types from the script id:
• Input fileset type = tokenize($scriptId, '-')[1]
• Output fileset type = if (matches($scriptId,'-to-')) then tokenize($scriptId, '-')[last()] else 'report'
• Restricts us to exactly one type of input fileset and one type of output fileset
2. Declare the fileset types as metadata in the XProc script and make it available through the WS
• In /p:declare-step/p:documentation ?
• On p:input / p:option / p:output ?
• For example: <p:option name="href" required="true" px:type="anyFileURI" px:media-type="application/xhtml+xml text/html" px:fileset="daisy202">
• If multiple fileset types can be accepted; @px:fileset could accept a space separated list, just like px:media-type

Thoughts?

Jostein

[Romain Deltour]

As far as I remember, what I had in mind in Madrid was to have 2 different job creation "wizards". One "create from file" and one "create from script".  The main "create job" page would contain 2 big buttons: "upload file(s)" and "select script", leading to the 2 alternative ways of creating a job.

Your two proposals seem to consolidate the upload-first and script-first approaches in one UI. I think what I had in mind (described above) is more aligned with option #2 (i.e. one group for upload, one group for script selection), but maybe allowing the order of groups #1 and #2 to be switched depending on how you reach the job creation page: if the user selects a "upload files" button, the file upload group is the first in the accordion, if the user selects the "select script" button, the script selection group comes first and the file upload comes next.

What do you think ?

Romain.

[Romain Deltour]

Do we need to identify file sets or is  type of the accepted input "master" files (e.g. OPF)  enough ?

How would you detect the file set type in the Web UI ?

Interesting idea anyway. I'd definitely prefer option #2 over an inference on the script's short name.

Romain.

[Jostein Austvik Jacobsen]

Do all filesets have master files? And can we easily distinguish between a DAISY 3 OPF and a EPUB3 OPF? or a DAISY 3 NCX and a EPUB3 NCX?

Some filesets have multiple types as well I suppose. For instance, you could probably use a DAISY 2.02 or a EPUB3 fileset as input to a script that takes HTML as input.

If a fileset contains a file called "ncc.html", should we assume that the fileset is a DAISY 2.02 fileset and hide the scripts that takes HTML as input?

In the Web UI I suppose I would have to hardcode in what a fileset looks like for each format. Or maybe we could define a XML vocabulary for describing filesets (folder structure + file contents). Something like:

<fileset id="daisy202" name="DAISY 2.02">

    <file href="ncc.html"/>

</fileset>

Jostein

[Jostein Austvik Jacobsen]

Right. Although, I thought we decided to have two different paths because some scripts might not require uploads. So wouldn't we skip the file upload step in case the user selects a script first?

Jostein

[Romain Deltour]

 wouldn't we skip the file upload step in case the user selects a script first?

Yes, if the script does not require input files. On the other hand, we would still allow a "script first" approach for the other scripts, in which case the file upload widget would show up in the accordion.

Romain.

[Jostein Austvik Jacobsen]

1. So you click "+Create Job" and get this: http://josteinaj.no/images/2013/createJob-sketches/createJob-pickYourPath.jpg
2. If you click "Upload File(s)":
1. Add files: http://josteinaj.no/images/2013/createJob-sketches/createJob-filesFirst-files.jpg
2. Then choose script: http://josteinaj.no/images/2013/createJob-sketches/createJob-filesFirst-scripts.jpg
3. Then fill out options and start the job: http://josteinaj.no/images/2013/createJob-sketches/createJob-filesFirst-options.jpg
3. If you click "Select Script":
1. Choose a script: http://josteinaj.no/images/2013/createJob-sketches/createJob-scriptsFirst-scripts.jpg
2. If you chose a script that accepts files:
1. Add files: http://josteinaj.no/images/2013/createJob-sketches/createJob-scriptsFirst-acceptsFiles-files.jpg
2. Then fill out options and start the job: http://josteinaj.no/images/2013/createJob-sketches/createJob-scriptsFirst-acceptsFiles-options.jpg
3. If you chose a script that does not accept files:
1. Hide the "files" accordion group and go straight to the options accordion group: http://josteinaj.no/images/2013/createJob-sketches/createJob-scriptsFirst-doesNotAcceptFiles-options.jpg

Jostein

[Romain Deltour]

Awesome wireframing, could you make an animated GIF version ? :p

Yes, the UX you describe is what I was thinking. In any case, the idea is to "streamline" the job creation process as much as possible. Any suggestion and comment obviously welcome.

Romain.

[Jostein Austvik Jacobsen]

Animated GIF FTW! :)

Upload File(s) path: http://josteinaj.no/images/2013/createJob-sketches/filesFirst.gif

Select Script path: http://josteinaj.no/images/2013/createJob-sketches/scriptsFirst.gif

Select Script path w/o files: http://josteinaj.no/images/2013/createJob-sketches/scriptsFirst-noFiles.gif

The only issues I can think of with this:

• the file selection accordion group and the script selection accordion group swaps places depending on what button you push - could get confusing?
• there's an extra step involved - deciding whether to upload files or select a script first

Jostein

[Romain Deltour]

Yep, I agree about the 2 issues. About issue #2, I was wondering if the first step of the accordion (file upload or script selection) could be handled in the landing "create job" page, which would then 

lead to the accordion page where the first group is collapsed since it's just been completed in the landing page.

E.g. pressing the "upload files" button would not directly lead you to the accordion's first group, but would actually show the file browse dialog to upload the files, when pressing OK the next page w/b the accordion with the files uploaded already.

Likewise, rather than pressing a "Select script" button then selecting a script in the accordion, the user could see a list of scripts already, then select one to move to the accordion page with the script pre-selected.

R.

[Jostein Austvik Jacobsen]

So kind of like my initial option #1 then? http://wiki.daisy-pipeline.googlecode.com/hg/img/webui/createJob-option1.jpg

Jostein

[Romain Deltour]

I was thinking of the first step in its own page (the main 'Create Job') page, not part of the accordion. Performing the first step would then lead to the accordion with job uploads and script selection separated as in your original option #2.

Romain.

[Jostein Austvik Jacobsen]

Would it be ok to just hide the first part of the page (display:none) and show the second part of the page (with the accordions) dynamically?

Like this: http://josteinaj.no/images/2013/createJob-sketches/createJob-bothFirst-thenAccordions.jpg (combination of #1 and #2)

At first only the file upload + script list would be visible. After uploading one file or selecting a script, that part of the page disappears and the three accordions becomes visible...

Jostein

[Romain Deltour]

Yes, I suppose it w/b fine. Of course we need to check the overall accessibility of this configuration page +   accordion widget.

R.

[Jostein Austvik Jacobsen]

Yeah I know. I've considered making the accordion titles into <h2>s so that they appear in the TOC for screen readers. Also, maybe we don't even need the accordion groups? Do we really need to collapse part of the page? (They're easy to remove later if we want to).

Jostein

[Jostein Austvik Jacobsen]

Say we try to use only the master files (ncc, ncx, opf):

• The /ws/scripts listing does not describe the inputs for each script, so the Web UI would have to check all scripts each time it loads the scripts list (/ws/scripts/zedai-to-dtbook, /ws/scripts/dtbook-to-epub3, etc.) We could include the inputs in /ws/scripts but it would be nice to keep that payload as small as possible.
• A script can have multiple file inputs and there is no "primary" input to define what is the master file. For instance, maybe there's a file input that lets you select which CSS file to use.
• The DAISY 2.02 master file is HTML, so whenever you upload something with an HTML file in it, the DAISY 2.02 to *** scripts will show up, and vice versa.

So I think I'd rather have some more metadata about the fileset type(s) that a script accepts (and provides as output?) than base it off the master files.

If we define this metadata in the scripts, we could also have the fileset version separately. EPUB version 2.0 / 3.0. DTBook version 2005-1 / 2005-2 / 2005-3. HTML 4 / 5.

In /ws/scripts we currently have:

<script href="http://localhost:8181/ws/scripts/dtbook-to-html" id="dtbook-to-html">

<nicename>DTBook to HTML</nicename>

<description>Transforms DTBook XML into HTML.</description>

</script>

What if we had something like:

<script href="http://localhost:8181/ws/scripts/dtbook-to-html" id="dtbook-to-html">

<nicename>DTBook to HTML</nicename>

<description>Transforms DTBook XML into HTML.</description>

<input-format id="dtbook"/>

<output-format id="html" version="5"/>

</script>

(input-format/@version not being defined means all versions is ok)

Jostein

[Jostein Austvik Jacobsen]

Only one accordion group are expanded at any given time. So when you're choosing a script, you can't see what files you've uploaded. When you're uploading files, you can't see what script you have chosen. And when you're filling out the options, you don't know what files you've uploaded or even what script you've chosen.

So I think we should have a short summary at the top of the page (or possibly floating in a sidebar?). See the attachment.

What do you think?

Jostein

[Romain Deltour]

A summary sounds like a good idea. Could it be possibly integrated to the accordion's headers ?

E.g.:

>  Files - Alice in Wonderland.zip (DAISY 2.02, HTML)

> Script - ZedAI to EPUB 3

v Options

source: _________

R.

<createJob-withSummary.png>

[Javier Asensio]

Yep, it seems pretty clear

cheers,

Javi

[Jostein Austvik Jacobsen]

Yeah, I tried that actually, but I'm not sure about how to make it look good. (see attachments)

If we change the "Scripts" header to "Script - ZedAI to EPUB 3" it will look like the group contains more information about the ZedAI to EPUB 3 script, while it is actually still a script listing (see screenshot 49:46).

We could append a muted "(selected: ZedAI to EPUB 3)" string after "Scripts", on a new line to keep the "Scripts" part centered (screenshot 48:40). Does that look ok even when the file accordion group is expanded though? (screenshot 13:13)

And in both cases, I don't think we can fit in the description of the script or information about what fileset has been uploaded into the headline for the accordions, so that will have to be listed inside the accordions themselves.

Jostein

[Javier Asensio]

I like 1 and 3 more. They seem clearer to me.

cheers,

Javi

[Jostein Austvik Jacobsen]

Of the 3 I uploaded in my most recent mail, #2 and #3 are the same (the 48:40 and the 13:13 ones; I should've renamed the files :P).

Jostein

[Javier Asensio]

HAha, yes, I meant #2 and #3, the ones with the file name in grey XD. I mention #3 as I liked the 'and 17 more files'  thingy

cheers,

Javi

[Jostein Austvik Jacobsen]

Hehe, yeah that makes more sense :).

Yeah I agree I like those better. I'm not sure what I like better though; inline the info with the accordion group headers or list it in a summary above the accordion right under the <h1>.

Jostein

[Jostein Austvik Jacobsen]

So the latest version of the Web UI in the v1.5 branch detects what kind of fileset is uploaded.These MIME types are currently used:

DAISY 2.02: multipart/x-daisy202

DAISY 3: multipart/x-daisy3

DTBook: application/x-dtbook+xml

ZedAI: application/z3998-auth+xml

EPUB: application/epub+zip

It is unable to filter the scripts based on this though as it doesn't know what the scripts accepts as input. To do so we would still need a way to declare input (and possibly output) fileset types in the scripts and to expose it through the Web API.

The input/output fileset types doesn't really belong on inputs/options/outputs like px:media-type though. An EPUB scripts input option might specify px:media-type="application/oebps-package+xml" but the input for the script itself would be "application/epub+zip". So one option would be to declare @px:input-media-type (and @px:output-media-type) on the root element of the script.

What do you think?

More details on the issue tracker: http://code.google.com/p/daisy-pipeline/issues/detail?id=41

Jostein

[Romain Deltour]

one option would be to declare @px:input-media-type (and @px:output-media-type) on the root element of the script.

Sounds like a reasonable enhancement.

Couple questions that comes to mind though:

- what if the script requires different file sets ?

- what if the script allows several alternative fileset types ?

Each of these use case could be solved by a whitespace-separated list of types, but not both of them at the same time. Ideas ?

Romain.

[Jostein Austvik Jacobsen]

Yes, a whitespace-separated list like we do for @px:media-type on the inputs/options is what I had in mind if the script accepts multiple filesets. For instance, you could have a "upgrade-old-daisy-to-daisy4" script (with a better name) which accepts both DAISY 2.02, DAISY 3 and DTBook as input.

What's the difference between "different" and "several alternative" filesets?

Jostein

[Romain Deltour]

What's the difference between "different" and "several alternative" file sets?

One the one hand, the script requires both a DAISY 3 and DAISY 2.02 file sets, on the other hand another script requires either a DAISY 3 or a DAISY 2.02 file set.

R.

[Jostein Austvik Jacobsen]

Right. I suppose the same could apply for @px:media-type for inputs/options?

We could use comma-separation for "AND" and space-separation for "OR"?

Jostein

[Javier Asensio]

What you think of having this in the API for the script element:

<script [...] px:input-filesets="..." px:output-filesets="...">

In the xpl file we describe on each input/output port and option which fileset is expected if any.

I dont really fancy the idea of having commas and spaces as 'ands' and 'ors' as '&' and '|' already have those semantics.

But the whole point is filtering the scripts given a file set, isn't it? So we could use a comma (or space) separated list without really considering what the relationships are among those filesets, right? Facing it more as a keyword description than a functional description.

cheers,

Javi

[Jostein Austvik Jacobsen]

@input-filesets and @output-filesets to the <script/> element in the Web API sounds good to me.

Attaching fileset information on to the p:input/p:option/p:output elements would work I guess, but a fileset can span across multiple ports and options. For instance, a script that takes DAISY 3 as input could accept the NCX on a p:input port, DTBooks on another p:input port and auxiliary files on a p:option.

The XProc analogue to the <script/> element in the Web API is <p:declare-step/> and <p:pipeline/>. What do you think of adding @px:input-filesets and @px:output-filesets to those?

But the whole point is filtering the scripts given a file set, isn't it?

Yeah, that's true; the point is to filter the scripts. If you upload a DAISY 2.02 fileset to the Web UI then scripts that require both a DAISY 2.02 fileset *and* a DAISY 3 fileset should still be in the list of available scripts. If you don't provide all the required filesets when you start a job, that will be reported in the execution log. It should also be clear from the script description and port/option descriptions what kind of filesets are expected.

Jostein

[Romain Deltour]

All that sounds good to me.

Romain.