This site has been deprecated. Do not edit pages here. Please visit the new Pico Labs documentation.


Skip to end of metadata
Go to start of metadata
Deprecated

The methods described on this page are no longer supported in the KRL system.

Times, they are a changin'

The information here is based on the AppBuilder tool and the Kynetx browser extension, both of which are deprecated and will eventually stop working. You will likely want to follow the CloudOS app development instructions instead.

This page will get you started building KRL applications. After you've finished with this page, continue by completing the Live Web Exercises that go along with Phil's book The Live Web

The following may also be useful in continuing to use KRL:

Sign Up for AppBuilder

Although KRE is open source and you could install your own server, the easiest way to get started and build rulesets is to use the cloud-based service from Kynetx. 

If you haven't already, Sign up for an AppBuilder account. After signup, a confirmation will be sent to the email address you provided. Clicking on the link will take you directly to the AppBuilder login page.

Building Your First App

In this section we're going to build a simple application that places an Growl-like notification on an external web site whenever someone visits the site

  1. Open AppBuilder and log in using the credentials you received when you signed up for an AppBuilder account
  2. Click the "New App" button in the upper left hand corner
  3. Choose a name for your application. The name is for your reference only and is not used in any way other than to provide a description for you to organization your Apps. The name can be free-form and does not have to be a valid KRL identifier.
  4. Click on the "Create App" button to generate your App.
Here's what the "create app" dialogue looks like:

Next, you'll be taken to the application editor. You will see the name of the App that you entered on the previous screen inside the meta block:

Inside of the dispatch block, add the following:

Your screen should look like this:

Then press "Save".

For more information on how the dispatch section can be used, visit this page.

We're going to create a simple rule that places a notification on the Bacon Salt homepage when we visit. We can modify the rule that's already in the sample code (called first_rule). Do the following:

  1. Change the name of the rule to bacon_salt_rulz
  2. Replace the parameters to the notify() action with "Bacon Salt Rulz" and "Everything should taste like bacon!"
  3. Hit "Save."

When you're done, your rule should look like this:

Remember: Every rule must contain a selector and an action. 

Testing Your App

Now that you have coded your first KRL application, let's proceed to testing it. The best tool to use for the testing of your apps is a bookmarklet, and AppBuilder makes creating a test bookmarklet easy. Just click on Test. Drag the link that is titled "dev_KRL_Tutorial", onto your browser's bookmark bar:

Once you have put the link into your bookmarks bar, go to www.baconsalt.com and click on your bookmarklet. You should see a notification appear in the top right hand corner of the page:

If for some reason, no notification appears, see the section below about when things go wrong. Otherwise, be extremely excited! Because you have just made your first working Kynetx application! But before you go off and tell all your friends how awesome you are, there are a few more things to learn.

Action Arguments

You might have noticed that the notify() box disappeared shortly after you clicked the bookmarklet. This is the default action. To make it sticky, we can use an optional argument to the action by way of the with keyword:

Now when you click the bookmarklet, you should get a notification that sticks around.

You might have gotten two, or even three notification boxes if you clicked the bookmarklet multiple times without reloading the page. That's because the action actually modifies the DOM to contain the notification. When it disappears, it's simply hidden and the next notification will unhide it so that it's visible. 

Deploying and Distributing Your Application

Now that you have tested your application and found that everything is in working order, it's time to deploy your app to production.

The first step is to go to Deploy and deploy the application. This means, that you will be indicating which version of the ruleset should be the production version. Depending on how many times you've clicked Save you should see something like this:

Click the "Deploy" link on the latest version and you should see it say "Deployed."  

You can now install the app in your Kynetx Browser Extension (KBX). If you haven't installed a KBX yet, installing the app will install the KBX for you. 

  1. Click on "Distribute" on the upper right-hand corner menu
  2. Click the link in the section labeled "Listing URL:"
You should see this:
When you click the Install button, the app will be installed in you personal event network. Now when you visit the Bacon Salt Web site, the ruleset should modify the page without you having to click on the bookmarklet. 

When Things Go Wrong

If nothing happened when you clicked the test bookmarklet, there are some things you can do.

The more you understand about rule execution and the model the rules engine uses, the easier it will be to debug problem. The most important thing to understand for a Web page augmentation like the one in this quickstart is that the notify() action produces Javascript and that Javascript modifies the DOM. 

The first step is to check the domain declaration in the dispatch section to ensure it's correct. Note that a domain of baconsalt.com will also fire rules on any subdomain of baconsalt.com

We can ensure that the rule is firing, but looking at the page. In Chrome, we right-click and select "Inspect Element". In Firefox, you need to install and use the Firebug extension to see the current state of the DOM. At the bottom of the page, you should see <script/> tags that look like this:

If you don't see these tags then there is likely something wrong with the bookmarklet. Delete and reinstall it. 

If you do see these tags, then the question is what the rule did. Copy the link of the final script tag and paste it in a browser window. You'll likely see a screen of Javascript. T

You can get more detail about what the engine did by turning logging on in the meta section of the ruleset and then reloading the script URL. Here's what the meta section looks like with logging turned on:

When you reload the script URL, you'll see detailed logging of the rule execution along with the Javascript:

The above log shows a successful rule firing. The debug information can be confusing, but with time you'll come to understand it better. The key idea is to look to see if the rule was selected and whether or not it fired. If not, then the logging information can often be used to track down the problem.  

You can find more information about debugging KRL in the page on that topic

Congratulations

Congratulations, you have just made your very first Kynetx app!

Labels: