Need help with pebbles?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

129 Stars 5 Forks 21 Commits 4 Opened issues


Actionable Javascript Library for 0-line AJAX interactions

Services available


Need anything else?

Contributors list

Docs at

Goals of Pebbles: * so easy that a designer could write complicated AJAX! * 0 lines of javascript * complicated ajax websites * 0 lines of javascript * no bugs * 0 lines of javascript * very fast speed and optimality. * backwards compatibility with clients who have javascript off (this was more important 4 years ago when I first made this)

Plus, you don't even have to write one line of javascript!

The basic idea is that almost every complicated AJAX interaction can be reduced to a handful of fundamental actions which can be composed (remind you of UNIX?). So, all a programmer has to do with this library is add few lines of HTML to elements of a page to describe the Pebbles response that happens when someone clicks that element. Maybe you submit a form, maybe you fetch some content and update part of the page.

Most current website write and rewrite slightly different versions of these same basic patterns in javascript. This separates the HTML which has information about AJAX interactions and the Javascript which has other information.

Javascript can be tricky to write even for an experience programmer. Moreover, a lot of this stuff is repeated, and it shouldn't be. Pebbles brings more of a descriptive style programming (a la Haskell, Prolog) to the web in the simplest of ways.


  • Couldn't you just write javascript functions that you call that do the same thing?

You might but then you introduce the opportunity of syntax and other programming errors, thus not achieving 0 bugs. In practice, this library is so straightforward to use that once you define a complicated action, which only takes a few seconds, you can move it around and it just always works.

Moreover, it's easier to auto-generate correct readable html (e.g. from Django templates). Many of your pages won't need any javascript even if highly dynamic. All the custom logic is in one place rather than spread over the html and the javascript. Basically, writing javascript is harder than what amounts to a DSL in HTML.

  • I need more complicated action-handlers than just these 3, can you please make them?

The code is open source and on Github on jperla/pebbles. Feel free to add your own enhancements. Be careful because you want to keep your app simple, and, in my experience, these 3 actions comprise the vast majority of user ajax paradigms. With a little thinking you can probably do what you want using either "form-submit" or "replace" with the right response html.

Technical Documentation:

Pebbles accepts spinner url (to an animated gif of a spinner for waits). Pebbles sets up a live listener on divs with classes of type "actionable".

Classes of type actionable contain a hidden div which has class "kwargs".

.actionable .kwargs { display: none; }

kwargs div contains a number of html elements, each with a name and value. The name is the key name, the value is the value for that key. In this way, in HTML, we specify a dictionary of keyword arguments to the actionable.

Here are some self-explanatory examples:

Show me the money!

Set happy

<!-- unmodified existing form! -->

show full comment
show full comment

It fails loudly if misconfigured. It's hard to write buggy code and not notice in quick testing. It is easy to do everything right and it is easy for you to write a complex ajax website with no extra javascript code.

Full arguments are below:

Arguments: type: replace, open-close, submit-form replace replaces the target with the url open-close will toggle hide/display the target, which also may dynamically lazily load content from an url submit-form submits a form via ajax which is a child of the actionable, or may be specified in form argument; the response of the ajax replaces target

url: url string of remote page contents

target: CSS3 selector of element on page to update

target-type: absolute, parent, sibling, closest, or child-of Absolute just executes the target selector in jQuery. Parent executes target selector on jQuery.parents(). Sibling the same on siblings. Closest looks at children and children of children and so on. child-of looks at target's children

closest: selector used in combination with target-type:child-of to get target's children form: selector used in combination with type:submit-form to find the form

If you use the open-close type, then the actionable can have two child divs with classes "when-open" and "when-closed". Fill when-open with what the actionable looks like when the target is toggled open (for example, a minus sign), and fill when-closed with what the it looks like when the target is toggled closed (for example, a plus sign).

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.