keithamoss / hansardalerts

@HansardAlerts for Western Australia's Hansard

This is the source for the govhack-science website highlighing sciency datasets at govhack-science.github.io.

Content served by Jekyll, with layout and nice bits stolen shamelessly from Rasmus Andersson.

Planning

GovHack Data Model

Documentation

• Jekyll
• Liquid Templating Engine
• Liquid For Designers

Requirements

• Ruby
• RubyGems
• NodeJS
• Python
• Jekyll

Installation

https://jekyllrb.com/docs/installation/ https://jekyllrb.com/docs/github-pages/

Our friends at GitHub have provided the github-pages gem which is used to manage Jekyll and its dependencies on GitHub Pages. Using it in your projects means that when you deploy your site to GitHub Pages, you will not be caught by unexpected differences between various versions of the gems. To use the currently-deployed version of the gem in your project, add the following to your Gemfile

The best way to install Jekyll is via RubyGems. At the terminal prompt, simply run the following command to install Jekyll:

$ gem install github-pages

All of the GitHub pages flavour of Jekyll, and its gem dependencies are automatically installed by the above command, so you won’t have to worry about them at all.

Run

https://jekyllrb.com/docs/usage/

jekyll serve

If you receive a message like:

Could not find gem 'github-pages (= 67)' in any of the gem sources listed in your Gemfile or available on this machine. (Bundler::GemNotFound)

Then it means GitHub has upgraded their github-pages gem version, so just run bundle install from the root directory to upgrade to the latest set of deps GitHub is using.

hansardalerts's Issues

Email alert legal requirements

What are we legally required to include in the email?

• Disclaimer?
• Unsubscribe link?
• Anything else?

Resources on Services, Factories, and Providers in Angular

http://blog.xebia.com/2013/09/01/differences-between-providers-in-angularjs/

Implement a config file outside of Git-land

There are better ways of doing this, but I couldn't get UWSGI and NGINX to pass the envvar on.
See http://stackoverflow.com/a/15854231

Refactor the initial data load

Bad: Loading Your Initial Page View With AJAX Calls

Here's a common scenario with AngularJS: the user visits your page, and is greeted with a weird layout, that eventually resolves itself to what you intended. AngularJS has to do a large number of passes on your scopes to ensure that your models have "settled". So your visitor is confused, because the HTML seems to have rendered, wrongly, but then gets the AJAX data, re-runs your models, and everything updates to look fine.

Better: Ask Your Services To Talk To $window

You're already talking to your server, and know what you should get, because you already had the user interaction (the page visit). What I do is I get my initial load data server side, and then pass into Angular by attaching it to the window object. Then in Angular, I have a service whose job it is to fetch that information from the window and provide it to my app in a dependency injectable way. Because $window is injectable, I can then test by attaching whatever input data I want.

From http://miceplans.net/node/36

How to structure a Flask + AngularJS application

http://stackoverflow.com/questions/11522151/typical-angular-js-workflow-and-project-structure-with-python-flask

See also: https://github.com/angular/angular-seed/tree/master/app/js

User sign-up/sign-in process

New User:

• The first field in the form should be an email address field linked to Personas

Existing Logged in User:

• Display logged in status at the top of the page

Existing User, not logged in:

• The first field in the form should be an email address field linked to Personas
  Q. Can/should we auto-populate it?
  Q. Is the different behaviour of the field confusing (register vs login again)
  Q. Is not making the registration process explicit a problem? ("I just entered my email address here - it doesn't look like I've registered yet!")

Regardless, the top bar of the page should have Login/Register/Logged In buttons.

Learn about Bower

All of the hipsters JavaScript kids seem to be using it to distribute their packages these days. Would make installing (and presumably updating and uninstalling?) easier.

Scraper parser job, interested?

Try to use AngularJS routing to separate intro from the app

Alert management process

Depends on issue #9.

Users can see all of their current alerts on the index page. The table might be rendered with ngTable.

• Search text
• Leg. Assembly
• Leg. Council
• Status (Off/On)
• Creation date - Do they care?
• {Enable|Disable}/Delete/Edit buttons

{Enable|Disable}:

• Display confirmation dialog? Who cares?
• PUT to /api/alerts/{id}/{enable|disable}
• Change status in Angular-land, hopefully magic data binding updates the table
• Display confirmation of action completion - row colour fades to default? Toastr?

Delete:

• Display confirmation dialog
• DELETE to /api/alerts/{id}
• Flag as deleted in DB
• Remove from data in Angular-land
• Display confirmation of action completion - whatever we did for alert creation (Alerts / Toastr)

Edit:

• In-table edit vs modal edit. Whatever ngTable works nicest with (to start with, at least)
• Edit button should become 'submit'-esque button
• PUT to /api/alerts/{id}
• Either return confirmation from API or let angular re-request from GET /api/alerts/{id} and update magically.
• Display confirmation of action completion - whatever we did for alert creation (Alerts / Toastr)

