Academy

Creating a user-defined Look and Feel

Half of the work of creating an impacting report or dashboard depends on the Look and Feel you choose. Even though icCube comes with a set of existing themes, you may want to create your own, for example, one that blends with an existing brand or solution identity.

Since version 5.0, we have made theming icCube easier and more powerful. A theme defines the colors, fonts, and default options for icCube widgets. It allows you to define those settings once for all reports. You can thus avoid having to set the theme for each one of the widgets, which would be cumbersome and error-prone.

In this post we explain how to create your own Look and Feel (called Theme) in icCube: MyCustomTheme. This is achieved by adding just a JavaScript and a CSS file. We’ll assume you have some basic JavaScript and CSS knowledge.

Creating a new theme requires some experience, but if you don’t have the time or skills, the icCube team will be happy to create a new theme for you. Just contact us.

The JavaScript file

In the first JavaScript file, let’s name it MyCustomTheme.js, we need to first define a self-invoking function.

(function () {
// code will come here
})();

Adding a Theme is simple. To register a new theme, we need to set the name and the cssCls property. The second property will be applied for all widget boxes as a CSS class; thus, we’ll be able to add widget specific CSS’s. The boxHeaderCls property is not mandatory. In this example, we’ll use it to define a CSS class for the widget headers.

ic3.Themes.registerTheme({
        name: "MyTheme",
        cssCls: "ic3t-myTheme",
        boxHeaderCls: "ic3h-myTheme"
    });

The CSS file

Now we will bind the classes defined in our JavaScript file with the CSS styles.

We’ll name our CSS file MyCustomCss.css and add a green border for all widgets in the report:

.ic3t-myTheme {
    border: 1px solid green;
}

We also want to add some CSS to the widget header:

.ic3h-myTheme .ic3-box-header {
    text-align: center;
    font-family: Arial;
    font-weight: bold;
}

Loading our theme into icCube

We need to tell icCube to load the files we have defined. We do this by adding the following code into ic3report-config.js file in the app-local folder:

function ic3bootstrapLocal(options) {
        .......
        ic3RegisterTheme('MyTheme', 'theme/', 'MyCustomCss.js' , 'MyCustomCss.css' );
 }

Both MyCustomCss.js and MyCustomCss.css are located in the ../app-local/theme/ directory.

We now have our simple theme that we can already test. But our job is far from finished.

AmChart style

The main reason to define a style for AmCharts widgets is to change the look and the colors of the widgets/charts. We start with a new color palette, binding it to AmCharts widgets.

We place the following code in the theme file (MyCustomTheme.js), right after the registration of the new theme.

var myColorPalette = ["#01450e","#027919","#24a93d","#7eb689","#c8d6ca"];
 
ic3.Themes.registerAmChartsWidgetStyle({
      name: "MyAmChartsStyle",
 
       AmChart: {
            fontFamily: "Arial",
            fontSize: 12
        },
        AmCoordinateChart: {
            colors: myColorPalette
        },
        AmStockChart: {
            colors: myColorPalette
        },
        AmSlicedChart: {
            colors: myColorPalette
        }
    });

Following this link we can find all properties that can be set for AmChart widgets.

Because we can register more than one style for the widgets, we have to set the default style used in the theme. For AmCharts, we can do this by setting the amChartsDefaultStyleproperty:

ic3.Themes.registerTheme({
        name: "MyTheme",
        cssCls: "ic3t-myTheme",
        boxHeaderCls: "ic3h-myTheme",
        amChartsDefaultStyle: "MyAmChartsStyle"
    });

Now we can try our theme. An AmChart widget looks like this one with the purple theme applied on the report:

And with the new theme:

Google Chart style

As for AmCharts, we can the define a new style for Google charts:

ic3.Themes.registerGoogleWidgetStyle({
        name: "MyGoogleStyle",
        cssCls: 'ic3-google-my-style',
        widget: {
            colors: myColorPalette,
            fontSize: 12,
            fontName: "Arial"
        }
    });

Adding this style as default for the theme:

ic3.Themes.registerTheme({
        name: "MyTheme",
        cssCls: "ic3t-myTheme",
        boxHeaderCls: "ic3h-myTheme",
        amChartsDefaultStyle: "MyAmChartsStyle",
        googleDefaultStyle: "MyGoogleStyle"
    });

Register the style for other widgets

Adding the style for other widgets is similar to adding a style for AmCharts and Google Charts, just with fewer options, mainly defining the name of the style and a corresponding cssClss class.  This is a full version of the JavaScript and CSS file for our theme:

MyCustomTheme.js

