Add a front-end to udata
- Notes on this repo
- Compatibility
- Installation
- Theme development
- 📖 Read more
This is a new version of udata-gouvfr This is a udata extension, you should read the udata documentation first.
udata-front requires Python 3.7+ and udata.
Install udata.
Remain in the same Python virtual environment and install udata-front:
pip install udata-frontCreate 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 = ['front']
THEME = 'gouvfr'The front-end theme for the public facing website, is split into two parts :
- The Jinja templates are located inside
udata_front/theme/gouvfr/templates. - The Less, Vue & other sourcefiles for the front-end are located in
theme.
Before you start your developper journey, you have to setup your python and/or javascript development tools.
It is recommended to have a workspace with the following layout:
$WORKSPACE
├── fs
├── udata
│ ├── ...
│ └── setup.py
├── udata-front
│ ├── ...
│ └── setup.py
└── udata.cfgModify your local udata.cfg configuration file as following:
PLUGINS = ['front']
THEME = 'gouvfr'Prepare a udata development environment.
Note that we're using pip-tools on this repository too.
The following steps use the same Python virtual environment as udata.
Install udata-front in development mode:
cd udata-front
pre-commit install
pip install -e . -r requirements/test.pip -r requirements/develop.pipNB: the
udata.(in|pip)files are used by the CI to stay in sync withudatarequirements. You shouldn't need to tinker with them on your local environment, but they might be updated by the CI when you make a Pull Request.
WARNING: if you experience requirements conflicts, and some dependencies were changed on udata, the
udata.pipmight need to be manually recompiled locally:
pip-compile requirements/udata.in --output-file=requirements/udata.pipSimply run the udata project with udata-front loaded as a plugin:
cd udata
inv serveFirst, you need to use Node (version 16+) on your platform. You should consider installing NVM which uses the existing .nvmrc.
cd udata-front
nvm install
nvm use
npm installAnd voilà ! ✨
If you want to work on Vue or Less files, you can start the storybook server with this command :
npm run storybookIt allows you to work on the front-end only and even mocks the back-end responses.
You can visit their website to learn more about storybook and how to use it.
Simply run this command in the project directory :
npm startThis will start a development server that will listen to changes and automatically rebuild the project when needed.
Note that a webserver is started by Vite (default port is 1234), however we will not be using it as our CSS and JS files will be served by Jinja instead. More on that later.
We are using our own package of components. Their sources are in this repository in udata_front/theme/gouvfr/datagouv-components. They are included in udata-front without any build or release required. They are also available on NPM for others to use.
Finally, we have a bunch of commands to make your life a tad easier.
You can execute udata-front specific tasks from the udata-front directory with invoke. You can list available development commands with:
inv -lExample commands:
i18n: Extract translatable stringsi18nc: Compile translationsqa: Run a quality reporttest: Run tests suite
Additionally, you can run javascript-related commands through npm run.
build: Builds the final CSS/JS files. You should probably use this one in production.i18n:report: Generates a report of the i18n missing and unused keysi18n:extract: Same as above, but also automatically adds missing keys to translation filesstart: Get to coding with live reload and things. Same asnpm run devtest: Runs the Cypress tests. More on that in the Tests section of this README.
If you encounter any merge conflict with your package-lock.json, you can fix it with NPM:
npm install --package-lock-onlyBecause udata is written in Python, its templating engine is Jinja 2.
This means that the HTML received by clients is built at runtime, for each request, using templates with {% block %} tags and includes.
Those template are responsible for building the pages using layouts and blocks. Here are a few to get started (in udata_front/theme/gouvfr/templates), from less specific to more specific :
raw.html: contains the general html structure exposing abodyblock where we can write our page's body. This template is also responsible for including the CSS and JS files.base.html: contains some extra html structure exposing acontentblock for our page's content, and wraps it around the header and footer.header.htmlandfooter.html: standard header and footer block that will appear on each pagehome.html: the home page template (duh)
In order to add some interactivity to the project, we are using Vue 3 and some good old VanillaJS.
The JS assets are compiled in a single index.js file that includes everything for every page. If the bundle size starts to grow a little bit too much, you might need to think about splitting it into separate files for each page.
We are using the DSFR to build our front-end components.
In addition we have a nice litle set of CSS Utilities to quickly build custom components, inspired by bootstrap, most of its documentation
lives in the css located in theme/less/.
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.
This project uses Vite to build and transform our source files into nice bundles for browsers.
Its config can be found in the vite.config.ts file.
Vile does multiple custom things in this project :
- Transform the
.tsfiles into modern Javascript for browsers - Transform the
lessfiles into modern CSS usingPostCSS - Copy the static assets when they change (config is in the
vite.config.ts)
Vite uses udata_front.egg-info/PKG-INFO version to name files and udata-front uses its version to load the correct one.
If you're udata-front version doesn't match the one loaded in the theme, you may have to do a pip install -e . to update the package information.
We are using the full build of VueJS that includes the compiler in order to compile templates directly in the browser.
There is a single VueJS app (in index.ts) that contains every component and plugins.
However, this app is mounted multiple times, on each DOM node containing a vuejs class.
This allows us to mount the app only where it's needed, because each subsequent mount is more DOM to compile and thus has an impact on performance. Moreover, mounting to the smallest possible HTML allows us to prevent accidental XSS vulnerability by forbidding users to compile their content with the Vue engine.
In order to allow inter-component communication, a global event bus is available in the global app, under the $bus variable.
You can emit events by using $bus.emit('event') and components can listen to events by using $bus.on('event').
Tests are run in a headless browser using Cypress. Test definitions are located in the cypress/integration directory.
Writing tests is very easy thanks to its syntax :
it("Displays the page title", () => {
cy.get("h1").should("be.visible");
});To run the Cypress tests, you need a few things:
- A
cypress/udata-front-e2e.cfgfile:
cp cypress/udata-front-e2e.cfg.example cypress/udata-front-e2e.cfg- Some loaded fixtures needed by the end-to-end tests:
npm run prepare-e2e- A local webserver: in another terminal (still in the same Python virtual environment), run the following command in the same Python virtual environment as
udata:
npm run serve-e2eThen, tests can be run using the following command:
npm run testCypress also comes with cypress-axe to allow for accessibility automated testing.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent