As a component developer, you may find yourself working with JavaScript a majority of the time, especially if you work on client-side components. If you are already familiar with JavaScript, then you will feel right at home while working in the Exaptive platform. This guide will walk you through a simple example of creating a JavaScript component and adding a library. This will allow you to add custom libraries or your favorite JavaScript libraries


From here you might want to check out articles on working with specific libraries, D3React, and jQueryWhen you're ready to start coding on your own, you'll want to have the Javascript Component API reference handy.


Let’s get started!




Creating a JavaScript Component

First, you will want to create a JavaScript component. To do so, navigate to your studio and click on the plus (+) button in the top-right corner. Then, select “Component” and then “JavaScript”. Type in a name for your component and click the “Create” button. This will bring you to your component’s edit page in the studio. From here, you can edit your component (e.g. its description, its inputs and outputs, or its code). For now, we are going to focus on the component’s spec file, so click on the SPEC tab on the left-hand side of the screen.


WARNING  Because the spec file is a JSON file, it is important to make sure it is properly formatted. Invalid JSON will result in an error, disallowing you from saving your component. Also, unless you know what you are doing, we advise that you do not delete any of the properties in the file. Doing so may result in a broken component.


NOTE  Due to the possible pitfalls that editing the spec of a component as a JSON file brings, we are currently working on ways to eliminate this overhead and make it simpler for users to edit their components’ spec files without breaking them. This article will be updated once this has been implemented.


Editing the Spec File

Once you’ve click on the SPEC tab of your component, you will be shown a file that looks like this, ready for you to edit:


{

 "name": "Hello JavaScript",

 "main": "script.js",

 "tags": [],

 "image": "//content.exaptive.city/c.svg",

 "description": "This is a template jsdom component. It shows how to use most of the functionality available in a js dom component.",

 "domain": "jsdom",

 "layout": "html",

 "layoutSpec": {

   "element": "div",

   "attributes": {

 "class": "my-comp"

   },

   "innerHtml": "<p class=\"my-child\">\n\tThis is some text\n</p>",

   "css": ".my-comp {\n\tbackground: #eee;\n}"

 },

 "dependencies": {

   "file": [

   {

   "type": "js",

    "path":  

 "https://cdnjs.cloudflare.com/ajax/libs/jquery/3.0.0-beta1/jquery.min.js",

    "name": "{replace1}quot;

 }

   ]

 },

 "domainSpec": {},

 "input": [

   {

   "name": "doSomething",

   "valueType": "string",

   "description": "An input that takes a string"

   }

 ],

 "output": [

   {

   "name": "data",

   "valueType": "dynamic",

   "description": "An output that returns any value type"

   }

 ],

 "preprocessors": [

  "ES2015"

 ]

}



Pretty scary, eh? No worries! We will only be touching a small portion of this file; namely, the “dependencies” property which looks like:


"dependencies": {

 "file": [

 {

   "type": "js",

   "path":  

 "https://cdnjs.cloudflare.com/ajax/libs/jquery/3.0.0-beta1/jquery.min.js",

 "name": "{replace2}quot;

 }

 ]

}


You will notice that we already have a dependency listed: jQuery. Every JavaScript component comes with jQuery by default (specifically, version 3.0.0). If you do not need jQuery or want to use a different version, then feel free to modify this section as you see fit as jQuery is not required to run components in Exaptive. We merely include it by default because of its popularity and utility it provides developers.


NOTE  For more information on the different properties of the spec file and what they do, please refer to the article: Component Spec Properties.


URL Dependency

We have actually already seen an example of using a URL-based dependency (by URL-based, I mean a dependency that points to a specific URL; this is most often a file hosted through a CDN service such as CDNjs). The included jQuery dependency is an example of this! The dependency is a JavaScript file so it goes into the file array of dependency section as an object with the following properties:


However, what if you want to use a custom library that isn’t hosted on CDNjs or similar hosting site? That is where assets come in.


NOTE  The following section shows how to use an asset created in Exaptive as a dependency for a component. To learn more about uploading custom assets, please refer to the article: Creating Assets.


