Documentation
NAV Navbar
JavaScript
  • Activation API - React Module
  • Activation API - React Module

    Introduction

    The Kameleoon React Module is a standard npm module that adds new functionality to our base Activation API. The module first needs to be installed into your React application and deployed. Once integrated, specific new methods will be added to the Activation API. These methods will allow you to modify the UI and behaviour of React based components without modifying the source code of your application. For instance, you will be able to query (select) React components and change their states and props.

    Installation

    npm i kameleoon-react
    

    The Kameleoon React Module can be installed via npm in a standard way: npm i kameleoon-react.

    import KameleoonReact from 'kameleoon-react';
    import React from 'react';
    import ReactDOM from 'react-dom';
    

    The module then needs to be initialized at the top of the React application.

    General Usage

    The Kameleoon React module adds a new module (namespace) to the usual Kameleoon Activation API: Kameleoon.API.React. Although several methods are available within this module, the most important one is runWhenComponentPresent().

    To use an API method provided by the React module, just call it in the usual way, for instance Kameleoon.API.React.runWhenComponentPresent().

    Kameleoon.API.React Reference

    runWhenComponentPresent

    Kameleoon.API.React.runWhenComponentPresent("MyComponentName", function(components) {
        // components contains all components that match the type and filters
    }, {"className": "MyClassName", "layout": "push"});
    

    The runWhenComponentPresent() method will execute a JavaScript function (callback) as soon as a specific React component appears in the DOM.

    Arguments
    NameTypeDescription
    typeStringName of the component to find. This field is mandatory.
    callbackFunctionJavaScript function that will be called when a component is found. This field is mandatory.
    filterObjectFilters to obtain specific components among all components with the same type. This field is optional.
    pollingIntervalNumberPolling interval, in milliseconds. The engine will periodically check if the component is present on the DOM or not. This field is optional, if not provided, the method will use the default value of 200 milliseconds.

    createReactElement

    Kameleoon.API.React.createReactElement("div", {
        "className": "MyCustomClassName",
        "onClick": function () {
            // do something
        }
    }, "My inner text");
    
    Kameleoon.API.React.runWhenComponentPresent("Link", function (components) {
        var title = Kameleoon.API.React.createReactElement("h3", {}, "My new title");
        var children = [title];
        components[0].setProps("children", children);
    }, {});
    

    The createReactElement() method will allow you to create React elements directly.

    Arguments
    NameTypeDescription
    typeStringName of the component to create ("div", "a", etc...). This field is mandatory.
    propsObjectProps to add to your element. This field is optional.
    childrenAnyInner content of the element. This can be a text string, an Array or an Object. This field is optional.

    Component methods

    The API returns custom objects that are wrappers around the React components. You can use some standard React methods to edit and change these components, such as the ones listed below.

    setState

    Kameleoon.API.React.runWhenComponentPresent("MyComponentName", function(components) {
        // components contains all components that match the type and the filters
        components[0].setState("myKeyState", "myNewValue");
    }, {});
    

    The setState() method enqueues changes to the component state and tells React that this component and its children need to be re-rendered with the updated state.

    Arguments
    NameTypeDescription
    keyStringKey (name) of the data to be updated. This field is mandatory.
    valueAnyValue of the data. This field is mandatory.

    setProps

    Kameleoon.API.React.runWhenComponentPresent("MyComponentName", function(components) {
        // components contains all components that match the type and the filters
        components[0].setProps("myKeyProps", "myNewValue");
    }, {});
    

    The setProps() method enqueues changes to the component props and tells React that this component and its children need to be re-rendered with the updated props.

    Arguments
    NameTypeDescription
    keyStringKey (name) of the data to be updated. This field is mandatory.
    valueAnyValue of the data. This field is mandatory.