udata-front 2.0.5.dev4192

udata customizations for data.gouv.fr

⚙️ Udata customizations for data.gouv.fr made by Etalab ⚙️

• Notes on this repo
• Compatibility
• Installation
• Theme development
  • 🚀 Getting started
    • 🐍 Python development
      • 🧱 Installing the python dependencies
      • 🚩 Starting the python development server
    • ☕ Javascript development
      • 🏗 Installing the javascript dependencies
      • 💪 Starting the javascript development server
    • 👀 Other dev commands
  • 🏰 General architecture
    • 🚜 Jinja2 templates
    • 🚲 Javascript
    • 🖼️ Style
  • 🛠️ Build tools
  • 🏭 Javascript architecture
    • 🏔️ Vue mounting
    • 👩‍🔬 Tests
• 📖 Read more

Notes on this repo

This is a new version of udata-gouvfr This is a udata extension, you should read the udata documentation first.

Compatibility

udata-front requires Python 3.7+ and udata.

Installation

Install udata.

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

pip install udata-front

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 = ['front']
THEME = 'gouvfr'

Theme development

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.

🚀 Getting started

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.cfg

Modify your local udata.cfg configuration file as following:

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

🐍 Python development

🧱 Installing the python dependencies

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.pip

NB: the udata.(in|pip) files are used by the CI to stay in sync with udata requirements. 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.

🚩 Starting the python development server

Simply run the udata project with udata-front loaded as a plugin:

cd udata
inv serve

☕ Javascript development

🏗 Installing the javascript dependencies

First, you need to use Node (version 14+) on your platform. You should consider installing NVM which uses the existing .nvmrc.

cd udata-front

nvm install
nvm use

npm install

And voilà ! ✨

💪 Starting the javascript development server

Simply run this command in the project directory :

npm start

This will start a development server that will listen to changes and automatically rebuild the project when needed. Note that a webserver is started by Parcel (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.

👀 Other dev commands

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 -l

Example commands:

• i18n: Extract translatable strings
• i18nc: Compile translations
• qa: Run a quality report
• test: Run tests suite

Additionally, you can run javascript-related commands through npm run.

• build: Builds the final CSS/JS files and the UI-Kit Documentation. You should probably use this one in production.
• build:app: Builds the final CSS/JS files without the UI-Kit
• build:stylemark: Builds the UI-Kit files and also the CSS/JS files but unminifed (do not use those static files in production)
• i18n:report: Generates a report of the i18n missing and unused keys
• i18n:extract: Same as above, but also automatically adds missing keys to translation files
• clean: Cleans Parcel cache. Use this if you stumble upon weird bugs to start anew.
• start: Get to coding with live reload and things. Same as npm run dev
• test: Runs the Cypress tests. More on that in the Tests section of this README.

🏰 General architecture

🚜 Jinja2 templates

Because 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 a body block 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 a content block for our page's content, and wraps it around the header and footer.
• header.html and footer.html : standard header and footer block that will appear on each page
• home.html: the home page template (duh)

🚲 Javascript

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.

🖼️ Style

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/ and is built using Stylemark, you can read the live documentation in udata_front/theme/stylemark/ after building it using npm run build-stylemark.

You can access the UI-kit documentation by visiting the following route : /_stylemark/index.html

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.

🛠️ Build tools

This project uses Parcel 2 to build and transform our source files into nice bundles for browsers. Its config can be found in the .parcelrc file, as well as the package.json entries.

Parcel does multiple custom things in this project :

• Transform the .js files into modern Javascript for browsers
• Transform the less files into modern CSS using PostCSS
• Bundle the svg used in the JS files
• Copy the static assets when they change (config is in the package.json's staticFiles key)
• Build the Stylemark (UI-kit) documentation on file change

🏭 Javascript architecture

🏔️ Vue mounting

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.js) 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

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");
  });

Then, tests can be run using the following command :

npm run test

Cypress also comes with cypress-axe to allow for accessibility automated testing.

📖 Read more

Changelog

Current (in progress)

• Nothing yet

2.0.4 (2022-06-09)

• Add accessibility compliance status in footer #114
• Fix SVG display issue #116

2.0.3 (2022-06-03)

• Update search pages #95
• Add support for HTML in posts #106
• Fix RGAA criterion 1.1 #104
• Fix RGAA criterion 10.4 #103
• Add geographical page on home venti button #109
• Fix RGAA criterion 11.10 #102
• Update DSFR to 1.5.1 #107
  • :warning: SVG in JS must use bundle-text: prefix now
