React pages templates and plugins overview

This section explains how to customize Portal pages built with ReactJS. This functionality is only available for the Search Page at first.

How to set up an environment

Install some development tools using the following commands:

Install nodejs:

curl --silent --location https://rpm.nodesource.com/setup_8.x | sudo bash -
yum install -y gcc-c++ make
yum install nodejs

Install portal build environment:

cd /opt/cantemo/portal/portal_media/js
yum install git
npm install
npm install -g grunt

After this you should be able to follow the instructions below.

There are two ways to customize Portal pages built with React. Let’s start with the simplest one.

I. Plugins

The plugins are located in following directory: /opt/cantemo/portal/portal_media/js/app_react_plugins/

../_images/plugins-directory-structure.png

We have three plugin areas on the search page where you can insert your own custom functionality. As you can see by their names, one is located on the main gearbox, one each type of pods we have on display. Collection pod and item pod.

../_images/plugins-ui.png

Using these three plugins you can add extra options <li>OPTION</li> to each of the gearboxes and you can also add functionality to your new options.

Implementing plugins

The plugins are React components, for example the following would show a note when clicked:

class GearboxPlugin extends React.Component {
  constructor(props) {
    super(props);
  }

  testFunction = () => {
    let {collectionId} = this.props;
    alert(`Collection ${collectionId} clicked`);
  };

  render = () => {
    return (
      <li><a onClick={this.testFunction}>Example: Reindex</a></li>
    );
  };
}

For each of the plugins, there is an example included in the folder with the filename index.example.js.

You can enable each of the examples individually by copying index.example.js to index.js and then compiling the JavaScript. See III. Compiling and rendering.

After this modify the index.js files to replace them with your own customizations.

You can find multiple ways of editing React code in the official documentation: https://reactjs.org/docs/hello-world.html

II. Theming

The templates are located in this directory: /opt/cantemo/portal/portal_media/js/template_engine/ There will be individual directories for each customizable page.

This focuses on the search page. The search page default template is located here: /opt/cantemo/portal/portal_media/js/template_engine/search/default/. Please do not modify these files. If you want to customize something, you will need to copy that particular file into the /opt/cantemo/portal/portal_media/js/template_engine/search/custom/ directory (create the custom folder if it doesn’t exist) and you must respect the exact folder structure and file names from the default template.

../_images/directory-structure.png

So for example, let’s say you want to customize the way Item pods look and work. In order to do this, navigate to /opt/cantemo/portal/portal_media/js/template_engine/search/default/components/ and copy the item-grid.js file. Now go to /opt/cantemo/portal/portal_media/js/template_engine/search/custom/, create the components folder (if it doesn’t already exist) and paste the file you’ve copied there.

III. Compiling and rendering

The last step you need to do is to actually compile all the files. In order to do that, you have to be in the /opt/cantemo/portal/portal_media/js/ directory. From here simply run this command ./start-templating-script.sh. This will compile the files and it will then watch for further changes you do to the templates.