D3.js is pretty simple to set up in your Exaptive components, and using it in Exaptive will feel quite familiar. This article will get you up and running by showing you how to include the D3 library in your components in the Studio. 


Also included is a simple "Hello, World" D3 example that will help you verify that D3 is, in fact, running correctly in your component.


When you're ready to start coding on your own, you'll want to have the Javascript Component API reference handy.




Getting Started

To get started, create a new component from your studio by clicking the "+" button. Make sure you select "JavaScript," and give your component a name. Finally, click the "Create" button.


You should now see the EDIT page of your newly created component. This is where you can edit things like the component's description, its inputs and outputs, and the actual script it runs. For now, we are interested in the component's specification so click the SPEC tab on the left-hand side of the screen.


The spec is where we can edit things like the name of the component or add tags to help other users find it and use it in their own xaps. Most importantly for this article, we can add dependencies to our component in the "dependencies" section. So go ahead and click EDIT at the top of the spec file so we can add D3.js as a dependency.


Add D3.js


The spec file is simply a JSON file that describes things about your component. We are interested in the "dependencies" section, but you will notice that there is already and entry here:

 

"dependencies": {
        "file": [
            {
                "type": "js",
                "path": "https://cdnjs.cloudflare.com/ajax/libs/jquery/3.0.0-beta1/jquery.min.js",
                "name": "$"
            }
        ]
    }

 


Every JavaScript component, by default, includes jQuery as a dependency. We will go ahead and leave this in, but we won't be getting into the specifics of working with jQuery. 


We can use this as an example on which to base our D3.js dependency. We simply need to follow the same format and only edit the path and the name properties. Thus, our dependencies section now looks like the following:

   

    "dependencies": {
        "file": [
            {
                "type": "js",
                "path": "https://cdnjs.cloudflare.com/ajax/libs/jquery/3.0.0-beta1/jquery.min.js",
                "name": "$"
            },
            {
                "type": "js",
                "path": "https://d3js.org/d3.v4.min.js",
                "name": "d3"
            }
        ]
    }

   


Now all you need to do is click "DONE" to close the editor and then click the "Save" button in the top-right corner of the screen and...voilà! You've just added D3.js as a dependency to your component! You can now access the awesome power of this library in your script and make some amazing components to share with the growing Exaptive community!


Hello, D3!


Now that you've added D3 as a dependency, let's edit the script and test your component in a xap to make sure that everything is working as expected.


First, open your component's script by clicking on the SCRIPT tab on the left-hand side of the screen. This is your component's script. This is where you write the code to give life to your component and have it do something awesome.


For now, we will ignore all the code in the doSomething method and focus our attention on the _init method. Any code in the _init() method is run once your component has loaded in your xap. So once your xap that contains this component loads it, that code will run before anything else in the component.


For now, we are going to do something simple. We are going to display some text on the screen and change the background color of the body element on the page.


So, in the _init method add the following code:

  

let d3 = this.api.imports.d3;

d3.select("body").style("background-color", "deeppink")
    .selectAll("p")
    .data([1, 2, 3, 4, 5])
    .enter().append("p")
        .text(function(d) {
            return `Hello, I'm number ${ d }!`;
        }).style("color", "white");

 


This doesn't do anything revolutionary, but it will give us confidence that D3 is accessible in our component and we can work on more interesting and robust components.


Simply put, the code above selects the body of the page and changes the background color to my favorite shade of pink. It then selects all the p tags on the page, takes in an array of integers and, for each integer, appends a paragraph element with some text based on the data. Finally, for each of those paragraphs, the color of the text is changed to white.


Before we test this, take a moment to delete all the HTML located in the INNER HTML tab (as it isn't needed for this exercise) and save your component.


Using Our Component


Time to see the fruits of our labor! Go back to your studio and click the "+" button again, but this time select xap. This will bring you directly to the DATAFLOW area of your Studio.


From here, find your D3 component and bring it into the DATAFLOW. 


Now go to PREVIEW, and you will see your component working in all its glory! The background should be pink and you should see five white paragraphs on the page:




That's it! You've successfully created a D3.js component! Take some time to party and grab some coffee or tea, because now it is time for you to go make something awesome!


Happy building!