• Add new menu items #113

2.0.2 (2022-04-11)

• Add harvest catalog view #100
• Add elections on home venti button #101

2.0.1 (2022-04-05)

• Add support for HTML static pages and more DSFR components #96
• Fix mobile bugs after header changes #99
• Fix organizationCertified error when organization is null #98

2.0.0 (2022-03-30)

Breaking change

• :warning: Use refactored search endpoints from udata #60

1.2.5 (2022-03-29)

• Add a transport banner hook #94
• Add button on organization page to see all of its datasets #93
• Format home page numbers #90
• Let browsers decide what cursor to use #89
• Replace see more button on home page with link #91
• Replace Suggest with accessible combobox #88

1.2.4 (2022-03-01)

• Deprecation: Topics are now deprecated and will be removed in upcoming releases.
• Fix <read-more> component height when it contains <img> #65 #85
• Add featured button component back for sysadmin #79
• Update reuse style #52 #81
• Add banner to broken user page #76
• :warning: Button changes #75
  • Remove underline from button hover
  • .btn, .btn-secondary and .btn-secondary are removed. Use DSFR and .fr-btn--secondary-{color} instead.
  • .tags and .tag are removed. Use DSFR ones instead.
  • .dropdown is removed. Use DSFR select instead.
• Fix duplicate request on dataset search #70 86
• Add banner for harvested dataset #73
• Change github footer link to the tickets repository #80
• Remove banner for the new search beta on datasets search page #83
• Fix RGAA criterion 7.3 #82
• Use avatar_url for owner #84
• Update resources style #78

1.2.3 (2022-01-27)

• Fix modals not working #71
• Fix auth messages not shown from query parameter #68
• Fix RGAA criterion 10.14 #72
• Fix thread header wrapped when title is too long #64

1.2.2 (2022-01-21)

• Fix latest modification date for dataset and resources on dataset page #62
• Fix hidden datasets shown on Home and Reuses #67
• Add temporal coverage back to dataset page #63
• :warning: @bg-beige is remove, use @background-contrast-grey instead
• Update colors to fix accessibility issues #56
• Fix missing checkbox using DSFR checkboxes #69

1.2.1 (2022-01-11)

• Change urls in Participate banner to relevant etalab guides #53
• Add topic information on reuse metadata and add a filter by topic on reuse search page #50
• Update DSFR to v1.2.1 #45
• :warning: .btn-tab is removed, use .fr-tag instead 57

1.2.0 (2021-12-10)

• Add a banner for the new search beta on datasets search page #43
• :warning: Remove Issues logic in accordance with udata #42
• :warning: @grey-100 is now #e5e5e5
• Standardize organization page similar to dataset and reuse pages #40
• Fix RGAA criterion 10.7 Each element focusable has a visible focus #46
• Fix Stylemark generation to include JS files and properly include other assets #33
• Redirect about page to "ressources" page in menu #48
• Standardize article discussions and quick fixes to discussions #41 #51
• Fix error on search request cancelation #44

1.1.2 (2021-11-23)

• Standardize reuse page similar to dataset page navigation quickfixes #31
• Move template hook logic to udata and add oauth hooks #29
• Add resources pagination dataset page and use DSFR pagination #30 #37
• Style oauth page #34
• Fix horizontal scroll on mobile #38
• Fix gouvfr static path #39

1.1.1 (2021-10-22)

• Update README to reflect front changes #17
• Add Participate banner in the footer #24
• Fix min-height used in posts images to center them #23
• Update dataset page with navigation quickfixes and add DSFR components #18
• Implement feedbacks on quickfixes #26

1.1.0 (2021-10-12)

• Add Cypress front-end tests stub #9
• Add read only mode back on frontend #10
• Fix RGAA criterion 1.2 Each decorative image is ignored by assistive technologies. #13
• Add a request membership action on organization page #12
• Unset vue delimiters used in html templates to prevent injections #11
• Fix temporal coverage order in search results metadata #14
• VueJS multiple mount points with a global event bus #15 #19
• Fix RGAA criterion 12.6 Block of contents from multiple pages can be reached or skipped #21

1.0.0 (2021-09-16)

• :warning: breaking change: Package renaming and new repository #1:
  • udata-gouvfr is now udata-front
• Update feedparser following setuptools 58.0.2 release that drops support for use_2to3 #6
• Show correct number of latest reuses on homepage #3
• Fix next value on login to prevent infinite loop #4 #8

Previous udata-gouvfr changelog

If you're migrating from udata-gouvfr, see previous changelog here