Reorganizing to a Medium-sized Flask Application

in opw

 

My Flask application has been growing in size, and I needed to reorganize my current module into a package. I learnt to do this from Flask’s documentation. The small application that used to have this hierarchy:

/relmandash
    /relmandash.py
    /relmandash_test.py
    /models.py
    /static --> for .css and .js files
    /templates --> for .html files
    /helper_packages

now looks like this:

/relmandash
    /relmandash_test.py
    /runserver.py
    /relmandash
        /__init.py
        /view.py
        /models.py
        /static
        /templates
        /helper_packages

3 easy steps to shift from a module to a package:

  1. Create another folder named after the application (relmandash in this case), and move everything that was required by relmandash.py (including relmandash.py) into this folder.

  2. Rename relmandash.py into init.py.

  3. Create a new file runserver.py and add these two lines:

    from relmandash import app
    app.run(debug=True)

Simple! Notice how the test application is still located outside of the newly created folder. This does not change as relmandash_test.py just makes use of the relmandash package.

Since I was already re-organizing the application, I thought I might as well group my view functions (functions with @app.route above them) into another file called views.py. I already had a models.py file for my database schema declarations and the import works the same way. All I had to do for views.py was add this line to the top:

from relmandash import app

And right at the bottom of init.py:

import relmandash.views

The documentation does provide an explanation for using circular imports, so I will not go into detail here. I suppose I still don’t see the need for blueprints yet, so meanwhile I’ll savour my new and tidy package!

Donald Norman on Design Principles

in opw

 

I’ve recently started paying more attention to the application’s design, and Lukas recommended reading up on Donald Norman’s views on design. Not just design for web applications, but design for everyday tools - kitchen appliances, vehicles, mobile phones, etc. His speeches reconcile the various types of design techniques out there into one: user-centered design. All designers should place themselves in the users’ shoes in order to achieve good design. In one of his presentations, Donald introduces the six design principles that make up good design. Here, I will be describing these six principles in terms of their applications into web design, through my understanding.

Visibility

First question to ask: “Can I see it?” Rules to remember:

  • Font sizes, layout dimensions, and object positions should be relatively defined (%, em…). This is to cater for the variation of screen sizes from that of a tiny Blackberry Bold/Curve to a huge 23” monitor, otherwise your website will be looking like this. Doubtful that webpages will be seen across 40” flat screens but one can still plan for that!
  • Adequate spacing and proper emphasis. So that users will be able to SEE what they need to WITH EASE. Personally I do not like scrolling too much (unless it involves some attractive Photoshoped background that makes scrolling fun i.e. Toshiba’s hdd site, anything important should be before my eyes once loaded, so company banners/headers should not take up half the page before showing what NEEDS TO BE SEEN.

Feedback

Second question: “What is it doing now?” Rules:

  • Error notification is a must, but depending on the target audience and nature of the web application, may or may not be too specific. For example, Password confirmation is incorrect would be much more informative than Invalid input in one of the fields in a user sign up form, but printing a whole stack trace of an error might lead to exposed source code for hackers!
  • Progress bars I love them! And would like to figure out how to incorporate them into the dashboard while it is waiting for Flask’s server to load data. Otherwise, I’ll have to work on the performance (story for a later time) or use JS instead to grab every tab’s data separately (very un-MVC-like, but who doesnt love HArthur’s dashboard?)

Affordance

“How do I use it?”

  • WYSIWYG Although this term was meant for UI editors, I would like to use it here to describe what websites should be to users in terms of features and functionality. In particular, non-links should NOT have pointers as cursors when hovered over like this. In any case, design should never affect what the user thinks the website is capable of doing.
  • Be helpful to users, provide hints, or lead them in a step-by-step process, but don’t overdo it! Again, it still comes down to the target audience.

Mapping

“Where am I at using this, and where can I go from here?”

  • Navigation - Depending on the access priviledges of a user, websites could limit or make abundant the links available to different users. I learnt from my Web Applications course that the admin page should never be a link that can be accessed by a user, rather a separate or entirely different path.
  • Site maps are nice to have, but I’ve seen some automated ones that display all available pages without organisation, the site would have been better off without it.

Constraint

“Why can’t I do that?”

  • Plan what the user can, or can’t do.
  • Hide/Lighten buttons/links/menu that cannot be clicked on.
  • Test if the constraints work, and if the user can perform functions that should be allowed.

Consistency

“I think I’ve seen this before?”

  • Use a layout template for a consistent header, footer, and menu.
  • Stick to tradition Top left for the homepage link, top right for user account summary, etc…

Of course, these are just the foundation towards a good website. As for the looks, style and feel, I’ll have to consult others for now

Jinja2 templates, Javascript and HTML

in opw

 

I’ve been using Flask to build the release dashboard, and so far the building and configuration have been the definition of smooth sailing. However, it took me two weeks to realize the templates for HTML output do not make use of something the developers of Flask built themselves, but a syntax named Jinja2! So much for skim-reading the tutorials. Take this simple code,

{ % for elem in array % }
    <p>{ { elem } }</p>
{ % endfor % }

Turns out, if i wanted to check if array was empty before looping, I could do

{ % if array % }
    # loop and print
{ % else % }
    # print something else
{ % endif % }

I found that out from Django’s docs and thought that I was using the Django template syntax all along! P.S.: I tried count(array), len(array), array|length, array.size and the list goes on…

Similar to mixing HTML in between Jinja2 syntax, a template doesn’t need to have Javascript and Jinja2 as separate blocks of code. Instead of pure Javascript:

<script type=text/javascript>
    function print_table(type) {
        $.getJSON($SCRIPT_ROOT + '/' + type, function(data) {
            if (data.result.length > 0) {
                var table = 
                    ['<thead><tr><th>ID</th></tr></thead>'];
                $.each(data.result, function(index, bug) {
                    table.push('<tr><td>' + bug.id + '</td></tr>');
                    }
                });
                $('<table/>', {
                    html: table.join('')
                }).appendTo('body');
            } 
        });
    }
