1. Introduction
Project Overview
The React-Nuxeo Integration project is a robust solution aimed at simplifying the process of creating custom Nuxeo
add-ons that seamlessly integrate with React applications. This documentation serves as a comprehensive guide to
understanding and working with this integration.
Nuxeo is a powerful and extensible platform for content management and document management. With the React-Nuxeo
Integration, you can harness Nuxeo’s capabilities within your React-based projects, making it easier than ever to manage
and manipulate documents, content, and metadata.
Project Goal
The primary objective of this project is to enable developers to create Nuxeo add-ons that enhance the document
management experience by providing a user-friendly and highly customizable React front end. By combining the strengths
of Nuxeo with the flexibility of React, users can:
– Effectively manage content and documents.
– Streamline the organization and retrieval of valuable information.
– Build intuitive interfaces to interact with Nuxeo’s robust features.
This documentation will guide you through the installation process, usage examples, API documentation, and various
customization options to help you make the most of the React-Nuxeo Integration.
Let’s get started by understanding how to install and set up the integration for your projects.
2. Installation
Before you begin, ensure you have **YARN** and **NODE** installed on your system.
Installing the React UI Nuxeo Add-On
1. **React UI sources**: The React UI sources are located in `./maretha-react-webui/src/main/web-app`.
2. Gulp will copy the ‘src/main/web-app/dist’ build to ‘src/main/resources/web/nuxeo.war/app’, and “/app” will be
included in the Nuxeo library add-on.
3. After installing the add-on into the Nuxeo server, you can access the app under `/{NUXEO_CONTEXT}/app`.
System Requirements
Make sure your system meets the following requirements:
– **Node.js**: Ensure that you have Node.js installed on your system. You can download Node.js
from [nodejs.org](https://nodejs.org/).
– **Yarn**: We recommend using Yarn for managing project dependencies. You can install Yarn
from [yarnpkg.com](https://classic.yarnpkg.com/).
Installation Steps
To set up the React UI Nuxeo Add-On, follow these steps:
1. **Clone the Project**: If you haven’t already, clone the project to your local machine:
“`bash
git clone https://github.com/maretha-io/maretha-react-webui-sample-project.git
2. **Navigate to the Project Directory**: Go to the project directory:
“`bash
cd maretha-react-webui
3. **Install Dependencies**: Execute the following command to install the project dependencies using Yarn:
“`bash
yarn install
Build
To build the Nuxeo add-on, follow these steps:
1. Run the following Maven command to build the Nuxeo add-on zip package into ./maretha-react-webui-package/target:
“`bash
mvn clean package
2. From ./maretha-react-webui/src/main/web-app you may build the UI with gulp after ‘yarn build’, and the resulting app will be in ./maretha-react-webui-package/src/main/resources/web/nuxeo.war/app/.
Dependencies
To work on this project, you’ll need the following dependencies:
– **Node**: Version 16.19.0 is required. Please note that newer versions are not supported due to [specific compatibility issues](https://github.com/nodejs/node/issues/46167#issuecomment-1379121059).
– **Yarn**: Version 3.3.1 is the recommended package manager for this project. Yarn serves as a replacement for NPM and is used to manage project dependencies.
– **Gulp CLI**: The project relies on Gulp for build tasks. Gulp CLI version 2.3.0 is used for running these tasks.
– **Gulp**: Gulp version 4.0.2 is used to automate various build processes and streamline development workflows.
Tools/Frameworks/Libraries Used
This project leverages a range of tools, frameworks, libraries, and techniques to enhance its functionality and development process. Here are the key components used in the project:
– **Yarn**: Yarn serves as the project’s package manager, providing efficient dependency management and ensuring a smooth development experience.
– **React-i18next**: This library is used for internationalization, allowing the project to support multiple languages and translations seamlessly.
– **ViteJS**: ViteJS is the primary build tool used in the project. It offers fast and efficient development builds, making the development process more responsive.
– **Redux Toolkit**: Redux Toolkit is employed as an HTTP client library. It streamlines state management and data fetching, simplifying the integration of API-related actions and state into the project.
– **Material UI**: Material UI is the main UI library toolkit used in the project. It provides a comprehensive set of UI components, styles, and themes for consistent and aesthetically pleasing user interfaces.
– **Minimals**: Minimals is the base UI template used in the project, built over Material UI. It offers a clean and functional design foundation that enhances the overall user experience.
These tools, frameworks, and libraries contribute to the project’s efficiency, maintainability, and user-friendly interface, making it a robust and feature-rich application.
3. API Documentation
This section provides detailed information about the API endpoints and methods used in the React UI Nuxeo Add-On for communication with the Nuxeo server.
Communication with Nuxeo
In the ‘api’ folder of this project, the communication with the Nuxeo server is facilitated through the use of REST endpoints provided by Nuxeo. These endpoints allow the React UI Nuxeo Add-On to interact with the Nuxeo server for various operations, such as document management, search, auditing, and more.
Existing API Files
To maintain a structured and organized approach to communication with the Nuxeo server, the project includes dedicated API files for different functional domains. Each of these API files focuses on a specific aspect of interaction with the Nuxeo server.
middleware.ts
This file contains middleware definitions for communication with the Nuxeo server:
– **`apiMiddleware`**:
– `userAPI.middleware`
– `tasksApi.middleware`
– `searchApi.middleware`
– `documentApi.middleware`
– `auditApi.middleware`
reducers.ts
This file defines reducers for communication with the Nuxeo server:
– **`apiReducers`**:
– `[userAPI.reducerPath]`: Reducer for userAPI
– `[tasksApi.reducerPath]`: Reducer for tasksApi
– `[searchApi.reducerPath]`: Reducer for searchApi
– `[documentApi.reducerPath]`: Reducer for documentApi
– `[auditApi.reducerPath]`: Reducer for auditApi
baseQuery.ts
The `baseQuery` provides configuration for API requests:
– **`baseQuery`**:
– `baseUrl`: The base URL for Nuxeo server defined in `import.meta.env.VITE_NUXEO_CONTEXT_PATH`.
– Headers: Various headers for enrichers and fetch options.
document.ts
This file contains API endpoints for document-related operations:
– **`documentApi`**:
– `getDocumentByPath`: Get a document by path.
– `getDocumentById`: Get a document by ID.
– `getHistory`: Get the history of a document.
– `getCollectionSuggestions`: Get suggestions for collections.
– `putDocumentById`: Update a document by ID.
– `postDocument`: Create a new document.
– `deleteDocument`: Delete a document.
– `addToCollection`: Add a document to a collection.
– `deleteDocuments`: Delete multiple documents.
– `untrashDocument`: Restore a trashed document.
– `untrashDocuments`: Restore multiple trashed documents.
– `trashDocument`: Move a document to the trash.
– `removeFromCollection`: Remove a document from a collection.
– `trashDocuments`: Move multiple documents to the trash.
– `getBatchId`: Get a batch ID for file uploads.
– `getFavoriteDocument`: Get favorite documents.
– `addToFavorites`: Add a document to favorites.
– `removeFromFavorites`: Remove a document from favorites.
– `addComment`: Add a comment to a document.
– `startWorkflow`: Start a workflow on a document.
– `exportDocuments`: Export documents.
– `getComments`: Get comments for a document.
– `uploadFile`: Upload a file.
search.ts
This file contains API endpoints for search-related operations:
– **`searchApi`**:
– `searchPP`: Execute a search using provider and parameters.
– `usersSearch`: Search for users.
audit.ts
This file contains API endpoints for audit-related operations:
– **`auditApi`**:
– `audit`: Execute an audit query.
tasks.ts
This file contains API endpoints for tasks and workflows:
– **`tasksApi`**:
– `getTasks`: Get tasks.
– `deleteWorkflow`: Delete a workflow.
– `getWorkflowModels`: Get workflow models.
user.ts
This file contains API endpoints for user-related operations:
– **`userAPI`**:
– `getLoggedInUser`: Get information about the logged-in user.
– `deleteUser`: Delete a user.
– `putUser`: Update a user’s information.
– `postUser`: Create a new user.
– `getUser`: Get user information (authentication).
– `logout`: Log out the user.
You can use these endpoints to interact with the Nuxeo server programmatically for various document-related operations.
Adding New Communication REST APIs
If you want to open new communication REST APIs with the Nuxeo server, it is recommended to follow the structure and guidelines established in these API files. Each of these files is dedicated to a specific domain of functionality, making it easier to maintain and extend the API.
By adhering to this structure, you can ensure consistency in your codebase and make it more manageable. Creating a new API file following the same structure will help maintain the clarity and organization of your code.
When developing new communication REST APIs, consider the following best practices:
– Define a clear purpose for the new API.
– Create separate API files for distinct functionalities.
– Document the endpoints, parameters, and return values.
– Follow consistent naming conventions and code standards.
– Test and validate the new API endpoints thoroughly.
Adhering to these practices will contribute to the maintainability and scalability of your project’s communication with the Nuxeo server.
Please refer to the relevant function or method documentation for detailed descriptions, parameters, and return values.
4. Project Structure
This section provides an overview of the project’s folder structure, helping you understand how the project is organized and where to find specific components, resources, and code files.
Folder Hierarchy
The project follows a structured folder hierarchy that separates different types of files and resources. Here’s an overview of the key folders in the project:
– **api**: This folder is dedicated to communication with the Nuxeo server using REST endpoints. It contains various API files for different functionalities, such as document management, search, auditing, user-related actions, and tasks.
– **components**: The ‘components’ folder houses reusable React components that are used throughout the project. These components help build the user interface and maintain consistency in the application’s design.
– **pages**: In the ‘pages’ folder, you’ll find the main pages of the application. Each page represents a specific view or functionality within the application.
– **store**: The ‘store’ folder contains the configuration for the Redux store. It’s where state management and actions are defined. The ‘store.ts’ file configures the store using Redux Toolkit, while individual slices manage specific parts of the application’s state. These slices, like ‘userSlice,’ ‘browseSlice,’ and others, include initial states, reducers, and selectors for their respective areas of the application.
Redux Store
The Redux store is a fundamental part of the project’s state management, allowing for efficient data storage and retrieval. The Redux store is organized within the ‘store’ folder, and it is defined in the ‘store.ts’ file.
File: store.ts
The ‘store.ts’ file configures the Redux store using Redux Toolkit. Here are the key aspects of this configuration:
– **Reducers**: Reducers are combined into the store using the `combineReducers` function. This project’s Redux store includes several reducers, such as ‘user,’ ‘browse,’ ‘collection,’ ‘trash,’ ‘users,’ ‘favorites,’ and ‘search,’ each serving specific purposes. Additionally, it incorporates the API reducers generated using Redux Toolkit Query.
– **Middleware**: Middleware is used to handle asynchronous actions, and in this project, it includes the ‘apiMiddleware.’ This middleware plays a crucial role in handling API requests and responses seamlessly.
– **Listeners Setup**: The `setupListeners` function ensures that Redux Toolkit Query’s listeners are configured to work with the store. It is an essential part of handling API-related actions efficiently.
Slices
The project’s Redux store is structured around slices, which are individual pieces of the store that manage specific parts of the application’s state. Each slice contains its initial state, reducers, and selectors. For example, here’s how the ‘browse’ slice is defined:
File: browse.ts
– **Reducers**: The ‘browse’ slice is responsible for managing the current document entry, the parent entry, and other browsing-related state. It includes reducers like ‘setCurrentEntry,’ ‘setBrowseParent,’ and ‘setTrashed’ to update the state as needed.
– **Selectors**: Selectors like ‘selectCurrentEntry,’ ‘selectBrowseParent,’ ‘selectUpdateSearch,’ and ‘selectTrash’ allow you to access specific parts of the ‘browse’ state from within your application components.
The Redux store, with its well-structured slices and middleware, serves as a powerful tool for managing application state, making it easier to handle complex interactions and data flow within the project.
For more details about the specific functionality and usage of Redux slices, please refer to the relevant code files in the ‘store’ folder.
