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.
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
- Open AppBuilder and log in using the credentials you received when you signed up for an AppBuilder account
- Click the "New App" button in the upper left hand corner
- 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.
- 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:
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:
- Change the name of the rule to
- Replace the parameters to the
"Bacon Salt Rulz"and
"Everything should taste like bacon!"
- 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.
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.
- Click on "Distribute" on the upper right-hand corner menu
- 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
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
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.
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:
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, you have just made your very first Kynetx app!