Alert creation process

Depends on issue #8.

User is presented with a form:

• Checkboxes for Leg. Assembly and Leg. Council
• Search terms box - including some explanatory text around adv. searching abilities and placeholder text
• Create alert button.

Create Alert:

• Validation (in Angular-land)
• Validation (in Python-land)
• Create alert in DB at /api/alert/create POST
• Return either alert_id (and have Angular re-request alert info)
• .push() to alerts list in Angular-land and have it update the UI
• Display temporary UI acknowledgement of creation (Bootstrap Alert / Toastr)
• Reset alert creation form

Cleanup experiments

e.g. database.py is unused now, I think.

A Vagrantfile to setup the dev machine

Admin interface

The Admin interface should allow

• View all users
• Edit user information (Though we may not store anything worth editing)
• View all alerts
• View all alerts for a given user
• Edit an alert (e.g. manually turn it off)

Implement better API exception handling

http://flask.pocoo.org/docs/patterns/apierrors/

@app.errorhandler(InvalidUsage)
def handle_invalid_usage(error):
    response = jsonify(error.to_dict())
    response.status_code = error.status_code
    return response

/api/current_transcripts should have some caching

How to wait for a promise in a run block in Angular

http://stackoverflow.com/questions/21697598/how-to-wait-for-a-promise-in-a-run-block-in-angular

tl;dr Bootstrap manually

Resources on "How to think Angular"

http://stackoverflow.com/questions/14994391/how-do-i-think-in-angularjs-if-i-have-a-jquery-background?rq=1

http://stackoverflow.com/questions/14333857/how-to-master-angularjs?rq=1

Final graphics

• Finalised logo
• Finalised header image w/ "Hansard Alerts" and a tagline
• A favicon

Finalise design

The current is just default Bootstrap to get the backend working and UI stuff ironed out.

Check out ng-boilerplate

http://joshdmiller.github.io/ng-boilerplate/#/home

Decide on hosting arrangements and domain name

govtoolkit.org/hansardalerts
hansardalerts.org
et cetera

Is HansardAlerts the final name?

Alert errors mails

The alerts system should send automated error emails in case of something going awry:

e.g.

• Any exceptions
• Any unexpected responses from the Hansard searcher
• Any failures from the mailer API

Links back to Hansard?

Where and how should we link back to Hansard and provide due credit to the Parliament folks for making the backend possible?

Work out why the alerts list isn't being re-rendered by Angular

Using broadcast successfully (via http://stackoverflow.com/questions/20181323/passing-data-between-controllers-in-angular-js)

Events seem to be picked up in the controller OK, but it's not re-rendering.

Maybe stop and use http://bazalt-cms.com/ng-table/example/1 at this point?

Angular-Bootstrap-Switch

Should probably use one of these plugins instead:

https://github.com/frapontillo/angular-bootstrap-switch

https://github.com/JumpLink/angular-toggle-switch

Introductory text

We'll need a brief bit of text explaining what it is, where it came from (inspired by OpenAustralia's thing), and some detail around when on sitting fays you can expect alerts to arrive (based on the info on Parliament's website).

About page

We need text for an about page.

Reuse it to fill in metatags in cover-layout.html

What should the Twitter account do?

Should it be regularly tweeting things to maintain interest and get RTs?

Or is it just an avenue for support and occasional promotional tweets?

Conver float-label to an Angular directive

Add spinny form button back in using proper Angular

i.e. No DOM manipulation

Reconcile app.py vs __init__.py

Looks like I got halfway to refactoring it and got distracted by something. At the moment they're both doing much the same thing.

It's based on one of the published Flask patterns from...somewhere.

Social media integration in alert emails

Should alert emails have any social media integration?

e.g. Twitter links next to each alert that tweet "{search term} {section of Hansard} {members mentioned} #ourhashtag {link or @HansardAlerts)"

The SQLite database should be backed up automatically

Resources on using RESTful APIs in Angular

https://github.com/mgonto/restangular

http://www.masnun.com/2013/08/28/rest-access-in-angularjs-using-ngresource.html

http://draptik.github.io/blog/2013/07/28/restful-crud-with-angularjs/

When v1 is out, read the Angular Best Practice series

http://www.artandlogic.com/blog/2013/05/ive-been-doing-it-wrong-part-1-of-3/

Log viewer

The alerts system should log some useful information and this should be made available via a web interface.

Welcome email

We need some text and a design for a "Welcome to HansardAlerts" email. To include account details (email, name {if we collect that}), a big fat "Create Alerts" button, and prods toward the Twitter account and website as well as legal requirements in the footer.

Can we grab the user's avatar from Personas?

It'd add a touch of personalisation.

See also http://blog.miguelgrinberg.com/post/the-flask-mega-tutorial-part-vi-profile-page-and-avatars