</script>

one can do

{ % if beta % }
    <table>
        <thead><tr><th>ID</th></tr></thead>
        <tbody>
        { % for bug in beta % }
            <tr><td> </td></tr>
        { % endfor % }
        </tbody>
    </table>
{ % endif % }

for the same output, though the former uses Javascript to obtain the list in JSON after the page has loaded.

A Plan for the Release Tracking Dashboard

in opw

 

I know, I’m no writer and I need nudges and several reminders just to write a blog post (winks to Marina and Lukas >.-). Anyway, here’s what I have been up to.

The past few weeks have been all about moulding the dashboard’s requirements and getting started on coding what a user, either the release team or any other contributor, will be able to SEE.

The dashboard’s main page will adopt Dietrich’s FirefoxOS Status, with extra large indicators as to how far away Firefox is from being able to be released, in terms of open bugs left. This will be where the release team and contributors get an idea of the overall progress of the product, before having the choice of drilling down to a more detailed view of what exactly is driving those numbers.

Individual view draft

The first of two dashboard views is the individual view, where a user will be able to identify assigned and tracked Beta, Aurora, and ESR bugs by default. An option to login will enable the user to view his/her assigned security bugs (easily distinguishable from normal bugs as they will be displayed in a different font/highlighting/colour - blue in this case as shown above). Additional security group bugs that are not tracked will appear after those tracked. Ideally, some visualization of a user’s level of activity/progress can be illustrated, which I think would be a great motivation for contributors to work towards resolving as many bugs, ASAP.

Besides logging in, another plan for the individual view is to incorporate a menu similar to that of Heather Arthur’s Bugzilla ToDo’s, but only including bugs that are to be nominated, waiting for approval, or waiting to be uplifted. Although, I might have to steal Heather’s design ideas because that one page is so simple, focused, and just plain cute!

While trying to understand the various stages a bug can fall into, I recently learnt that a resolved bug does NOT mean that a case closes! The shortest example (thanks a bunch to Lukas for explaining it to me a million times, finally typing it out for me to further spend time to digest): bugs that are waiting for approval is defined (in Bugzilla terms) as

(1) tracked bugs that are RESOLVED FIXED, (2) at least one of the status-firefox < version> flags for Aurora/Beta are NOT marked fixed, but (3) it does have a patch(es) already nominated for approval-mozilla-(beta,aurora) with a ?

For interested beginners, I suggest looking at bug 819781, or spend several hours staring at the definition, then search bug 819781!

I shall leave the second dashboard view to a later time, when more thought has been given to what needs to be presented. For now, finishing the core functionality of the individual view!

Mozilla's Existing Dashboards

in opw

 

Before coming up with a relman/releng dashboard, I had to examine various dashboards created by fellow Mozillians that helped in bug searching in one way or another. There may be some that I missed, but I’ll try my best to evaluate more in the coming week in order to be sure of what we need for our dashboard.

Bugs Ahoy! by Josh Matthews

