Git Product home page Git Product logo

legislation-explorer's Introduction

OpenFisca Legislation explorer

A web user interface to explore an OpenFisca tax and benefit system.

This application consumes a legislation description made available by the OpenFisca web API and makes its parameters and formulas searchable and interlinked. Example.

Development stack

This application is based on Node on the backend and React on the frontend.

In order to run the server or to improve the app, first install Node and NPM and Git. Then, run the following commands:

git clone https://github.com/openfisca/legislation-explorer.git
cd legislation-explorer
npm install --production

Configure your instance

You will need to tell the Legislation Explorer server where your OpenFisca API instance can be reached, as well as where your repository resides for contributors to be directed to. This is all done through environment variables, allowing you to use the same code for any instance by injecting these elements at runtime.

To set these options, you need to define them by prefixing the npm start or npm run dev commands with their definitions, in the $NAME=$VALUE syntax.

  • API_URL: the URL at which your OpenFisca API root endpoint can be found. For example: https://openfisca-aotearoa.herokuapp.com. Defaults to http://0.0.0.0:5000.
  • CHANGELOG_URL: the URL at which the changelog for the country package can be found. Used on 404 pages. For example: https://github.com/openfisca/openfisca-tunisia/blob/master/CHANGELOG.md.

If it gets lengthy or you want to persist these values, you can also use a .env file. Such a file is a plaintext file with name .env stored in the root directory of your legislation explorer instance (i.e. next to the package.json file). List all of your environment variables in the $NAME=$VALUE syntax, one per line. If you have trouble writing this file, read the parsing rules. An example file is provided as .env.example, setting default values. You can copy it, but changing it won't have any impact: only a file named .env will be taken into account. You should not commit this file: it depends on each instance.

Localisation (l12n / i18n)

The user interface of the legislation explorer has full support for internationalisation. Supported languages can be found in the src/assets/lang directory, and can be added by simply creating a new file with the two-letter language code to add support for.

For localisation, you can override any of the strings defined in these files through the UI_STRINGS environment variable.

  • UI_STRINGS: overrides the ui config object through a JSON string. Example: UI_STRINGS='{"en":{"countryName":"Tunisia"},"fr":{"countryName":"Tunisie"}}' npm start.

The value is a JSON-encoded object whose keys are ISO two-letters language codes and values are strings, these values will take precedence over any strings defined in the lang folder.

The following strings are strongly recommended to be overridden:

  • countryName: The name of the tax and benefit system you are modelling here.
    • forCountry: In case the default interpolation for your countryName does not give good results, you can also edit the prefix added before the countryName value.
  • search_placeholder: One or two suggested searches, preferably comma-separated, for your users to make sense of the search field. Best results will be obtained by using the most well-known parameters for your tax and benefit system.

Analytics

This web app supports Matomo (ex-Piwik) analytics out of the box. To set it up, use the following environment variables:

  • MATOMO_URL: the base URL at which the Matomo instance can be reached. For example: MATOMO_URL=https://stats.data.gouv.fr MATOMO_SITE_ID=4 npm start. Only taken into account if used in conjunction with MATOMO_SITE_ID and if MATOMO_CONFIG is not defined.
  • MATOMO_SITE_ID: The ID of the site to track in this Matomo instance. For example: MATOMO_URL=https://stats.data.gouv.fr MATOMO_SITE_ID=4 npm start. Only taken into account if used in conjunction with MATOMO_URL and if MATOMO_CONFIG is not defined.
  • MATOMO_CONFIG: a JSON-encoded object describing how to contact your Matomo instance. The value is a configuration object for the piwik-react-router package (make sure to read its docs for the version specified in package.json). Defaults to not sending analytics at all. Example: 'MATOMO_CONFIG='{"url":"https://stats.data.gouv.fr","siteId":4}' npm start.

Server and public URL

  • PATHNAME defines the path at which the Legislation Explorer is served. Defaults to /. For example: PATHNAME=/legislation to serve on https://fr.openfisca.org/legislation.
  • HOST: defines the host on which the app is served. Example: HOST=192.168.1.1 npm start. Defaults to 0.0.0.0 (all local interfaces).
  • PORT defines the port on which the app is served. Example: PORT=80 npm start. Defaults to 2020.

Development-specific options

  • NODE_ENV defines if assets should be served minified or with hot module remplacement. Can be either development or production. Example: NODE_ENV=production PORT=2020 node index.js. Prefer using npm start.

Run the server

cd to the cloned legislation-explorer directory, and run the following commands:

npm run build  # compile the frontend code
npm start  # start the server

Improve the app

You can edit all files in the source folder you cloned. In order to ease development, a different set of commands will allow you to run the app with hot module replacement, which will reflect your changes almost instantly rather than rebuilding the whole package.

cd to the cloned legislation-explorer directory, and run the following commands:

npm install  # install development dependencies
npm run dev

Some additional commands can be useful for development. You can discover all of them by running npm run.

Tests

This app has both unit and integration tests. Its integration tests are implemented with Watai. You will first need to install its Selenium WebDriver dependencies to run these tests.

Then, build the app, run the server, run a Selenium instance and, in another Terminal, run:

npm run test

Deploy to production

See the dedicated guide.

legislation-explorer's People

Contributors

anna-livia avatar cbenz avatar dependabot-preview[bot] avatar dependabot-support avatar dependabot[bot] avatar edarin avatar fpagnoux avatar laem avatar mattisg avatar morendil avatar pnbt avatar sandcha avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

legislation-explorer's Issues

Track pageviews

As a product manager,
I can track pageviews on the legislation explorer,
To follow the efficiency of the search feature

Explain update procedure on 404 pages

