TIBET

Lama™ (In-App IDE)

NOTE: We're redesigning the Lama UX documented here to reduce the UX footprint of the HUD component while retaining Lama's key features.

NOTE: In early documentation and videos the Lama was named 'Sherpa'. Sherpa is now the name of our standalone DevOps REPL.

Wins

• Interactive, top-down development with zero reload/compilation downtime.
• Extremely fine-grained editing focused on tags and their functionality.
• Add new tags, types, and more without leaving your running application.
• Source edits automatically sync between client and server without reload.
• Extensible development library supporting new inspectors, editors, etc.

Contents

Concepts

• Loading
• Show/Hide
  
  
• The Dispenser
• The Halo
• The HUD
  • The Structure Tool
  • The Style Tool
  • The Responder Tool
  • The Bind Tool
• The Inspector
  
  
• The TIBET Panel
• The Layout Panel
• The Settings Panel
• The Changes Panel

Cookbook

Code

Concepts

Built to provide immediate, immersive feedback to speed your development, Lama™ leverages the TIBET platform's unique features to support a "prototype-to-production" development flow.

Unlike traditionally file-centric tools, the Lama is a tag-centric IDE.

Development in the Lama centers on adding, removing, combining, and editing tags and their backing types.

This process is facilitated by a small set of tools that are unique to TIBET and the Lama:

• The Dispenser
• The Halo
• The HUD
• The Inspector

The Lama includes a number of other tools you should also be familiar with:

• The TIBET Panel
• The Layout Panel
• The Settings Panel
• The Changes Panel

Each of these tools are covered in detail in the concepts section of this document.

NOTE: while TIBET is server-agnostic many of the features of the Lama (type creation, build, deploy, etc) rely on the TIBET Data Server or TIBET Desktop to work correctly.

The Lama is not a browser extension or native application, it's a TIBET application composed of lama-namespaced TIBET tags which load whenever you load a suitable boot profile.

Once loaded, the Lama creates one or more iframe elements to contain your application and any screens you may be editing. This approach lets you work in true MVC fashion on several pages of a wizard simultaneously for example, dramatically speeding development.

Edits you make in the client via the Lama can be applied temporarily to the client for review and testing then either reverted or pushed for permanent storage.

Edits you make on the server are propagated to the client and can be applied without reloading the page or flushing client-side data. Server-side changes can be applied immediately or TIBET can queue changes for review and selective import. You're in control.

With the Lama you build your application interactively, from the top down, adding detail to your tags with each iteration, working with a running application the entire time.

Loading

The Lama is loaded when you launch an application profile which includes the Lama tag set. This is the default behavior when you launch a standard TIBET project using a development@developer profile. (See TIBET Loader for more on boot profiles).

http://127.0.0.1:1407#?boot.profile=development@developer

When starting an application with the Lama the initial display will be identical to your normal application display with one exception -- a small TIBET logo will appear in the lower-right corner of your application:

While it may not be visually apparent, the Lama actually "contains" your application.

On startup, all TIBET applications run by virtue of a <tibet:root/> tag. If the Lama tag set is loaded and enabled (TP.sys.getcfg('lama.enabled') is set to true) the <tibet:root/> tag renders a <tibet:lama/> tag rather than your application home page.

When it renders, the tibet:lama tag generates tags for its top-level tools and one or more iframe elements used as 'screens' or 'pages'.

In the preview edition of the Lama only one screen is active. Future versions will support developing across multiple Lama 'screens'.

Show / Hide

Clicking the TIBET Logo at the lower-right of your application will toggle display of the Lama's HUD and other tools. You can also use Alt-UpArrow as a keyboard shortcut to toggle the Lama's display to give you a clear view of your application.

You can minimize the extent of the vertical sidebars using the small circled-arrow icons at the top/bottom of each sidebar. The result is a fairly minimal "frame" around your application:

The Dispenser

The Lama is designed to support a "top-down" or "prototype-to-production" development model. This design is most apparent when considering the Lama's Dispenser…a feature that lets you create new tags "out of thin air".

In the image below the Dispenser is the small white rectangle with the dotted top edge at the center of the Inspector Toolbar:

Dragging out a new tofu element shifts the display to show you the outlines of the various elements you can target. If you change your mind press Esc to cancel the operation.

