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

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

• Overview
• What Happens When an Event Is Raised?
• Rules Are Simply Conditional Actions

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.

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:

domain "baconsalt.com"

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 (Classic) 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:

rule bacon_salt_rulz {
  select when pageview ".*" setting ()
  pre {
  }
  notify("Bacon Salt Rulz", "Everything should taste like bacon!");
}

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 (Classic) 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:

rule bacon_salt_rulz {
  select when pageview ".*" setting ()
  pre {
  }
  notify("Bacon Salt Rulz", "Everything should taste like bacon!")
    with sticky = true;
}

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:"

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:

meta {
  name "KRL Tutorial"
  description << >>
  author "Phil Windley"
  logging on
}

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

// ...
//------------------- begin rule execution: bacon_salt_rulz ------------------------
// 2012/02/24 00:02:38 DEBUG Rules.pm a16x144 bacon_salt_rulz Rule not pre optimized...
// 2012/02/24 00:02:38 INFO Rules.pm a16x144 bacon_salt_rulz fired
// 2012/02/24 00:02:38 DEBUG Actions.pm a16x144 bacon_salt_rulz blocktype is [every]
// 2012/02/24 00:02:38 DEBUG Actions.pm a16x144 bacon_salt_rulz actions list contains 1 actions
// 2012/02/24 00:02:38 DEBUG Actions.pm a16x144 bacon_salt_rulz [action] notify_two executing with args ('974474419',callBacks,{'rule_name' :'bacon_salt_rulz','rid' :'a16x144','txn_id' :'DC9DBED8-5E7A-11E1-A00B-3BAEBC28BD10','sticky' :true},'Bacon Salt Rulz','Everything should taste like bacon!')
// 2012/02/24 00:02:38 DEBUG Scheduler.pm a16x144 bacon_salt_rulz Rule name: bacon_salt_rulz
// 2012/02/24 00:02:38 DEBUG Scheduler.pm a16x144 bacon_salt_rulz Resetting schedule
// 2012/02/24 00:02:38 DEBUG Rules.pm a16x144 bacon_salt_rulz Finished processing rules for a16x144
// 2012/02/24 00:02:38 DEBUG AST.pm a16x144 bacon_salt_rulz Generating JS for a16x144
// 2012/02/24 00:02:38 DEBUG AST.pm a16x144 bacon_salt_rulz Generating resource statement for a16x144
// 2012/02/24 00:02:38 DEBUG Log.pm a16x144 bacon_salt_rulz [logging] Storing logging data
// 2012/02/24 00:02:38 DEBUG Log.pm a16x144 bacon_salt_rulz results for bacon_salt_rulz
// 2012/02/24 00:02:38 DEBUG Log.pm a16x144 bacon_salt_rulz TXN_ID: DC9DBED8-5E7A-11E1-A00B-3BAEBC28BD10
// 2012/02/24 00:02:38 DEBUG Session.pm a16x144 bacon_salt_rulz Cleaning up session
// 2012/02/24 00:02:38 INFO Response.pm a16x144 bacon_salt_rulz Event processing finished
// 2012/02/24 00:02:38 DEBUG Response.pm a16x144 bacon_salt_rulz __FLUSH__
// 2012/02/24 00:02:38 DEBUG Response.pm a16x144 bacon_salt_rulz Called with GET /blue/event/web/pageview/a16x144/13300411460428573224612046033?kvars=%7B%7D&caller=http%3A%2F%2Fwww.baconsalt.com%2F&referer=&title=Bacon+Salt&frag=&a16x144:kynetx_app_version=dev HTTP/1.0
// 2012/02/24 00:02:38 DEBUG Response.pm a16x144 bacon_salt_rulz Returning javascript from evaluation
// KNS Fri Feb 24 00:02:38 2012 (kib4.kobj.net)
KOBJ.registerClosure('a16x144', function($K) { (function(){(function(){function callBacks () {

};
...

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!