Graph & Paper

In the first part of the tutorial, we saw a working example of a simple JointJS application:

Now that we have included JointJS on our webpage, we can start creating our diagram.

In this section, we will learn how to finish setting up by creating a graph and a paper in our JointJS code and linking them to our HTML. We will be looking at these portions of the original Hello, World! application:

<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" type="text/css" href="node_modules/jointjs/dist/joint.css" />
</head>
<body>
    <!-- content -->
    <div id="myholder"></div>

    <!-- dependencies -->
    <script src="node_modules/jquery/dist/jquery.js"></script>
    <script src="node_modules/lodash/lodash.js"></script>
    <script src="node_modules/backbone/backbone.js"></script>
    <script src="node_modules/jointjs/dist/joint.js"></script>

    <!-- code -->
    <script type="text/javascript">

        var graph = new joint.dia.Graph;

        var paper = new joint.dia.Paper({
            el: document.getElementById('myholder'),
            model: graph,
            width: 600,
            height: 100,
            gridSize: 1
        });

        var rect = new joint.shapes.standard.Rectangle();
        rect.position(100, 30);
        rect.resize(100, 40);
        rect.attr({
            body: {
                fill: 'blue'
            },
            label: {
                text: 'Hello',
                fill: 'white'
            }
        });
        rect.addTo(graph);

        var rect2 = rect.clone();
        rect2.translate(300, 0);
        rect2.attr('label/text', 'World!');
        rect2.addTo(graph);

        var link = new joint.shapes.standard.Link();
        link.source(rect);
        link.target(rect2);
        link.addTo(graph);

    </script>
</body>
</html>

All useful JointJS applications need to have a graph and a paper. The graph contains a reference to all components of your diagram, and the paper is responsible for rendering the graph.

The Graph model is usually defined on the first line of the JointJS JavaScript code. In our code, we saved a reference to it as var graph. In order to have our cells (elements and links) rendered, we need to add them to the graph; unless we add our cells, the diagram does not know they exist. In our example, we do that with the addTo() functions, but we could also do it with the graph.addCells() function.

Normally, the Paper view is specified directly after the graph definition. We create it with an options object and save it as var paper. Of the five options, two define crucial paper attributes:

These attributes relate the rendered paper to our HTML on one side, and to our JointJS data (element and link models) on the other. This makes paper the most important building block of any diagram.

The three other options specify the paper's presentation attributes. In our example, these are:

The full list of available Paper attributes is long and allows customizing almost everything about the paper rendering. You will encounter these in the advanced portions of the tutorial series. The most used paper attributes are presented in visual form in the Paper Attributes demo.

Paper Styling

Now, let's make some changes to the appearance of the original Hello, World! application. We can specify a background color with the background attribute, and show the grid with drawGrid. For the grid to be visible, we also need to increase gridSize:

The code is presented below. The changes we made are highlighted:

<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" type="text/css" href="node_modules/jointjs/dist/joint.css" />
</head>
<body>
    <!-- content -->
    <div id="myholder"></div>

    <!-- dependencies -->
    <script src="node_modules/jquery/dist/jquery.js"></script>
    <script src="node_modules/lodash/lodash.js"></script>
    <script src="node_modules/backbone/backbone.js"></script>
    <script src="node_modules/jointjs/dist/joint.js"></script>

    <!-- code -->
    <script type="text/javascript">

        var graph = new joint.dia.Graph;

        var paper = new joint.dia.Paper({
            el: document.getElementById('myholder'),
            model: graph,
            width: 600,
            height: 100,
            gridSize: 10,
            drawGrid: true,
            background: {
                color: 'rgba(0, 255, 0, 0.3)'
            }
        });

        var rect = new joint.shapes.standard.Rectangle();
        rect.position(100, 30);
        rect.resize(100, 40);
        rect.attr({
            body: {
                fill: 'blue'
            },
            label: {
                text: 'Hello',
                fill: 'white'
            }
        });
        rect.addTo(graph);

        var rect2 = rect.clone();
        rect2.translate(300, 0);
        rect2.attr('label/text', 'World!');
        rect2.addTo(graph);

        var link = new joint.shapes.standard.Link();
        link.source(rect);
        link.target(rect2);
        link.addTo(graph);

    </script>
</body>
</html>

JointJS source code: graph-and-paper.js

Appendix: Paper Scaling

At any point after defining the paper, we can use the paper.scale() function to transform the paper and all of its contents. Have a look at the advanced Multiple Papers tutorial to learn how to use this functionality to create diagram minimaps and previews. The example presents the diagram scaled at a factor of one half; note that scaling does not affect paper dimensions:

paper.scale(0.5, 0.5);

JointJS source code: graph-and-paper-scaled.js

Appendix: Paper Translation

We can also use the paper.translate() function to move the origin of the paper coordinates and all of its contents; when used in a custom interaction, this may support paper panning functionality. The example presents the scaled diagram from above translated by 300 and 50 units:

paper.translate(300, 50);

JointJS source code: graph-and-paper-translated.js

We now understand the importance of the Graph and Paper objects, and know how to change the appearance of our paper.

The next step is to learn how to work with elements.