Front-end development in Invenio
The following topics cover front-end development in Invenio Framework repository applications. It provides a comprehensive overview of how to build and maintain the front-end components of an Invenio-based repository, covering everything from setting up your environment developing and integrating custom pages and UI components into a repository site.
Invenio is based on the Flask Python micro framework and as such, it inherits and builds on much of front-end ecosystem from it.
Intended audience
This guide is intended both for developers that needs to develop new features for their own NRP repository instance and core NRP developers or anyone wanting to contribute to the project's front-end ecosystem.
Frontend Architecture Overview
Our repositories follow a hybrid frontend architecture:
- Record Detail Pages: Built primarily with Jinja/JinjaX templates for server-side rendering
- Interactive UI Components: Implemented with React for rich, dynamic user experiences
- Simple interactive elements: Can be implemented with JQuery
This approach leverages the strengths of both technologies: server-rendered content for faster initial page loads and SEO benefits, combined with React's component-based architecture for complex interactive elements.
Jinja/JinjaX for Record Detail Pages
Record detail pages are primarily rendered using Jinja/JinjaX templates. These templates:
- Are processed on the server side
- Receive data directly from the backend
- Generate HTML that is sent to the browser
- Provide excellent SEO capabilities
- Enable fast initial page loads
React for Interactive UI Components
Most of our application's interactive UI is built with React, including:
- Search interfaces
- Form components
- Dashboard widgets
- Interactive data visualizations
When to Use Which Technology
| Use Case | Technology | Reasoning |
|---|---|---|
| Detail pages with static content | Jinja/JinjaX | SEO, fast initial load |
| Complex interactive elements | React | Component reuse, state management |
| Forms | React | Validation, dynamic fields |
| Data visualization | React | Interactive charts, responsive displays |
Design system
Our repositories are based on the Semantic UI design system. This means that all of the components that we use and also those that are coming from Invenio eco system are also using Semantic UI. It is technically possible to use another design system, but it would require much more effort in terms of UI development, therefore we recommend sticking with Semantic UI. Also all of the UI that your app is getting from our/Invenio source code will be in Semantic UI, therefore, it will be difficult to achieve same look and feel accross the app if you use different design system.
Semantic UI React is the official React integration for Semantic UI, available at https://react.semantic-ui.com/ (opens in a new tab). For the static pages, you can use documentation of "regular" Semantic UI: https://semantic-ui.com/ (opens in a new tab)
UI directory Structure
In our repositories, the UI section is organized as follows:
ui/model-name
├── semantic-ui
│ ├── js
│ └── model-name
│ ├── forms
│ │ ├── index.js
│ │ ├── FormActionsContainer.jsx
│ │ └── FormFieldsContainer.jsx
│ └── search
│ ├── index.js
│ ├── ResultsGridItem.jsx
│ └── ResultsListItem.jsx
├── templates
│ └── semantic-ui
│ └── model-name
│ ├── Deposit.jinja
│ ├── Detail.jinja
│ ├── Main.jinja
│ ├── Search.jinja
│ └── Sidebar.jinja
└── webpack.py
Note that you can have many folders under UI, and each one will have a similar structure. For example, you will also have components folder that contains less components.
The most important thing to note is that here you have your jinjax templates for the detail, search and form pages and your javascript files. Plus the webpack.py file, which is very important as it serves to add new javascript entry points, javascript aliases and javascript dependencies to your project. It is basically a way to create your npm project via python.
Real example of UI folder for a project with model named documents:
Table of Contents
Getting Started
Set up your development environment and start working on an Invenio site UI.
UI Resource views
UI Resource classes are Python classes tied to route views, responsible for fetching data from database and rendering it through Jinja templates, ensuring a separation between backend logic and UI presentation.
Jinja templating
Learn how to use Jinja for server-side rendered pages, including template inheritance, blocks, variables and more.
JinjaX: Componentize Jinja Macros
When there's a need for complex reusable template chunks, Jinja macros can quickly get messy. JinjaX tries to solve this by providing React-like UI components to Jinja templates.
Embedding React Widgets and applications
Integrate React components and applications into your templates to add interactivity and dynamic content to your pages.
Asset Management
Manage and optimize your repository project’s assets using Invenio Webpack integration.
Customization and Theming
Internationalization (i18n)
Support multiple languages by translating templates and components, and managing locale-specific assets.
Testing and Debugging
Test and debug your front-end code with unit-tests for Jinja and React, ensuring a robust application and predictable behavior.
Advanced Topics
- Performance Optimization (TODO:)
- Improving front-end performance
- Lazy loading and code splitting in React
- Caching strategies for static assets
- SEO Considerations (TODO:)
- Enhancing search engine optimization for pages
- Best practices for metadata and schema.org markup
- Security Best Practices (TODO:)
- Securing front-end code
- Preventing XSS attacks in Jinja and React
- Content Security Policy (CSP) considerations
- Form validation (TODO:)
Contributing to the Front-End Codebase
- Contribution Guidelines
- How to contribute to NRP Invenio core front-end (TODO:)
- Code review process (TODO:)
- Writing and maintaining documentation (TODO:)