Targeting in a visual DOM can be tricky since your target element may not have an easily visible representation, it may be too small, or it may be covered by other elements.

To target "difficult" elements just hold down the Control (Ctrl) key and the display will rotate as you drag, allowing you to drop into elements that otherwise might be inaccessible. You can also target occluded elements by dropping directly into the HUD Structure/DOM tool (the top-left sidebar in the image below):

Once you drop the tofu element in your desired location one of two things will occur.

If you dropped into a computed tag you'll be presented with that tag's tagCompile method so you can edit the method responsible for producing the "macro replacement" element(s).

If you dropped into a templated tag a dialog will prompt you for information about the new tag you want to insert in the tag's template.

For templated updates the Lama automatically locates the proper position in the targeted template and updates it, letting you edit template files directly via drag-and-drop.

In keeping with the "prototype-to-production" approach TIBET and the Lama do their best to follow a "teach me" model when it comes to development rather than a "scold you" one.

Entering a non-existent tag name in the new tag dialog does not trigger an error, instead it causes the system to render a placeholder element:

This kind of response to new or unknown information is a central theme of TIBET's design. Rather than throwing an error Lama will often simply prompt you to teach it about the new tag, type, test, or other element you intend to build.

Once the placeholder is rendered clicking the link it contains will open a new panel to let you define your new tag's specific details:

Once you define your new tag's details click 'Create' to build it.

TIBET will automatically generate a new tag type, patch your application's load package, load the new tag, and replace the tofu placeholder with your new tag.

What you see will vary based on the supertype you choose for your new tag. For example, inheriting from a button type will result in a default rendering of that button type.

One more thing…

That :type command? It's actually a client-side transformation of the TIBET CLI type command. In other words, if you substitute tibet for the leading : you can enter the exact same command from a terminal in your project to accomplish the same goal:

$ tibet type --name='APP.hello.world' --supertype='TP.core.TemplatedTag' --dna='templatedtag'

working in: /Users/ss/temporary/hello/_world_
processing directories...
processing templates...
templating complete...
positioning files...
positioning complete...
adjusting package entries...
<package src="~app_tags/APP.hello.world/"/> (added)
New configuration entries created. Review/Rebuild as needed.
Cleaning up working directory.
Type DNA 'templatedtag' cloned to ~app_tags/APP.hello.world as 'world'.

This is, in fact, how the :type command works…it marshals a request to the TDS to run that command line on your behalf. When the command completes the changes it triggers cause the Lama to automatically load your new tag just like any other server-side changes.

This is just one example of the power of using a fully-integrated library but it also points out another key feature of TIBET: nearly everything you can do from the Lama can also be done from the command line or your favorite editor. Thanks to TIBET's controlled approach to change processing you can switch to whatever tool is most productive for the task at hand.

The Halo

The Halo is the Lama's answer to "inspect element", providing both a focal point for your development as well as a number of other helpful features.

Halo display is toggled by the "boxed A" icon on the Inspector Toolbar, via Shift-RightClick, or by clicking an element in the Lama's DOM sidebar.

As you select elements with the Halo the Lama's HUD sidebar panels will automatically show you DOM structure, style rules, signal responders, and data bindings for $HALO.

For example, in the image above we've selected an <html:div> a child of the hello:app tag, itself a child of the html:body, which is a child of the html:html element. This div has several span and p child elements, two style rules, three signal responders, and no binds.

You can also manipulate the current $HALO element via a context menu. To activate the Halo context menu simply right-click inside the Halo.

Like all of the HUD, the Halo context menu is truly context-sensitive, getting its display and functionality by querying the tag type being inspected.

The Lama is a reflection-driven tool whose "customizations" are simply the result of method implementations on tag types. Implement those methods on your tags and the Lama will "customize" itself to your tag sets.

With respect to the Halo context menu, a few options are typically available for all tags:

• Inspect: Focus the Inspector on this element's type.
• Empty: Remove any child content.
• Delete: Remove this element from the DOM.

Tag Creation

Tag-driven development in TIBET with the Lama is a top-down process with drag-and-drop simplicity, not one driven by cumbersome code-compile-reload cycles.