(function () {
 
    /**
    * Define the ' MyTheme ' theme.
    */
    ic3.Themes.registerTheme({
        name: "MyTheme"/* do NOT change as persisted within reports */ ,
        /*
        * The main CSS class representing that style: applied to the ic3-fixed-layout-box DIV.
        */
        cssCls: "ic3t-myTheme",
        /*
        * The default box header style.
        */
        boxHeaderCls: "ic3h-myTheme",
        reportContainerDefaultStyle: "MyTheme",
        amChartsDefaultStyle: "MyAmChartsStyle",
        googleDefaultStyle: "MyGoogleStyle",
        d3BulletDefaultStyle: "MyD3Style",
        buttonDefaultStyle: "MyButtonStyle",
        dropDownDefaultStyle: "MyDropDownStyle",
        contextMenuDefaultStyle: "MyCMStyle",
        accordionDefaultStyle: "MyMenuStyle",
        inputDefaultStyle: "MyInputStyle",
        treeDefaultStyle: "MyTreeStyle",
        queryBuilderDefaultStyle: "MyQBStyle",
        pivotTableDefaultStyle: "MyPivotStyle",
        simpleTableDefaultStyle: "MyTableStyle",
        bigTableDefaultStyle: "MyBTStyle",
        htmlBoxDefaultStyle: "MyBoxStyle",
        htmlTemplateDefaultStyle: "MyTemplateStyle",
        multiSelectDefaultStyle: "MyMSStyle"
    });
 
    /* We can define a color palette that we can use for the charts.*/
    var myColorPalette = [
        "#01450e","#027919","#24a93d","#7eb689","#c8d6ca"
    ];
 
    /**
    * Define a new AmCharts style.
    */
    ic3.Themes.registerAmChartsWidgetStyle({
        name: "MyAmChartsStyle"/* do NOT change as persisted within reports */ ,
        AmChart: {
            fontFamily: "Arial",
            fontSize: 12
        },
        AmCoordinateChart: {
            colors: myColorPalette
        },
        AmStockChart: {
            colors: myColorPalette
        },
        AmSlicedChart: {
            colors: myColorPalette
        }
    });
 
    /**
    * Define a new Google style.
    */
    ic3.Themes.registerGoogleWidgetStyle({
        name: "MyGoogleStyle"/* do NOT change as persisted within reports */ ,
        cssCls: 'ic3-google-my-style',
        widget: {
            colors: myColorPalette,
            fontSize: 12,
            fontName: "Arial"
        }
    });
 
    /**
    * Define a new D3Bullet style.
    */
    ic3.Themes.registerD3BulletWidgetStyle({
        name: "MyD3Style"/* do NOT change as persisted within reports */ ,
        cssCls: 'ic3d3-my-style'
    });
 
    /**
     * Define a new button / action style.
     */
    ic3.Themes.registerButtonWidgetStyle({
        name: "MyButtonStyle"/* do NOT change as persisted within reports */ ,
        cssCls: "ic3-bt-my-style"
    });
 
    /**
     * Define a new dropdown style.
     */
    ic3.Themes.registerDropDownWidgetStyle({
        name: "MyDropDownStyle",
        cssCls: "ic3dd-my-style"
    });
 
    /**
     * Define a new context menu style.
     */
    ic3.Themes.registerContextMenuWidgetStyle({
        name: "MyCMStyle",
        cssCls: "ic3cm-my-style"
    });
 
    /**
     * Define a new accordion style.
     */
    ic3.Themes.registerAccordionWidgetStyle({
        name: "MyMenuStyle",
        cssCls: "ic3a-my-style"
    });
 
    /**
     * Define a new input action style.
     */
    ic3.Themes.registerInputWidgetStyle({
        name: "MyInputStyle",
        cssCls: "ic3i-my-style"
    });
 
    /**
     * Define a tree filter style.
     */
    ic3.Themes.registerTreeWidgetStyle({
        name: "MyTreeStyle",
        cssCls: "ic3tf-my-style"
    });
 
    /**
     * Define a new query builder style.
     */
    ic3.Themes.registerQueryBuilderWidgetStyle({
        name: "MyQBStyle",
        cssCls: "ic3qb-my-style"
    });
 
    /**
    * Define a new pivot-table style.
    */
    ic3.Themes.registerPivotTableWidgetStyle({
        name: "MyPivotStyle"/* do NOT change as persisted within reports */ ,
        cssCls: "ic3-pt-my-style",
        widget: {
            zoom: 1.0
        }
    });
 
    /**
    * Define a new simple table style.
    */
    ic3.Themes.registerSimpleTableWidgetStyle({
        name: "MyTableStyle"/* do NOT change as persisted within reports */ ,
        cssCls: "ic3-st-my-style"
    });
 
    /**
    * Define a new big-table style.
    */
    ic3.Themes.registerBigTableWidgetStyle({
        name: "MyBTStyle"/* do NOT change as persisted within reports */ ,
        cssCls: "ic3-bigtable-my-style"
    });
 
    /**
    * Define a new html box style.
    */
    ic3.Themes.registerHtmlBoxWidgetStyle({
        name: "MyBoxStyle",
        cssCls: "ic3html-my-style"
    });
 
    /**
    * Define a new html template style.
    */
    ic3.Themes.registerHtmlTemplateWidgetStyle({
        name: "MyTemplateStyle",
        cssCls: "ic3html-my-style"
    });
 
    ic3.Themes.registerMultiSelectWidgetStyle({
        name: "MyMSStyle",
        cssCls: "ic3ms-my-style"
    });
})();

MyCustomCss.css

.ic3t-myTheme {
    border-color: 1px solid green;
}
 
.ic3h-myTheme .ic3-box-header {
    text-align: center;
    font-family: Arial;
    font-weight: bold;
}

By David Alvarez