udata-gouvfr

udata customizations for Etalab / Data.gouv.fr.

Note: This is a udata extension, you should read the udata documentation first.

Compatibility

udata-gouvfr requires Python 3.7+ and udata.

Installation

Install udata.

Remain in the same Python virtual environment and install udata-gouvfr:

pip install udata-gouvfr

Create a local configuration file udata.cfg in your udata directory (or where your UDATA_SETTINGS point out) or modify an existing one as following:

PLUGINS = ['gouvfr']
THEME = 'gouvfr'

Development

Prepare a udata development environment.

It is recommended to have a workspace with the following layout:

$WORKSPACE
├── fs
├── udata
│   ├── ...
│   └── setup.py
├── udata-gouvfr
│   ├── ...
│   └── setup.py
└── udata.cfg

The following steps use the same Python virtual environment and the same version of npm (for JS) as udata.

Clone the udata-gouvfr repository into your workspace and install it in development mode:

git clone https://github.com/etalab/udata-gouvfr.git
pip install -e udata-gouvfr

Modify your local udata.cfg configuration file as following:

PLUGINS = ['gouvfr']
THEME = 'gouvfr'

You can execute udata-gouvfr specific tasks from the udata-gouvfr directory.

ex: Build the assets:

cd udata-gouvfr
npm install
inv assets-build

You can list available development commands with:

inv -l

Theme

The front-end theme for the public facing website, is split into two parts :

The Jinja templates are located inside udata_gouvfr/theme/templates.
The Less & other sourcefiles for the are located in theme.

In addition we have a nice litle set of CSS Utilities to quickly build front end components, inspired by bootstrap, most of its documentation lives in the css located in theme/less/ and is built using Stylemark, you can read the live documentation in udata_gouvfr/theme/stylemark/ after building it using npm run build-stylemark.

When building pages, here are a few templates to look out for in udata_gouvfr/theme/templates :

home.html : well, duh.
header.html and footer.html : same idea.
raw.html : contains the general html structure exposing a body block where we can write our page's body.
base.html : contains some extra html structure exposing a content block for our page's content.
subnav-large.html, publish-action-modal.html and carousel.html : TODO

Here are our reusable components :

dataset : datasets listings used in many pages.
reuse : cards for displaying dataset reused in the real world.
participez : is the large blue callout seen on multiple pages.
macros : TODO
svg : contains SVG assets to be included in our pages.

TODO

Front docs todo :

Parcel 2 architecture
- Static copy
- Stylemark build
- VueJS compiler mode
VanillaJS IIFE architecture
Vue 3 architecture
- Modals
- I18n
- Config plugin
- Components Back docs todo :
CSS/JS file inclusion
Static route for UI-Kit

Whenever a components needs some special styling, you can find their corresponding definitions inside theme/less/specific/<component>, it's best if we can avoid having too much specific styling, but sometimes you just really need it.

Finally, we have a bunch of commands to make your life a tad easier, that you can run through npm run.