With the Lama loaded and active you can create tags "from thin air" or from existing elements in the page. Creating new tags from scratch lets you build out new functionality in a prototyping fashion. Coalesing existing tags lets you refactor your UI as you go.

from thin air…

Drag a new "tofu" element from the inspector's lower toolbar and drop it in your page where you envision the new tag. The tofu dispenser is the white rectangle with the dotted top edge at the bottom center in the image below:

Dragging out a new tofu element shifts the display to show you the outlines of the various elements you can target. Hold down the Option key and the display will rotate as you drag, allowing you to drop into elements that otherwise might be inaccessible. You can also drop the tofu element into the Lama's DOM sidebar either onto or between elements (the top-left HUD sidebar in the image below):

Once you drop the tofu element in your desired location one of two things will occur. If you dropped into a computed tag context you'll be presented with that tag's tagCompile method for editing. If you dropped into a templated tag context a dialog will prompt you for information about the new tag insertion via the "New Tag" panel:

Entering a non-existent tag name in the new tag dialog does not trigger an error, instead it causes the system to render a placeholder like the following one:

This kind of response to new or unknown information is a central theme of TIBET's design. Rather than throwing an error TIBET will often simply prompt you to teach it about the new tag, type, test, or other element you intend to build.

In this case you can define your new tag and click 'Create Type':

Once the tag has been created the new type's code will automatically load, replacing the tofu placeholder with your new tag. Note that what you see will vary based on the supertype you choose for your new tag and its implementation of tagCompile.

from existing elements…

Start by using the Halo to select the root element for your planned tag's template. The Halo display is toggled by the "boxed A" icon on the inspector's lower toolbar, via Shift-Right-Click, or by clicking an element in the Lama's DOM sidebar.

Right-click inside the Halo to bring up the Halo's context menu and pick "Make Custom Tag".

As with the 'from thin air' case, you will be presented with the 'Type Assistant' dialog (shown in the 'thin air' example) so you can describe your new tag's supertype, namespace, etc.

Once your type has been created your Halo'd selection will be replaced with a version of the newly created tag, fully rendered and ready for additional alteration via the Halo.

Tag Modification

As you select elements with the halo the Lama's four core HUD sidebar panels will automatically show you DOM position, style rules, signal responders, and bindings.

For example, in the image below we've selected an <html:div> which is a child of the app tag, itself a child of the body, which is a child of the html element. This div has four style rules applied to it, 3 responders, and a data binding reference:

Selecting elements in a sidebar will trigger a context-sensitive operation:

• Clicking a DOM element causes the halo to focus that element.
• Clicking a style rule will take you to that rule for editing.
• Clicking a responder lets you view handlers on the responder.
• Clicking a binding reference lets you adjust data bindings.

Each operation is context-sensitive and any edits you make can be applied immediately without reloading, allowing you to work quickly and interatively.

You can also use the halo's context menu to access common operations like inspecting the tag's type, emptying it, removing it, etc.

Future versions will allow you to perform true "GUI builder" operations on the element such as cloning, resizing, styling, and so on.

Thanks to the halo and HUD the Lama keeps your development focused on your tags, their structure, their style, and their behavior.

Make Custom Tag

One of the more interesting options is "Make Custom Tag", which allows you to use the current selection's DOM structure to populate a new tag template.

Using "Make Custom Tag" is easy. Just use any of the Lama's selection options (the HUD structure tool, the Halo tool, a "fence" operation) to select the target elements, then right click within the selection halo:

As with the 'from thin air' case, when creating a new tag type via the context menu you will be presented with the 'Type Assistant' dialog (shown in the Dispenser discussion) so you can describe your new tag's supertype, namespace, etc.

Once your type has been created your Halo'd selection will be replaced with a version of the newly created tag, fully rendered and ready for additional alteration via the Halo.

You can disable the Halo by clicking the Halo icon on the Inspector Toolbar or by using Shift-Click anywhere in the UI.

The HUD

The Lama's heads-up display or HUD is a central part of your development process. The default HUD configuration consists of four primary tools:

• The Structure (DOM) Tool
• The Style (CSS) Tool
• The Responder Tool
• The Bind Tool

The Structure (DOM) Tool

The top-left panel in the HUD displays a sparse view of the $HALO DOM structure:

The left-justified items in the structure tool represent the ancestors of the element, down through the currently Halo'd element. The indented items represent the direct children of the selected element, making it easy to navigate up and down through the DOM quickly.

The current element is always highlighted in gold, while the element's offset parent (useful for CSS positioning reference) is shaded in peach.

Hovering over any tile will cause the corresponding element in the DOM to highlight.

Clicking any element will shift the Halo to that element and trigger a HUD update.

Double-clicking a tile causes the Inspector to open and focus on the $HALO object, providing access to the node, its underlying type, its template (if any), its style, and more:

Right-click'ing on a tile will trigger display of a dynamic "helper" which allows you to add, remove, or alter any attribute values on the target element or to alter its text content directly:

You can also use the Dispenser with the Structure tool. By directing the Structure display to a particular location you can then drag-and-drop from the Dispenser into either a tile or a space between tiles to create new elements with a very specific DOM ancestry.

The Style Tool

Like the HUD Structure tool, the HUD Style tool displays real-time information about the current $HALO, in this case all style rules applied to the current target.

As with the Structure tool, hovering, clicking, double-clicking, and right-clicking a particular tile in the Style tool will trigger specific operations relative to the style rule selected.

In the image below we've selected hello|app in the Style tool in the lower left HUD panel and right-clicked on that tile to display the rule's property helper which allows us to view, remove, add, or edit individual style declarations:

As with all HUD "helper" panels, once you open a helper you can move it to any location to avoid having it intrude on the UI you're manipulating. Click the close icon at the top right corner of any helper panel to close it.

You can double-click on a style rule tile to open the stylesheet responsible for that rule in the Inspector, scrolling the file in the editor to the start of the rule:

As you might imagine, editing in the Inspector can be somewhat limiting so you can use the editor-specific portion of the Inspector Toolbar (the right-hand section) and select the small circled arrow icon to pop the editor out into a persistent tab in the Console.

In the image shown above we've collapsed the Inspector and resized the Console by dragging the Console border upward so we can view more of the stylesheet while also viewing our content.

Resizing the Console only works when you've opened it via the expand/collapse icons. When it's in single-line mode the Console will not respond to resize requests.

As with all editors in the Lama, as you edit content the Apply, Push, Revert, and Refresh buttons will enable and disable appropriately.

For example, when there are no differences between client and server state all buttons will be disabled. Once you change content the Apply and Revert buttons will enable. Only after you Apply local changes will Push become active, and so on.

As you make changes the Lama's Changes Panel will update (lower right corner) to show a count of the client-side URIs you've modified but haven't pushed to the server. Server side changes you haven't applied are also shown in the Changes Panel.

The Responder Tool

Located in the upper-right section of the HUD, the Responder tool displays the current list of signal responders for the selected $HALO.

If you're not familiar with TIBET's concept of signal responders you should check out the TIBET Signaling documentation, but in short, a responder is a tag or controller type along a particular signaling chain. Responders are never nodes, they're always a TIBET type, a type which lives outside the DOM so it can span screens as needed.

In the image below we see the $HALO has three responders: the tag type, the current route controller, and the current application controller. Colors help differentiate tag types from controller types.

Using the Responder tool you can quickly add signal handlers directly to a tag, to an attached tag controller, to the current route controller, or to the top-level application controller as needed. Adding responders does not require reloading, attaching, or detaching event listeners.

Right-Click on the desired responder to open the Responder's helper which allows you to browse the existing handlers on the current responder or to add new ones:

Let's add a new one now….

With the helper open, click the "Add" button in the lower right corner of the helper. If the helper isn't open double-click the tile to open the Inspector and click the Add button there:

Using either responder Add button will open the Method Assistant:

In this case we're adding a new responder to the APP.hello.app type, the type responsible for our hello:app tag. In particular, we're adding a handler for UIActivate, the signal TIBET fires on click or keyup, so we can test easily with just a Click.

Once the new handler has been added it will show up in the Inspector, ready to edit:

Edit the content of the new handler to something simple and click Apply:

APP.hello.app.Inst.defineHandler('UIActivate',
function(aSignal) {
    APP.info('Hello World!');
});

