Labo Components

This repo contains the front-end components in use in the Clariah Media Suite project. It runs in paralell with the back-end server architecture, maintained in the separate clariah-mediasuite repository.

This project is published as an npm module.

Note on 24th March 2021 build (React 17, webpack 5)

Required fixes:

• had to update the bundle-scss npm script: https://github.com/reactway/scss-bundle
• Replaced react-power-select with React Select
• changed plugins for minifying CSS and JS (see webpack files)

Code splitting (TODO)

https://www.valentinog.com/blog/webpack/ https://webpack.js.org/guides/code-splitting/

Development setup

Integration with server side Clariah Mediasuite

To develop components in this repo, it needs to be linked to the clariah-mediasuite project. See its installation instructions for how to set it up.

Once clariah-mediasuite is installed, we need to link the two projects.

Clone labo-components (recommended as sibling directory to the clariah-mediasuite repo):

git clone [email protected]:beeldengeluid/labo-components.git .

Navigate to the node modules dir inside the clariah-mediasuite project:

cd src/static/node_modules

Remove the npm installed labo-components dir:

`rm -R labo-components`

Create a symlink in the currect dir pointing to the git cloned labo-components (assuming the two repos are located in sibling directories):

ln -s ../../../../labo-components/  .

Navigate back to the root of the cloned labo-components directory and install its dependencies:

npm install

Then run the development version:

npm run dev

Now run the server as explained in the clariah-mediasuite README and you should be able to see your front-end updates in the browser when you edit the labo-components project 🎉

Style compilation

SASS is used to generate the main stylesheet (/src/static/css/main.css).

Whenever you want to change the overall styling you need to run the watcher using a npm command:

npm run watch

While the watcher is running any changes to the *.scss files in the /static/sass folder will be compiled into /src/static/css/main.css

Creating a new recipe

We refer to the different tools that together make up the Media Suite as 'recipes'. The best way to learn how the media suite works is by creating a new recipe, which will give you the opportunity to start assembling your own choice of components.

Before starting, it's good to realise there are several ways of using the component library, but there is a recommended one for integration in the media suite, which we'll discuss right away.

Adding a recipe to the recipes page (recommended)

By following the recommended approach, your custom recipe will appear in the recipes page of the media suite.

Step 1: Create a recipe JSON file

The recipes.html file is the template that renders certain (manually chosen) recipes from the resources/recipes folder in blocks on the page to choose from.

To make your recipe appear on this page, first you need to add a new JSON file (with a meaningful name reflecting the functionality of the recipe) in /resources/recipes:

{
    "id" : "my_recipe",
    "name" : "Your own recipe!",
    "type" : "my_recipe",
    "phase" : "recipe-building",
    "description" : "Your recipe that does very cool things. Aim for world peace!",
    "ingredients" : {
        "key1" : "value1",
        "key2" : "value2"
    }
}

Note There is also an example.json you can copy and modify for convenience

The name is used as the title of your recipe on the recipes page

The description is used as the description for your recipe on the recipes page

The type parameter is used to load the correct recipe *.jsx file from the labo-component's index.jsx file, which is the main interface for using the component library, but more on that later on.

The phase is used to place your recipe in the right category on the recipes page. Please use one of the already existing values to reflect the intended research phase your recipe is suitable for. If it's something new, please make up a meaningful label.

The ingredients are basically any key/value pairs you'd like to use to easily configure your recipe.

Since hot loading does not work yet, you have to restart the server to make you recipe JSON load into server memory.

After that you can finally make your recipe appear in the recipes.html by insert a block of HTML like this:

<!-- EXAMPLE  -->
<div id="{{recipes['my_recipe'].id}}" class="col-sm-6 col-md-4">
    <div class="panel panel-default">
        <div class="panel-heading">
            <h3 class="panel-title"><i class="fa fa-rocket"></i>&nbsp; {{recipes['my_recipe'].name}}</h3>
        </div>
        <div class="panel-body">
            {{recipes['my_recipe'].description}}
        </div>
        <div class="panel-footer text-right"><a href="{{recipes['my_recipe'].url}}">View recipe</a></div>
    </div>
</div>

Step 2: Create the .jsx file in the component library

Currently the component library also contains the application specific recipes as top-level React components. In a later version, the media suite recipes will probably be moved into this repo.

Since you've only created a JSON file and want to create a whole new recipe type, you now have to create a new *.jsx file for your recipe and map your recipe in the index.jsx of the labo-components.

Open the labo-components code in your editor and add a new *.jsx file to the /app directory. The easiest is to copy ExampleRecipe.jsx and rename it (and its class name!) to whatever you like. Otherwise your recipe code should contain the following as the bare minimum:

import IDUtil from './util/IDUtil';

class MyRecipe extends React.Component {

    constructor(props) {
        super(props);
        this.state = {}
    }

    render() {
            return (
                <div className={IDUtil.cssClassName('example-recipe')}>

                </div>
            )
        }
    }

}

export default MyRecipe;

Following this, make sure to map the recipe type to your React class in index.jsx by extending the cookRecipe function as follows:

else if(recipe.type === 'myRecipe.type') {
    render(
        <MyRecipe recipe={recipe} params={params} user={user}/>,
        document.getElementById(elementId)
    );
}

Now to compile your changes please run the following command in the main directory of the labo-components code:

npm run dev

This will watch for any changes you make in the code (within the /app directory) and will try to build the code. If it fails it will print in what part of the code the error originates.

After you've managed a succesfull build, you need to do one more thing to make your new recipe work: edit the recipe.html (template that imports the labo-components library and is responsible for rendering recipes in the media suite) as follows:

<!--<script type="text/javascript" src="/static/node_modules/labo-components/dist/labo-components.js"></script>-->
<script src="/PATH_TO_YOUR_DEVELOPMENT_VERSION_OF_LABO_COMPONENTS/dist/labo-components.js" type="text/javascript"></script>

This makes sure the media suite code does not look for the component library in the node_modules, but looks for the development version you've just built.

Now (possibily after clearing your browser cache) you can now click on your recipe in the recipes.html and go to a working dummy recipe!