So, you want to build or edit a component. Let's take a quick tour through the Component Editor. We won't get into the details of building a component here. We'll help familiarize you with the system for building them. (This introduction covers JavaScript components, but the ideas are general, and the component templates and language references elucidate what you'd need to know for other languages). 


To create a new component, click the plus button to create something new in your Studio. 




Select Component. 




Now, select your language and be sure to give your component a name. No name = no creation. 


Alright, you're viewing your new component in the Component Editor. You'll notice a number of tabs on the left side of the page. Let's look at each of them individually. 

Description

First we have the description to explain what your component does at a high level. This helps other people understand (and you remember!) what your component does. You may have seen a few components with bad descriptions. Not cool, right? Don't be that person! The descriptions for components use Markdown, a text-to-HTML conversion language.  


Inputs


Next, we have inputs. Inputs allow us to set variables and pass data into the code in Xaps. The component template comes with a default input. Click on that to expand it so you can rename and reconfigure the input. 


With the expanded port, things get pretty simple. You can rename the input, change the data type it will accept (if you have questions about acceptable value types click the question icon), set a default value that will be loaded when you pull in the component, and give the input a description. This really helps other people use your component without needing to understand the underlying code, so, don't forget to spend a little time on this! 


What if your component needs multiple inputs? There are two options:

1) Add a new port

2) Create a composite port


Adding a new port is straight-forward. Just click the button in the upper right-hand corner. 


Creating a composite port creates an object with properties that will be passed into the component together when they're all provided as inputs. To do this, you'll use the entity type and the syntax will look like this:

 

entity<string firstName, string lastName, integer SSN, list previousWorkplaces>

 

You can select "Show Granular Inputs" to make these all available as individual ports on your component, or leave it unselected to have it appear as one port that accepts an object with all of the values. 


Setting the default when using granular inputs looks like this:

 

{
"firstName": "John", 
"lastName": "Smith", 
"SSN": 123034890, 
"previousWorkplaces": ["Apple", "Microsoft", "GE Capital"]
}

 

Outputs

Outputs work pretty much the same way as inputs. But quickly take a look at the outputs tab, and note there's an output called "data," which we'll talk a bit more about as it relates to the script. 


Script


The script is where you'll write your code. Here you'll see a template script. 


You'll notice there are comments to help guide your use of the code. There are a few things worth noting:

  • The function doSomething is named the same as the template component input. This is no coincidence. When a new input is received in the doSomething port it triggers the doSomething function. What if you want multiple inputs to be tied to that function? Composite inputs are the answer. 
  • The inputs are being assigned using the state variable. As it's structured in the template this is making available the values of any inputs. To access the doSomething value, your code would look like this: var doSomethingValue = state.doSomething
  • The output for the data port is being called by a string version of the output name in the output method and populated with a string in the template but the data being passed to it could be any manner of things and will typically be a variable name. 
  • The specifics of the script change based on the language domain you've chosen, but these ideas are general enough that the script templates should sufficiently communicate the nuances of your chosen language. 


For help with syntax in your script, look at the component API documentation in the Component Authoring section.


Inner HTML


Moving on to the inner HTML tab you'll see another set of template code. This portion is specific to JavaScript and pertains to any HTML you would like to be associated with your component. A specific use case would be for a component, like a File Drop Target, that by default has some HTML structure. This tab accepts standard HTML code and is read as such. That said, in most cases, this tab will be left blank. 

CSS


Similarly, the CSS tab allows for styling of the component at the component level (there's also a CSS tab at the xap level where this can be overwritten if necessary). This tab accepts standard CSS. 


Spec


Finally, we arrive at the spec file. If you've made changes above and saved them, you'll notice this is populated with your changes. Everything above is a GUI over the top of this spec file. That said, there are still a few things to edit here:

  • tags, which accepts a list of strings these words should describe your component and serve the purpose of making it easier to find through search;
  • image, which takes a string URL pointing to an image that will be what; 
  • element, which takes the element type for your component like div, svg, input, etc.;
  • class, which sets the class for applying css to your component; and
  • dependencies, where you will load necessary dependencies.  


Take a look at the component spec setup articles in the Component Authoring section for more help with this.

 That's it for creating a new component. Go put your new knowledge to use and build a component! 

Or, if you're trying to edit a component, you'll arrive at the Component Editor from one of three places. 

From the DATAFLOW by clicking the edit icon on your component: 

 
From the studio, by clicking the edit icon here:

 

From the component dashboard, by clicking edit here: