Your first assembly
The audience for the assembly editor are people with some technical knowledge, including HTTP, XML, and XPath .
Although no coding will be involved in building this first assembly, some technical knowledge is helpful. Still, we have had very non-technical people get up to speed and build assemblies on their own!
This first assembly will show how to build a little visual widget that will display the latest article titles from the CNBC news feed.
The goals are just to demonstrate the very basics of how assemblies are built with the editor.
Start with a new assembly. By default the editor loads with an empty assembly called "Unnamed (1)".
If you don't have an empty assembly to open, use the File menu at the top right and choose New:
The CNBC news feed is an RSS XML file that can be viewed in your browser at http://www.cnbc.com/id/100003114/device/rss/rss.html
We will load the feed to fetch the latest article titles and display them in a list.
First we need to fetch the XML data from that feed URL. The HTTP Transaction module can be used to do that.
How are you supposed to know to use the HTTP Transaction module? If you don't have a technical background and still want to build assemblies, the best way to learn is by example, which is to examine some of the existing assemblies in the catalog. Almost all of them fetch data in some form or another using a variation of the HTTP module.
Search the catalog for "http" and choose to search for modules. Modules are the building blocks for assemblies.
Lots of modules match the search. I'm experienced so I know that the HTTP Transaction module will let me fetch that news feed's data. Drag the module out of the catalog and place it near the top.
We choose "GET" as the verb and paste in the CNBC feed URL:
The assembly editor is a live editor, in that you need to execute modules and fetch data in order to configure and test the modules you need to use for the desired logic.
So we can now execute this one-module assembly. The easiest way is to double-click on the HTTP Transaction module.
The assembly engine will show progress as it runs. After the data is fetched, a preview will appear at the lower left of the editor.
Let's see what was loaded. Either click the magnifying glass icon in the module's title bar, or click the button shown to open the Stream Inspector:
You can now examine the full contents of the data that was fetched from CNBC. Observe that there are article titles:
Lets display those titles. Search for an "html" module in the catalog:
The HTML Renderer modules will do what we want. Drag it from the catalog and drop it under the first module.
Click and drag from the output node of module #1. A wire will appear, plus a wire node in module #2 will now appear:
Drag the wire and connect it to the input node in module #2:
Alternatively, you can click on the output node from module #1, then click on the input node in module #2
What is happening here?
The wire output from module #1 contains a single XML document, called a Data Stream in the editor.
But the input node for module #2 just needs a text value.
The editor recognizes the mismatch and knows that a text value needs to be selected from the Data Stream XML. So it is asking you to select an XPath to the text.
We saw that the articles had titles, so we enter title into the search:
The first one in the list is the article titles, so we select that:
The editor now shows the end portion of the selected XPath with a dark background. This indicates that a node from the Data Stream XML in the wire is being extracted and used for the input:
The XPath can be changed if needed by clicking on the text here:
Now click the Execute Assembly link here:
Then choose the default "assembly editor" option here:
Now we can see the results!
Ugh, all the title text is appended together. Let's make it pretty. We need to add newlines after each title so each title is on a separate line.
Disconnect the wire between modules #1 and #2 by clicking on one of its ends and letting go of the wire. Then drag module #2 down to the bottom to make some space.
We'll need to loop through each title to add newlines. Search for a "loop" module in the catalog and drag the Data Rows - Loop module under module #1 like this:
Note that the Loop module has a place where another module or subassembly can be placed.
To append the needed newlines to the titles, we'll need the Text Builder module. Search for a "builder" module in the catalog and drag the Text Builder module into the Loop like this:
Click the plus icon in the Text Builder twice. The first entry will be for the titles, the second will be where we enter the newlines:
Now we need to load the Loop module with data so we can configure it. Wire modules #1 and #2 together like this, then double-click the Loop module:
An error will occur b/c the Loop is not yet configured.
It needs to know which data rows will be looped upon. We want to process each article's title. Each article is an "item" node in the feed, so we search for "item" and select the first entry:
Now double-click on the Loop module again. Since the data rows is now configured, there will be no error and the Text Builder module will be able to be configured.
In the first line of the Text Builder, open its dropdown list and search for "title", then click the first result which are the article titles:
Then for the second line we want to append the newlines to the title. Since the output needs to be HTML formatted for the renderer module, we enter "<br/><br/>" which is two HTML line breaks:
Now we need to configure the Loop so it will overwrite the previous title text with the output from the Text Builder with the appended newlines.
Choose the "assign results to" radio button, then again search for "title" and choose the first entry which is the article titles:
Now let's check our work. Double-click on the Loop to run the assembly and open the Loop module's Stream Inspector. The HTML newlines should now be there:
Connect the Loop output to the Renderer like we did before, choosing the article titles:
Now click the Execute Assembly link as before and view the output:
Well, the titles are now on separate lines like we wanted, but why are those commas there?
It is being caused by the way we wired the output from the Loop into the Renderer's text field. The system knows there are multiple titles being put into a single text field, so it tries to be helpful by separating multiple items with commas. Sometimes those automatically inserted commas are helpful, but not for us in this case.
Let's fix that. We need a way to concatenate all the title text in those multiple <title> XML nodes into a single XML node. We will do ourselves what the system is doing for us automatically, but without those commas. Unwire modules #2 and #3, move module #3 down lower to make space, search for a "concat" module in the catalog, then drag the Data Nodes - Concat Text module here:
Wire the output from the Loop #2 into the Concat module #3, double-click module #3 to load it with data, then configure it like so:
Double-click the Concat module #3 to load it with data and open its Stream Inspector. At the very bottom will be its output, all the titles concatenated together without any commas between them:
Now wire the output from the Concat module #3 into the Renderer and search for "concat" which has the output from module #3:
Execute the assembly again. There we go, now all the titles appear like we want:
The finished assembly can be saved now:
After it is saved, you can now execute the assembly in a new browser window, where the article titles will now appear in their own web page:
Congratulations, you should now have a basic understanding of the mechanics of building assemblies!
To become proficient with using the assembly editor to build solutions, your journey is to learn about the system's most commonly used modules (you'll probably use a couple dozen most often, not all 250 or so) and the patterns of assembly implementations for automation apps, triggers, and actions.
