Integrating DatafariUI in a div

This document is meant to detail the steps and rules to follow to integrate DatafariUI in a div of an existing web app. The example provided uses a simple web app hosted on an apache2 web server, but the key principles are explained so that you can transfer them to your own server technology.

1- Decide the path to which DatafariUI will be deployed

Before starting building the app and moving files, you need to determine a root path from which the DatafariUI will be hosted, all paths under this root will belong to DatafariUI (it uses the URL to navigate through the UI and some assets need to be stored under that path to be accessed by the application).

In our example, our webapp is hosted at /otherfolder and we decided to host DatafariUI on a page under /otherfolder/testdatafariui .

2- Prepare DatafariUI for the build

We need to prepare the DatafariUI application build so that it is ready to be accessed from the desired path. We also need to configure the address of the Datafari we want to call.

Download the source code

The DatafariUI project is on GitHub, the homepage of the project is here :

https://github.com/francelabs/DatafariUI

So do a git clone of the project to download the source code.

Install Node

To build the UI you will need node and npm. Install the latest LTS version of node from their website: https://nodejs.org/en/ (packet managers are often quite behind and older versions might not work as intended).

This should also install npm as part of the installation.

Build and configure for production

Install the dependencies locally

Before building the project, you need to download all the dependencies locally using npm. To do so run the following command at the root directory of the project:

Configure Datafari for our production case

First open the .env.production file. It contains a PUBLIC_URL variable we must change to match the root path we decided to use for the page hosting DatafariUI:

Then open the src/index.js file, you must change the window.datafariBaseURLto match the URL of your Datafari instance (my datafari instance is hosted at 192.168.1.20 with the default settings resulting in the address https://192.168.1.20/Datafari to access it):

The application is now ready to be built.

3- Building the app and copying the required files

To build the production ready version of the app go to root folder of the project and run:

You now have a build folder in the project folder tree.

You need to copy the folders images, locales and static from this build folder so that they can be accessed from the previously chosen root path for DatafariUI, in my case:

4- Including the app in the chosen page

You will need to perform two things:

1. Include the necessary scripts and css into the page

2. Add a div with the id “root” to your page

Including required scripts and css

Open the index.html file from the build folder (build/index.html) of the datafariui project (the file content is written on one line, you can reformat it to help you copy the required elements). From there, identify and copy the 3 scripts elements at the end of the body and add them to the end of the body of your page. They should look something like the following:

To build the production ready version of the app go to root folder of the project and run:

Also copy the two link tags at the end of the head tag, right after the title tag, to the end of the head section of your html page. They should look something like the following:

Including a div with the “root” id

Now add an empty div with the id “root” somewhere on your page:

For reference, here is look at my html page, which is /var/www/html/testdatafariui/index.html in my case (I integrated DatafariUI into the default index page of the ubuntu installation of apache2 here, and enlarged the main div to 90% of the width of the page to have a proper render of the UI):

5- configuring the web server

As stated at the beginning, DatafariUI is using the URL to navigate from one UI to another (from search at /search to preview at /preview for example). However it is a single page application, therefore, any request sent to a URL under the root we chose that does not correspond to a file should be redirected to the page hosting the app. In my example case, the app is hosted by the /otherfolder/testdatafariui/index.html page and I am using apache2 so serve it. Below is the part of my apache2 configuration to achieve the required behavior:

The installation is now finished and you should be able to access DatafariUI from the page hosting it:

Open

Advanced usage 1: Modifying the id required for the div

Before building the datafariui project, you can edit the src/index.js file. Within it there is this block of code:

Change root to the id you want to use for the div and follow the rest of the procedure.

Advanced usage 2: The page hosting DatafariUI is a react app or it uses the WebPack runtime

DatafariUI is bootstrapped using create-react-app. The app is using the webpack runtime with the default configuration. If your application does the same, there will be a clash of names and only one application will be able to load on the page at any given time. To fix that, follow the information of this blog post: https://medium.jonasbandi.net/hosting-multiple-react-applications-on-the-same-document-c887df1a1fcd to redefine the name of the webpack runtime for one of the application and you should be good to go.