18f / paid-leave-prototype

A proof of concept state paid family medical leave system

Paid Family & Medical Leave Prototype

This prototype was built by 18F, in partnership with the Department of Labor's Women's Bureau. Our goal was to provide a simple front-end, and some guidance on potential back-end structures, so that any jurisdiction with a Paid Family Medical Leave program can more easily create a website for it. The prototype is available now. Notable subsets of the prototype include a public-facing application process and a healthcare-provider patient-approval process.

Development

Development is in the 18f-pages branch.

Project Management

Feel free to open an issue if you'd like to request a feature. You can also look at our issues-tracking system on Trello.

Technical Approach

With a goal of constructing a modular, extensible, lightweight easily-customizable platform, this prototype employs several notable processes:

• The site is constructed in Jekyll.
• It is built entirely in JavaScript, to ensure that it can be hosted in any server environment.
• The application form is encoded as JSON Schema, with JSON Form used to dynamically generate the HTML for the form. (No form data is present within the application page's HTML—it is all rendered in-browser, via JavaScript.)
• Upon submission, form contents are submitted against the JSON Schema before being submitted to a RESTful endpoint (a server to be provided by the state implementing this prototype software).

Making changes to the form and validation process can be done by modifying the schema, with some particular HTML customizations possible via extensions to the schema in the form JSON. See the JSON Form documentation for specifics about this.

Because the form is generated from JSON, it would not be difficult to extend this prototype by adding a web-based form-building system, permitting customizations to the form without necessitating editing any JSON or HTML.

Local Development

This can be deployed locally with the following commands:

git clone https://github.com/18F/Paid-Leave-Prototype.git
gem install jekyll bundler accesslint-ci
jekyll serve --watch

Third Party Javascript Libraries

• jquery-2.1.4
• jsonform
• TV4- Tiny Validator for JSON Schema v4
• Tablesaw Js
• Underscore Js

Contributing

See CONTRIBUTING for additional information.

Public domain

This project is in the worldwide public domain. As stated in CONTRIBUTING:

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.

paid-leave-prototype's Issues

Identify the mechanism for toggling the display of form fields

Normally we'd just use some external JavaScript to accomplish this, but JSON Form has a hook for this, which I imagine is because it's problematic or impractical to attempt to make changes to the DOM when it's already been rendered by JSON Form. Figure out how to get this working (my efforts failed, because dropping JavaScript straight into JSON makes no sense).

Patterns in form fields are listed but not displaying on the resulting inputs

schema.json properites.patterns attributes are not rendering in the prototype.

Rewrite form.json to list all fields

Per #14, convert to a more verbose format.

Ensure that validation against JSON Schema is working

On submission, the form contents should be validated against JSON Schema, and any errors should be displayed in a user-friendly way. And when the form validates against the schema, it should be submitted to a specified endpoint (customized for each implementation, for the state's PFL system).

Resolve question of how best to encode form's structure

Per the discussion in #9, there's a fundamental conflict that I'm not sure of how to best resolve, and that's about how to represent the form structure and style it properly. JSON Form has a notable limitation: form JSON cannot be nested (at least, not much). This makes it challenging to break the form up into its constituent sections while also providing decent granularity for each of the fields in that section. We have three choices:

1. Represent each form section in form.json as "type": "fieldset" groups. That eliminates any JSON Form display options (e.g., rendering select fields as radio buttons), and necessitates using CSS to group together fields...if that's possible.
2. Do not include form sections in form.json, but instead represent each field, one by one, serially. Use a combination of CSS and form.json options (e.g., prepend, htmlClass) to group fields together. Challenge: including descriptive text / titles before or after form groupings.
3. See if using a different JSON Schema library, e.g. Alpaca, will make it possible to nest form elements. Switching wouldn't be particularly difficult at this point, since JSON Schema is JSON Schema.

Convert relevant select menus into radio buttons

There are two ways to do this (That I know of):

1. Use form.json to list every field, and set the fields in question to radio buttons.
2. Use onBeforeRender to convert the fields to use radio buttons. (Associated risk: flash of unstyled content.)

Add the contextual help text

Right now, we're using the help field in form.json to title each section. Instead, do this:

• change these help fields to title (or something like that) fields, creating a custom field type to do so
• change the .help-block class name in the CSS to instead apply to the new field class
• add the actual help text throughout form.json (e.g., "Birth certificate, certificate of adoption, marriage license, or other documentary material" for the "Documentation of Relationship" field)
• create new .help-block CSS to style this help text properly

Wire up the submit button

Within JSON Form's structure, make sure that the submit button is properly wired up to:

• validate the input against the schema
• display errors if there are any
• submit to an endpoint

Integrate USDOL Minimum Wage API

Now that USDOL's API provides minimum wage data, integrate that into the prototype.

Add transitions to the calculator

Right now, it just toggles the display of DIVs, which looks rough. Use a nicer jQuery transition.

File a Claim Text Location

Debating where "file a claim" should be. Right now we have two pages:
https://pages.18f.gov/Paid-Leave-Prototype/claims/
and
https://pages.18f.gov/Paid-Leave-Prototype/claims/new/

I wonder if "file a claim" should direct directly to the new claim file, and the "new claim" page also gives calling and download paper form info.
Just brainstorming.

Retrieve and display bank's name from the routing number

Use this delightful API to display the bank's name based on the entered routing number, so that applicants can verify for themselves that they have entered the correct number.

Add average claim processing time to the homepage.

Re-label Paid Family Leave to Paid Family-Medical Leave

As it says.
Pages to fix:
https://pages.18f.gov/Paid-Leave-Prototype/claims/new/

Add descriptions to form sections

Some form fields are supposed to have instructions or a description. Include these.

Add all countries to address select

But only countries legal trade with. e.g., North Korea would not make the cut. I'm not sure if there's a federal source of such a list.

Checklist for claimants

Do we want to create an eligibility checklist?
Here's an example of a government one: https://egov.eeoc.gov/eas/

Externalize estimator CSS

It's in the page body right now.

Simplify, merge form.css

Our form CSS right now contains many more rules than it needs to. Remove everything redundant, and figure out whether to combine it with the main site CSS file, or keep it as a separate file.

Add a file upload field for Documentation of Relationship

Right now it's just a text input field. JSON Schema has no concept of files. For this prototype, we need this to look like a file input. I suspect that this is best done via the onBeforeRender function. However we do it, the idea is just to replace the text input field (<input type="text" name="dependent.relationship.documentation">) with a file upload field (<input type="file" />.

Actually supporting this would probably involve using HTML5's file API, base64ing the file, and stuffing it into a string...but that presents its own challenges. Alternately, see how Alpaca does it.

Question: How do we think about modularity/adaptability in the code?

Three types of leave:
Family Leave
Medical Leave
TDI