Once the new handler has been "applied" (patched into the running application's client-side code) all we have to do is click within the scope of the responder, in other words, click anywhere within the boundary of the hello:app tag:

With a few mouse clicks and a very focused bit of editing (without having to search through files) we've added new behavior to all hello:app tags and done it without any requirement that we reload or lose context. Once our handler works as we desire we can use 'Push' to save our final version to the server.

Changes you save from the client are sent to the server in diff format and patched into your original source files. You can then choose to commit or revert these changes in git or your particular source code control system.

If we've navigated away and want to make changes to our handler we can always double-click the target responder to open the entire list of handlers it supports in the Inspector:

Clicking a specific handler will cause it to open an editor just like the initial creation cycle did, allowing you to change it as needed. You can use the 'Apply', 'Push', 'Revert', or 'Refresh' buttons to control which edits you preserve and which you discard.

The Bind Tool

The final HUD component is the Bind tool found in the bottom right of the HUD.

The Bind tool, like all other HUD tools, queries the current $HALO for any bind attributes in scope and displays them along with the elements they're attached to.

To see this in action let's add a bind attribute now.

In this case we'll use the Structure tool to select the html:h1 element below our application tag and open the DOM Helper so we can add a binding attribute to our h1:

As discussed in the TIBET Binding documentation, TIBET uses attributes in the bind namespace to define data bindings. In this case we're dealing with a read-only element (an h1) so we'll use bind:in to point to a TIBET URN which will hold the data we want the element to display:

Note that as soon as we've added the binding attribute we see a new tile in the Bind tool, signifying that the html:h1 has at least one binding attribute on it. If other elements in the h1 element's ancestor chain contained bind attributes we'd see them represented as well (this is common when using bind:scope attributes to create scoped binding contexts).

With the Bind tool ready, closing the DOM Helper and double-clicking the html:h1 tile in the Bind tool will bring us directly to an editor on the content of the URL we bound the h1 to:

In this case we can see that the h1 still contains its original data, the bind hasn't refreshed yet. But enter Hello World! as the content of our URN and click Apply and you'll immediately see the h1 update to reflect the bound data value:

As discussed in the TIBET Binding documentation, all binds in TIBET target URIs. TIBET URIs serve as intelligent containers for data and support a variety of XPointer schemes meaning you can query them via XPath, JSONPath, or TIBET-specific path syntax.

URI instances, particularly TIBET URN instances (URNs using the urn:tibet: prefix), also serve as ValueHolders (named models), letting you alter their value from code with ease.

To demonstrate, let's update the content of urn:tibet:hello. We'll enter the following command and use Shift-Return to execute it:

TP.uc('urn:tibet:hello').setContent('Where\'s fluffy?');

As soon as the command completes you'll see the h1 change value in response as well as the editor content for the URN displayed in the inspector:

Using the Bind tool lets you quickly manage both your binding scopes and your bound data, letting you interact with both directly from the UI.

The Inspector

We've interacted with the Inspector a number of times while covering the Halo and HUD.

With the Inspector you can browse, inspect, and edit a wide variety of targets including TIBET, your application, local/session storage, remote stores like CouchDB, and much more.

The Inspector's roots may change, but the fundamental components remain consistent:

• A top "path" component providing Home, Back, Forward, and Bookmarking controls as well as a display of the currently focused path. Depending on the context, items in the path may be dragged out and used just as you would use the Dispenser:

• A central "navbay" control for browsing through hierarchies of objects, data, etc. This control also has "next" and "prev" controls in the form of circled arrow icons at each end. The content of each bay is acquired by querying the selected item for its inspector content, allowing the tool to adapt to virtually any content, including your custom content:

• A "toolbar" (aka the Inspector Toolbar) with a fixed left-side set of controls and a context-sensitive right-side set of controls. As with the navbay segment, the content of the dynamic portion of the toolbar is acquired by querying the selected item. In the example below we've selected a Type which has provided us with an icon we can use to run that type's tests:

The variety of panels available in the Inspector is essentially unlimited, but to give you an idea of what else is possible consider this sample, which lets us log in to CouchDB:

…and then browse it directly, allowing us to look at documents, views, and more:

In the example above we're browing the tasks database typically used by the TIBET Workflow System (TWS) and browsing the views which provide access to the flow, task, and job documents used by the TWS. Future versions will support full CouchDB administration and editing.

The Inspector Toolbar, particularly the 'fixed' section, provides quick access to common operations through a drop-down menu and a fixed set of controls.

We've already seen the Dispenser and the Halo controls in action.

To the left of the Halo is the 'outline' control, the small paired angle-bracket icon, which lets you toggle the display to show each element's outline:

Working from the left-hand side we have the Toolbar's Menu, Test, Build, and Deploy buttons:

The Test, Build, and Deploy buttons trigger the :test, :build, and :deploy commands respectively, while the dropdown menu provides access to commands covering a variety of operations common during development:

Lama Panels

To make the most of valuable screen real estate the Lama leverages the "corners" of its display to keep a small set of useful tools accessible but largely hidden during normal operation.

Clicking the various corner icons of the Lama will cause each Panel to slide into view. Clicking it again will close the Panel. Here we've opened them all:

The TIBET Panel

The TIBET Panel, essentially an "About" panel, provides information about the current application in the lower toolbar as well as displaying the current TIBET version. It also provides quick access to provide feedback, sign up for support, or report an issue.

We encourage you to send us feedback on any issues, feature requests, etc. you may have, particularly during the Lama Technology Preview.

The Layout Panel

Currently disabled, the Layout panel at the bottom left, is a placeholder for adding, removing, and adjusting the layout of the screens and components in the Lama's display area.

As mentioned earlier, the Lama creates one or more iframe elements to contain your application's "screens". The preview release of the Lama is limited to a single screen but future versions will allow you to work with multiple screens simultaneously, a particularly powerful approach particularly when working on multi-page wizard interfaces.

In fact, the Lama actually creates a <lama:world/> tag to contain the screen tags it leverages. The Layout tool is designed to let you configure this "world" to define how screens, console output, and other components use your screen real estate.

The Settings Panel

Currently disabled, the Settings panel at the top right, will provide a control surface for altering Lama settings which affect its runtime operation.

The Changes Panel

The Changes panel is one of the more powerful and interesting tools in the Lama toolbox.

Located in the bottom right corner of the Lama, the Changes panel keeps a running tab on any URIs on the server which have values which differ from those in the client. This data is reflected in the two numbers circled in the panel header:

The left-hand number reflects the current changed server URI count while the right-hand number reflects client-side URIs which have changed.

Clicking on a specific number will open the panel if closed and then toggle the list display between server and client contexts so you can view the specific lists.

Server Changes

When you change a file on the server the TDS will push that information to the client. Based on your selection for 'Watch changes' and 'Process changes immediately' that file change will either be ignored, queued for review, or automatically hot-patched into your application.

Client Changes

When you make edits in the client, changing a template, a stylesheet, a type, etc. that information is tracked and displayed, even when the panel is collapsed:

Opening the Changes panel on the client list lets you view the specific URIs which have changed client-side and either push them all or selectively push them by hovering over the URI and selecting the "Push" button which appears:

The Changes panel is one of the more powerful ways the Lama helps speed development by letting you edit on either side of the wire and control how and when those edits are synced.

Summary

That concludes our overview of the Lama and its core features and controls. Look for more detail in the Cookbook section over the coming months.

In the meantime the best way to learn about the Lama is to see it in action.

Cookbook

The Lama is currently a "technology preview". Stay tuned for a full cookbook of recipies for using the Lama for production-level development as we bring it from preview to production-ready.

Code

Code for the Lama is found in ~lib/tools/lama and its subdirectories. (Recall that ~lib is the TIBET virtual path reference for the root of your TIBET library installation).

The Lama tag, <tibet:lama>, is found in ~lib/tools/lama/src/TP.tibet.lama.js. This is the tag injected by the tibet:root tag when it detects the Lama is enabled.

The core Lama controller is found in ~lib/tools/lama/src/TP.core.Lama.js. A number of other utility objects are also found in that directory.

The majority of Lama functionality is found in custom tags in the lama namespace. Most of these tags have their own directories below ~lib/tools/lama.

One thing to keep in mind when viewing Lama-related code is that the initial Lama implementation was done prior to a number of improvements to the underlying library so it's not the best example of current best practice.