As a user trying to access an obsolete variable,
I get information about the fact that it could have been removed and what to do about it,
So that I don't believe there is an error with the software

Add links to documentation

  • Link “En savoir plus” main link to doc.openfisca.fr.

For variables:

  • Link Entity types to Entities documentation page.
  • Link periods to Periods documentation page.
  • Link Variable to Variables documentation page.

Display the source version of the data

As a user,
I can know which version of the source legislation is used to present the variables,
So that I don't waste time looking at obsolete information

Display scale parameters in legislation explorer

Right now they have been deactivated

UI needs to be discussed.

Propositions :

  • Select field to choose the date (with all the dates where the law has changed)
  • Slider to choose the date
  • Date picker
  • All values displayed in collapsable blocks
  • A graphical plot

Improve search results ordering

The current ordering is only alphabetical.

There should be a sorting algorithm that priories matches according to the position of the match in the variable name (the earlier the better).

Redesign home page

  • Add the logo.
  • Integrate source version under the logo.
  • Count total visible formulas & parameters as a description of the system: OpenFisca référence {{ count }} formules et {{ count }} paramètres qui modélisent le système socio-fiscal français..
  • Remove breadcrumbs bar.
  • Remove the graph link.
  • Remove the nav bar.
  • Increase readability of list items: title is variable name, description is its label.
  • Make everything bigger.
  • Remove direct links to GitHub.

Improve search box in Graph view

Two main concerns:

  • wrong search on the name (class) of the variable. Exemple: Prime pour l'activité find ppa but ppa doesn't succeed to find ppa
  • Displaying the results of the search should be enhanced (larger display zone) to avoid horizonthal scroll bar as much as possible

This issue was randomly assigned. Feel free to change those ;-)

Ease research iteration

Replace “Back to home” button in the detailed view of a variable with a “Back” button that saves my search.

Broken source code links

Links displayed in both web pages and JSON data point to the wrong place, example:

{
defaultValue: 0,
definitionPeriod: "MONTH",
description: "SMIC proratisé (mensuel)",
entity: "individu",
formulas: {
0001-01-01: {
content: "def function(self, simulation, period): coefficient_proratisation = simulation.calculate('coefficient_proratisation', period) smic_horaire_brut = simulation.legislation_at(period.start).cotsoc.gen.smic_h_b smic_proratise = coefficient_proratisation * smic_horaire_brut * 35 * 52 / 12 return smic_proratise ",
source: "https://github.com/openfisca/openfisca-france/blob/18.2.0ckages/openfisca_france/model/prelevements_obligatoires/prelevements_sociaux/cotisations_sociales/allegements.py#L296-L301"
}
},
id: "smic_proratise",
source: "https://github.com/openfisca/openfisca-france/blob/18.2.0ckages/openfisca_france/model/prelevements_obligatoires/prelevements_sociaux/cotisations_sociales/allegements.py#L290-L301",
valueType: "Float"
}

Show variables input elasticity

As an analyst,
I know if I can provide a variable value on a different period than its definition one and how the engine will expand it,
So that I don't get surprises when I request a computation


Parse, expose, show and document set_input values.

Remove uncomputed information

As a Producer,
I don't see a “Formules utilisant ce paramètre : aucunes” label in a parameter detailed view,
So that I am not misled thinking it is true while it's the consequence of a bug in the parsers

Add integration tests

Cover the legislation explorer with tests that prove:

  • The page loads and shows metadata on the loaded tax and benefit system.
  • The search does filter the list.
  • Navigating to an item of the list shows details.
  • Going back keeps the search.

Filter variables based on their label

As a reuser,
I can search for a term in the label of variables,
To identify a specific variable


Look for strict inclusion of the looked for substring in the variable name.

Extends #22.

Handle multiple words research

As a legislation explorer user typing "salaire base" in the search field,
I get the variable "salaire_de_base" in my results

Improve readability of variables

Design and implement a new view for variables.

  • Increase the description font size.
  • Update the sentence to (notice bold):

Cette variable s'applique aux entités individu / foyer fiscal / ménage / famille.
Elle a une période de définition d'un mois / d'un an / qui est l'éternité. Sa valeur est fixe dans le temps.
Sa valeur est un entier / un nombre décimal / une date (for unmapped types, default to showing them directly).
Sa valeur par défaut est 0 / 0.0 / 01/01/0001.

  • Add a source code link at the end of each formula with name “Modifier cette formule”.
  • Rename the source code link to “Modifier ces informations”.
  • For variables with no formula, remove title “Formule de calcul” and add the following text to its details:

Elle n'a pas de formule et n'est donc pas calculable. Elle ne peut qu'être fournie en entrée lors d'un calcul.

  • Localize all of the textual elements.
  • Remove the “external link” icons.

Index entities

As a producer,
I can search for an entity type in the legislation explorer,
So that I can get all necessary information to code formulas in a single place

Improve CTA discoverability

As an OpenFisca reuser,
I can understand the expected result of the search button,
So that I save a seconds on my first interactions


  • The “Trouver” button should be in a contrast color.
  • The “En savoir plus” button should be a link.
  • The logo should be smaller.

Add an international description

Include the following text, above the count of parameters and variables, with language depending on the browser language:

en

OpenFisca makes law computable. It is a free and open-source computation engine that allows modelling tax and benefit systems in a collaborative and transparent way. This software is used by researchers and public agencies.

fr

OpenFisca rend le droit calculable. Il s’agit d’un moteur de calcul libre et ouvert qui permet de modéliser le système socio-fiscal de manière collaborative et transparente. Ce logiciel est utilisé par des chercheurs en économie et des services publics.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.