Rules

Create JavaScript Rules to Style Your Chart

Overview

Rules allow you to include logic in order to change or modify the appearance of your chart based on specified criteria or "rules".

Within rules, you can use logical operators ||, && and != along with comparison operators ==, >, <, >= and <=.

You can also use arithmetic operators within rules: +, -, *, / and %.

Basics

The first step to using rules is to create the "rules" container. This is where you will define your rules in

rules: [ ]

Inside of the "rules" container, you can open a rule set. You can include as many rule sets within the container as you would like. Then, add your "rule" attribute along with the criteria you want to check for. For example, the following rule checks if the plot value is greater than 50 using the %v token.

For a complete list of tokens that you can use in your rules, check out the Tokens article.

rules: [
    {
        rule: "%v > 50"
    }
]

The next step is to specify what you would like the chart to do if that rule is met. You can place the attributes you would like to change right after the rule. For example, if you wanted to change the background color to red if the value is greater than 50, you could do the following:

rules: [
    {
        rule: "%v > 50",
        'background-color': "red"
    }
]

It is important to remember that the "rules" object is not a stand-alone object. Rules are to be used within an object on your chart to change the appearance based on a met criteria. For example, if you have a bar chart and you want to change the color of the bars if they are over a certain value, you can place a "rules" object within the "plot" object.

plot: {
    rules: [
        {
            rule: "%v > 50",
            'background-color': "red"
        }
    ]
}

Styling

Backgrounds

You've already seen how to change the bar color if the value is over a certain amount. Now, let's look at how you can use multiple rules to change the background color.

In this example, we are going to use multiple rules to change the background color to green if the value is above 0, and change the background color to red if it is below 0:

plot: {
    rules: [
        {
            rule: "%v > 0",
            'background-color': "#6c6"
        },
        {
            rule: "%v < 0",
            'background-color': "#c00"
        }
    ]
}
https://app.zingsoft.com/demos/embed/JY9YU4R3
https://app.zingsoft.com/demos/embed/JY9YU4R3

Now, what if you have a line chart and want the background color of the markers to be red if they are below a certain value? You can achieve this by placing the rules within a "marker" object. By doing this, you make your chart more clear and also easier to see things that may require more attention.

type: "line",
plot: {
    marker: {
        rules: [
            {
                rule: "%v < 25",
                'background-color': "red"
            }
        ]
    }
}
https://app.zingsoft.com/demos/embed/CJ8CEZ4M
https://app.zingsoft.com/demos/embed/CJ8CEZ4M

Lines

For charts that contain lines, you can style them based on criteria that you specify.

Remember, you're not limited to only using %v in your rules. You can use any of the available tokens. In this example we used the %p token, or %plot-index, and styled the line for the plot index that is equal to 1.

type: "line",
plot: {
    rules: [
        {
            rule: "%p == 1",
            'line-color': "blue"
        }
    ]
}
https://app.zingsoft.com/demos/embed/LXCKEBZE
https://app.zingsoft.com/demos/embed/LXCKEBZE

You can also change multiple attributes at the same time. In this example, within each rule set, we've set the "line-width", "line-color", and "line-style" based on its value.

type: "line",
plot: {
    rules: [
        {
            rule: "%v  20 && %v < 30",
            'line-color': "#f93",
            'line-width': "8",
            'line-style': "dashed"
        },
        {
            rule: "%v >= 30",
            'line-color': "#f93",
            'line-width': "12",
            'line-style': "solid"
        }
    ]
}
https://app.zingsoft.com/demos/embed/9HW9UZWA
https://app.zingsoft.com/demos/embed/9HW9UZWA

This isn't just limited to the plot lines. Let's look at how we can style our guide lines based on rules by making the "scale-y" guides red if they are a negative value.

type: "line",
'scale-y': {
    guide: {
        rules: [
            {
                rule: "%v < 0",
                'line-color': "red",
                alpha: "0.6"
            }
        ]
    }
}
https://app.zingsoft.com/demos/embed/302XY2H8
https://app.zingsoft.com/demos/embed/302XY2H8

Value Boxes

You can also use rules to display or style value boxes on your chart.

In the same way you changed the color based on our values, you can decide whether the value box will be visible or not based on the same values. In this example, we've hidden all of the value boxes that are below certain values.

type: "line",
plot: {
    'value-box': {
        rules: [
            {
                rule: "%v < 35",
                visible: "false"
            }
        ]
    }
}
https://app.zingsoft.com/demos/embed/6GVAZ13F
https://app.zingsoft.com/demos/embed/6GVAZ13F

Just like we changed the color of markers that were below a certain value, we can instead, add color to our value boxes to indicate performance or importance.

type: "line",
plot: {
    'value-box': {
        rules: [
            {
                rule: "%v < 15",
                'background-color': "red",
                'font-color': "white"
            },
            {
                rule: "%v >= 15 && %v < 30",
                'background-color': "yellow",
                'font-color': "black"
            },
            {
                rule: "%v >= 30",
                'background-color': "green",
                'font-color': "white"
            }
        ]
    }
}
https://app.zingsoft.com/demos/embed/2F40YF9W
https://app.zingsoft.com/demos/embed/2F40YF9W

Borders

Next let's look at a couple ways we can add and style borders using rules.

The next example uses the %pavg, or %plot-average, to add either a red or blue border. If the plot's average is above 50 it will add a blue border. If it is below 50, it will add a red border.

This is a good example of where rules can come in handy, especially if you have multiple plots. Rather than having to figure out the average of each plot and then styling each one individually, ZingChart can do it for you.

type: 'bar',
plot: {
    rules: [
        {
            rule: "%pavg > 50",
            'border-width': "2px",
            'border-color': "blue"
        },
        {
            rule: "%pavg = 40",
                padding: "5px",
                'border-width': "3px",
                'border-color': "#366"
            },
            {
                rule: "%v < 40",
                padding: "4px",
                'border-width': "1px",
                'border-color': "#396"
            },
            {
                rule: "%v > 70"
            }
        ]
    }
}
https://app.zingsoft.com/demos/embed/QRGTURXZ
https://app.zingsoft.com/demos/embed/QRGTURXZ

You can also change the borders of your value boxes based on our criteria.

https://app.zingsoft.com/demos/embed/2KKHFT6V
https://app.zingsoft.com/demos/embed/2KKHFT6V

Examples

Here are a couple more examples to help inspire you.

https://app.zingsoft.com/demos/embed/CBIHNKIG
https://app.zingsoft.com/demos/embed/CBIHNKIG
https://app.zingsoft.com/demos/embed/TK9F5QK4
https://app.zingsoft.com/demos/embed/TK9F5QK4

Summary

This was just a brief look at what you can do with rules. For more information on how to use tokens and which tokens are available to you, check out the Tokens article.

Don't forget, a comprehensive list of available attributes and objects can be found on our JSON Syntax page.