KRL Tutorial

From KynetxDocs

Contents 1 Getting Started 2 Building Your First App 3 Create a Development Endpoint 4 Load Your Card Into Azigo 5 Test your endpoint 6 Create your Production Selector Card Endpoint 7 Using KAB 8 When Things Go Wrong 8.1 Firebug 8.2 Internet Explorer Developer Toolbar 8.3 Logging

Getting Started

1. If you haven't already, Sign up for an AppBuilder account. After signup, a confirmation will be sent to the email address provided. Clicking on the link will take you directly to the AppBuilder login page.
2. Download and install Azigo. For this tutorial, you will be using the Azigo card selector as your endpoint. Download and install the AzigoLite card selector. Azigo has clients for both Mac OS X and Windows.

Building Your First App

In this section we're going to build a simple application that places an alert on an external web site whenever someone visits with a particular URL

1. Open AppBuilder and log in using the credentials you received when you signed up for an AppBuilder account.
2. Create an application under your account
   1. Click the "New App" button in the upper left hand corner
   2. Choose a name and description for your application. These fields are 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 and description can be freeform and does not have to be a valid KRL identifier.
   3. Click on the "Create" button to generate your App.
      
3. Edit the application.
   1. Next, you'll be taken to the screen for editing the application meta data
   2. You will see the name and description of the App that you entered on the previous screen inside the meta data editor.

      name "Tutorial"
      description << 
        Simple notification app 
      >>
      author ""
      logging off
      

      Your screen should look like:

      

      Context sensitive help is available via the blue Help button on the right of the AppBuilder interface.

4. Click on the dispatch button on the left. A text area for editing the dispatch section of the application will appear. Add the following:

   domain "baconsalt.com"
   

   Then press "Save". The dispatch section can be used to route ruleset evaluation to an alternate ruleset based upon simple matching criteria. For our example, we will keep this section simple.

5. We're going to create a simple rule that places a notification on the Bacon Salt homepage when we visit.
   1. Click on the "Rules" button on the left and click the "New Rule" button.
   2. Pick a rule name (say "my_first_rule"). This name must be a valid KRL identifier.
   3. Some text will already appear in the editor. It should look like this:

   select using "" setting ()
   noop()
   

   4. Inside the quote marks that follow the words "select using," enter the following:

      http://www.baconsalt.com/
      

   5. Leave the parens next to the word "setting" empty.
   6. Next, replace the "noop()" action with the following rule code:

      notify("Hello World", "Everything should taste like bacon")
      

   7. Make sure the "Rule Active" check box is checked and press "Save". You'll see something like this:
      

      A brief note on rules:. Every rule must contain a selector and an action. For more information on rules and additional optional rule parts, see here

      Also note that the rule you just created has its own button on the left menu.

   A note on versions: Every time that you save within AppBuilder, your application is saved to the Kynetx Rules Engine (KRE). This creates a new version of your application and allows you to test your app before deploying to production.

   
   You have now created your first Kynetx application. Before you can use it, you must continue to the next step and create an endpoint.

   Create a Development Endpoint

   1. Click the "Test" button in your left menu.
   2. Select "Test InfoCard" from the menu.
      • AppBuilder will insert a default image and name for your Info card (can also be called an Action Card).
        
      • (Optional) If you would prefer, you can rename the card and/or upload your own custom card image from the Manage->Image menu choice.
        

        Any image you like will do, but you should resize it to be at most 240x180 pixels--otherwise the card will be too big to display properly (You may need to refresh your browser after you upload to see your new image).

   3. Once you have loaded your custom image in the "Manage" menu, go back to the Test>Test InfoCard menu choice and press the "Make Test Card" button. Save your card as a file and then import it into the Azigo selector. You can repeat the "Make Test Card" process many times if you need to change the image or name of the information card.

   Load Your Card Into Azigo

   1. Start the Azigo selector from the "Start" menu in Windows or the "Applications" folder in OS X and import the card you just saved.
      Mac OS
      
      
      Windows
      
   2. Select the card and ensure that it's "on" (Mac) or "Enabled" (Windows).

   Test your endpoint

   Try it out by going to http://www.baconsalt.com/ You should see a dark grey notification box containing the message we put in the notify action in the upper right hand side of the BaconSalt homepage that fades away after a few seconds like this:

   

   
   

   Create your Production Selector Card Endpoint

   1. Set the Production Ruleset
   1. Click the "Deploy>Deploy" menu choice

   A Brief Note on Versioning
   Kynetx has introduced the concept of a Production and a Development ruleset. These require two separate endpoints. The development endpoint always uses the most recent ruleset. Kynetx defaults the card names for these test cards to cname+dev. For production, AppBuilder requires you to Activate your production ruleset. This allows the developer to modify and test rulesets without affecting existing users. When you enter the Deploy screen, you will see a list of versions from oldest to newest. From this screen, click on the "Deploy" link next to the version you would like to push live to production. Only one version of your app can be live on production at a time. The word "Production" will show up next to the app this live on production at the time you are viewing the Deploy screen.

   

   
   

   2. Next click on the "Distribute" menu choice on the left menu.
   3. Select "InfoCard" from the options.
   
   4. Press the "Make Card" button. If you are interested in distributing this information card to other people, you should save your card as a file and then import it into the Azigo selector. You can repeat the "Make Card" process many times if you need to change the image or title of the information card.

   Congratulations! You have created your first application using KRL! You can send this Kynetx Application Card to your friends and family so they can share the joy of Bacon Salt. This application might be a little silly, but with the power of Kynetx Network Services (KNS) and KRL you can provide a whole new purpose-based Web experience to your customers.

   Using KAB

   When Things Go Wrong

   Debugging a ruleset that isn't doing what you want requires understanding where things can go wrong and systematically eliminating each as a cause.

   Firebug

   Firebug, a Firefox plugin, is a valuable tool in debugging KRL. We'll assume you have it installed and at least have a passing familiarity with it's operation.

   The most obvious cause of a ruleset not firing is that it's not being called in the first place. Using Firebug, look at the bottom of the page source. KBX should have inserted tags at the bottom of the body of the page. The first tag configures the call and then a call to the shared runtime on init.kobj.net. This should be followed by a call to cs.kobj.net for the actual ruleset evaluation. Here's an example.

   
   

   

   If you don't see tags, then the card is not activating on the page you're looking at. The most likely cause is that the ruleset dispatch declaration does not include the site URL.

   Internet Explorer Developer Toolbar

   Developer Toolbar Microsoft's Developer Toolbar provides a debugging interface similar to Firebug in Firefox. This is a convenient way to view the changes that KNS inserts, rather than the cached source that IE Explorer normally provides.

   

   Logging

   You can add the pragma logging on to the meta section of the ruleset and the Javascript returned from the ruleset evaluation will include debugging statements. You can change on to off when you no longer want the debugging data included. To view the ruleset evaluation Javascript, use Firebug to view the script tag from cs.kobj.net.