Improving error display by using functions and _body?

[Shane Curcuru <as...@shanecurcuru.org>]

Does anyone mind if I do minor refactoring in some scripts to improve
the error display?

Currently, a lot of scripts do a bunch of work at the global outside the
_html wunderbar section.  That means that errors are just reported in
ruby, not wunderbar, and it's very friendly to users.

If most of the code that does stuff (mostly grabbing source data, which
is usually the only thing that would fail) is instead inside the _body?
section, then wunderbar traps errors and displays them in the context of
the page output.  That gives a much better user experience.

In some scripts, it would also mean refactoring some code into a
doStuff() method, so that the various data manipulation steps many
scripts take can be organized as a chunk, and the user output can be
cleaner.

Comments?

-- 

- Shane
  https://www.apache.org/foundation/marks/resources

Re: Improving error display by using functions and _body?

[Sam Ruby <ru...@intertwingly.net>]

On Fri, Jun 9, 2017 at 8:32 AM, Shane Curcuru <as...@shanecurcuru.org> wrote:
> More to the point: to make Whimsy tools more predictable for our users,
> I recommend copying the following sample code for new cgi's:
>
>   https://github.com/apache/whimsy/blob/master/www/test/test.cgi
>
> This works well for the many "display organized data from various ASF
> sources" scripts that we have.  Hopefully the script itself is
> self-documenting as to the purpose of each different panel element.
> This also ensures all the output is nicely bootstrapped and includes
> aria tags and behavior.

get_data only works well if there is only a single variable created at
the top of the script

> Speaking of accessibility, there are two issues that the WAVE aria
> testing tool shows on this page:
>
> - There is no lang="en" in the HTML header.  Given that we are de facto
> developing in english, what's the simplest way to add this for the
> default scripts we have (preferably in a library, not in each cgi)

If having a language is recommended, then this probably should be in
wunderbar itself.  Default of 'en' seems reasonable enough.  Care to
submit a pull request?  Be sure to update any tests that might fail
after this change.  And add a test for the new function.

> - There is a warning about skipped headers, but this is on purpose.  My
> layout puts two h3 elements up top that provide user-focused description
> and a list of other related tools (this can help committers find all the
> other great stuff in whimsy).  Then the h2 element is the actual data
> the script is putting out - which is really what the user is coming to
> the page to see.
>
> Comments on the _whimsy_body layout appreciated!
>
> In time I hope to update the roster tool to use lib/asf/themes.rb
> instead of it's current banner.rb, along with moving the orgchart model
> into lib/asf (Sam, any hints on that one?)

Modifying a .html.rb file should just work.  Modifying a .js.rb file
will require creating a ruby2js filter.

Essentially, the flow is that a .js.rb file is parsed into an Abstract
Symbol Tree (AST).  Any filters you provide can be run over the AST
and make any alterations you like.  The results will be serialized as
JavaScript.

> - Shane

- Sam Ruby

> Shane Curcuru wrote on 6/3/17 6:08 PM:
>> Does anyone mind if I do minor refactoring in some scripts to improve
>> the error display?
>>
>> Currently, a lot of scripts do a bunch of work at the global outside the
>> _html wunderbar section.  That means that errors are just reported in
>> ruby, not wunderbar, and it's very friendly to users.
>>
>> If most of the code that does stuff (mostly grabbing source data, which
>> is usually the only thing that would fail) is instead inside the _body?
>> section, then wunderbar traps errors and displays them in the context of
>> the page output.  That gives a much better user experience.
>>
>> In some scripts, it would also mean refactoring some code into a
>> doStuff() method, so that the various data manipulation steps many
>> scripts take can be organized as a chunk, and the user output can be
>> cleaner.
>>
>> Comments?
>>
>
>
> --
>
> - Shane
>   https://www.apache.org/foundation/marks/resources

Re: Improving error display by using functions and _body?

[Shane Curcuru <as...@shanecurcuru.org>]

More to the point: to make Whimsy tools more predictable for our users,
I recommend copying the following sample code for new cgi's:

  https://github.com/apache/whimsy/blob/master/www/test/test.cgi

This works well for the many "display organized data from various ASF
sources" scripts that we have.  Hopefully the script itself is
self-documenting as to the purpose of each different panel element.
This also ensures all the output is nicely bootstrapped and includes
aria tags and behavior.

Speaking of accessibility, there are two issues that the WAVE aria
testing tool shows on this page:

- There is no lang="en" in the HTML header.  Given that we are de facto
developing in english, what's the simplest way to add this for the
default scripts we have (preferably in a library, not in each cgi)

- There is a warning about skipped headers, but this is on purpose.  My
layout puts two h3 elements up top that provide user-focused description
and a list of other related tools (this can help committers find all the
other great stuff in whimsy).  Then the h2 element is the actual data
the script is putting out - which is really what the user is coming to
the page to see.

Comments on the _whimsy_body layout appreciated!

In time I hope to update the roster tool to use lib/asf/themes.rb
instead of it's current banner.rb, along with moving the orgchart model
into lib/asf (Sam, any hints on that one?)

- Shane

Shane Curcuru wrote on 6/3/17 6:08 PM:
> Does anyone mind if I do minor refactoring in some scripts to improve
> the error display?
> 
> Currently, a lot of scripts do a bunch of work at the global outside the
> _html wunderbar section.  That means that errors are just reported in
> ruby, not wunderbar, and it's very friendly to users.
> 
> If most of the code that does stuff (mostly grabbing source data, which
> is usually the only thing that would fail) is instead inside the _body?
> section, then wunderbar traps errors and displays them in the context of
> the page output.  That gives a much better user experience.
> 
> In some scripts, it would also mean refactoring some code into a
> doStuff() method, so that the various data manipulation steps many
> scripts take can be organized as a chunk, and the user output can be
> cleaner.
> 
> Comments?
> 


-- 

- Shane
  https://www.apache.org/foundation/marks/resources