Asset Dependency

If you have a JavaScript file that has been uploaded as an asset into your studio, then you can use it as a dependency fairly easily in your component as well. In fact, there is only one key difference between using an asset-based dependency and a URL-based one.


Instead of having the “path” property that points to the URL of the file, you will have an “asset” property whose value is the GUID of the asset you wish to include.


NOTE  The only way, currently, to get the GUID of the asset you want to use is to get from the URL when on the desired asset’s information page. Changes to how the spec can be edited will help resolve this issue and this article will be updated to reflect those changes.


For example, let’s say I’ve uploaded my own version of jQuery as an asset, and it has the GUID, 3bdd5ce8-0e03-43d6-a311-2ae198474c8a. The code in my spec file would then look like the following:


"dependencies": {

 "file": [

 {

   "type": "js",

   "asset": "3bdd5ce8-0e03-43d6-a311-2ae198474c8a",

 "name": "{replace3}quot;

 }

 ]

}


Using a Library

You now have a JavaScript library included in your component, but how do you use it in your component's code? It is actually quite simple. You only need to make one call to the Exaptive API in your code and access the library via its name property on the imports object of the API. Like so:


 var $ = this.api.imports.$;


You can then use $ to reference your library (in this case, jQuery) in your code. For example:


 var div = $(“div”);


The line, var $ = this.api.imports.$; will need to be called in every method of your component where you intend to use the library. For example, let’s say that your component has two inputs and therefore has two methods that map to these inputs, e.g. data() and count().


If you need to use jQuery in both of these methods, then you will need to call var $ = this.api.imports.$; in both. Alternatively, you may also call this.$ = this.api.imports.$ in the _init method of the component. Then you can just call this.$ anytime you need to access the library in your code.


CAUTION  Declaring the dependency in the _init method can cause issues in your code if not careful. Mainly, if you are inside a function within one of your methods and you try to call this.$, you will get an error as this is referring to the scope of the inner function in the method and not the scope of the component itself. This is easily remedied by declaring var that = this; or var self = this; outside the inner function. Then within the inner function you can call that.$ or self.$ to access the library.



Other Things to Know About Using JavaScript in Exaptive

As stated at the start of this article, working with JavaScript in the Exaptive platform will feel very familiar if you are already experienced in the language. However, there are a view things to know about while working with your components.


First and foremost, it is useful to know that JavaScript components use the ECMAScript 6 syntax and that your component is effectively an ES6 module. All of your component’s code will reside in the export default code block.


_init() & _close()

When you first create a component and go to the the script view, you will notice that we have provided two functions by default: _init() and _close(). The init function allows you to set up anything you need to when your component loads: initializing state or data, etc. And the close function allows you to do any cleanup that may be necessary.


Component Inputs are Functions

Inputs that you create on the INPUTS tab of your component can be accessed via functions in your component’s script. What this means is when data comes into your component in your xap via a port, the associated function will be called (the port and the function have the same name).


Debugging Your JavaScript Components

When it comes to debugging your components, you have a couple different options. If you are mostly wanting to verify values, or make sure things are running when you expect them to, then consider using this.api.log(string);. This will print the given string to your xap’s log, which can be accessed from the DATAFLOW via Tools -> Log.


However, if you are wanting to dive a bit deeper into your code and actually step through it, then we recommend Google Chrome’s Dev Tools. If you open up the Dev Tools while editing your xap, you can get to your component’s code via the Sources tab. Your code will reside in the folder (usually at the bottom of the list) with a GUID for a name which matches the GUID of your studio (you can see this GUID in your URL as well while in your Studio). Now, expand that folder, the exaptive folder (not the exaptive.city one), and finally your studio folder. Nested here are the scripts for all the components in your xap. Click on any and you’ll see your code. Remember: your code was written in ES6, but it was transpiled into ES5 so it may look slightly different.


PRO TIP  You can quickly get to your code by setting a manual break point in your code via the debugger; statement. With that set, you can then open the Dev Tools and run the xap, and then your xap will hit that line as if it had a break point. Just be sure to remove it when you’re done!