For new Mozilla contributors, this is a great place to search for bugs according to aggregated components. Using pure Javascript to communicate with the Bugzilla API and HTML/CSS to render the contents, Bugs Ahoy! is a single page application which allows for searches of open bugs by components and skills, with the additional option of displaying only unassigned bugs. Besides bugs related to the search components, there is also a link to each team’s wiki if the user wishes to get more involved. The dashboard adopts the three column layout, with search filters and extra information on both right and left columns, and the list of bugs located in the middle column. Content is cut down to a minimum for the bugs list (in descending order of time reported), including only the bug’s ID and a short summary. On hover, information about the bug’s last update and asignee are displayed. I personally feel that Bug’s Ahoy! is certainly a much better experience than searching using bugzilla’s search engine.

bzhome by Heather Arthur

For all who have contributed, bzhome is a good way to keep track of recently updated bugs related to a user. The single page application was written in Javascript, HTML and CSS. The site prompts for the user’s email address on entering, and displays the user’s bugs list. The list can be filtered by component or bugs that were CC’d/assigned to the user. Visually simple and straight forward, each section has a heading to avoid confusion. However, the reviews and feedback sections do not seem to display any information.

Bugzilla-Dashboard by Atul Varma

Bugzilla Dashboard is a more organized dashboard for experienced contributors, also written in Javascript. After specifying a Bugzilla user email address, the user’s bugs to review, assigned, reported, cc’d and recently fixed bugs can be viewed on one page, in time descending order. Besides the different lists of bugs that can be related to a user, I especially liked Atul’s menu to authenticate an existing user, change a user, refresh/repair the existing bugs lists, find a user, and file a bug. Overall, the page looks simple and neat, but requires scrolling horizontally to view all five bugs lists.

Firefox OS Status by Dietrich, along with Basecamp Blockers

This easy dashboard shows Firefox OS Basecamp contributors the number of bugs they are assigned with. To avoid scrolling, contributors can search their names to see if they are assigned any bugs. Like the previous dashboards, this page was written in Javascript, HTML and CSS. Dietrich’s target audience can benefit by briefly checking their Bugzilla username on the site, and if present, clicking the link that leads straight to their assigned bugs.

L10n-Triage, beta dash, l10n dash in wiki by Axel

Axel’s contribution to Mozilla’s localization community proves beneficial, in terms of tracking localization bugs and their activities. The three dashboards, implemented using Javascript, present different information related to localization bugs, so users can choose to use each one depending on their purposes.

L10n-Triage

L10n-Triage retrieves bugs for Boot2Gecko with the keywords ‘late-l10n’ and visualizes the daily total number of bugs. Besides that, all bugs amounting up to the total are listed with the functionality to order by ID, summary, resolution, last fixed date, filed date, late-l10n date, and basecamp status. For Boot2Gecko contributors, this application is certainly a minimal yet sufficient replacement for bug searching and analysis.

Beta Dash

A day-to-day visualized localization bug activity, with the options to filter by locale and/or modifier/commenter. The page is designed in a very simple manner, where the main focus is the visualization, and filtering options are located at the sidebar. For ease of characterization, Axel even made the effort of assigning different coloured text to each locale.

L10n Dash in Wiki

Displays the number of open bugs for each locale in Mozilla’s wiki. Each link

Socorro Releases by Chris Lonnen

As the name suggests, this is a page for tracking Socorro Releases. The page provides necessary information for each release, ie. scheduled release date, freeze date and current status; while listing useful links for more detailed information (bugs list, build link, crash statistics). I would say this page is mainly used internally among the Socorro team, where all the useful links can be found. Hosted in Mozilla’s wiki, the design adopts Mozilla’s standard wiki page, with information neatly arranged in tables. I have yet to ask Chris about the automation process of this dashboard.

If there’s one thing I learnt from my honour’s thesis, it is the importance of a thorough survey of related works done by others. I have kept a comparison table to summarize the differences and any requirements/design that can be adopted from these dashboards, and will continue updating it with others that I can find. Hope my next post will be about starting the dashboard!

Got an internship!

in news

 

Had a sleepless night and got up only to find the real announcement time to be at 6am tomorrow (8pm GMT) T_T Thankfully, Lukas sent me an email in the afternoon and I finally knew that I GOT IN! YAY! Anyway, I’ll be jotting down anything related to my internship here. Looking forward to an invaluable experience and a helpful starting contribution towards the FOSS community!

I would like to thank the GNOME OPW coordinators and Mozilla for organizing and sponsoring this wonderful program! And congratulations to the applicants who got in!