View on GitHub

Download this project as a .zip file Download this project as a tar.gz file

Prime JavaScript

Prime.js is a different kind of JavaScript framework. Prime is written in 100% standard, explicit, and namespaced OO JavaScript.

If you are looking for something like this:

$('.box .header').slideUp();

Prime is NOT for you. Prime is not terse and not flat. Prime is not about injecting code into a large hash and hoping it works.

On the other hand, if you love any of these things:

You will love Prime!

Getting Started

To quickly get started with Prime.js, add this to your web page:

<script type="text/javascript" src="http://inversoft.github.io/prime.js/prime-0.13.js"></script>

The latest version of Prime.js is 0.13.

We don't recommend using the github server to download Prime in production. Or using the full Prime.js file in production. Instead, you should minify this file before going to production.

Selecting

Selecting in Prime uses a static function in the Prime.Document namespace. Under the hoods this uses Sizzle, so if you are used to JQuery or other frameworks, it works the same. Here's an example:

var element = Prime.Document.queryFirst('.box .header');

The return value of this function is a new instance of the Prime.Document.Element class. You can also select multiple elements like this:

var elementList = Prime.Document.query('p');

The return value of this function is a new instance of the Prime.Document.ElementList class.

There are a few other selector functions in the Prime.Document namespace:

Like all of Prime, these functions are well documented and you should use our JSDoc to learn how to use them. If you ever see a function that isn't well documented, file an issue and we'll fix it.

ElementLists

The simplest usage of a Prime.Document.ElementList is to iterate over all of the elements. The each function makes this simple:

elementList.each(function(element) {
  // Do something interesting with the element
});

Element

The Element class is the basis of Prime. You use them to manipulate and traverse the DOM. Refer to the JSDoc for the Element class to learn about the functions we have already implemented. If you need a new one, suggest it on the mailing list or in the issue tracker.

Document Ready

Another common task is to register an event listener that is called when the document is ready. Here is how you do that with Prime:

function ready() {
  // Do something
}

Prime.Document.onReady(ready);

Or the inline method like this:

Prime.Document.onReady(function() {
  // Do something
});

AJAX

Prime has a class named Prime.Ajax.Request that supports all your AJAXy needs. You can even subclass the Request class to add your own event handlers and more. Here's a quick example of using the Request to make an AJAX request:

function success() {
  // Do something
}

new Prime.Ajax.Request('/some/uri', 'POST').
    withSuccessHandler(success).
    go();

Refer to the JSDoc to explore Prime's AJAX handling.

Context and this

We got tired of this being different things in every framework (or even in multiple places in the same framework). We decided it was time to make this consistent (or at least as much as we could). Since Prime is based on Objects/Classes, you can make Prime ensure that this refers to the current object.

Here is an example of using Prime.Document.Element inside a class to handle click events:

var MyClass = function() {
  this.element = Prime.Document.queryFirst('.some-class').
      addEventListener('click', this.handleClickEvents, this);
  this.message = 'Hello World';
};

MyClass.prototype = {
  handleClickEvents: function(event) {
    alert(this.message); // Says 'Hello World'
  }
}

Notice that when we added the event listener to the element we passed in the event name, the handler function and then this. What this tells Prime to do is ensure that when the event handler function is called that the this variable is correct.

Everywhere we could make this work in Prime, we did. All event functions take this third parameter.

You can even use or proxy handling for your own needs. Check out the Prime.Utils.proxy function to learn more.

Hacking

If you want to hack on Prime, your best bet will be to clone/fork the git repository. This contains all of the JavaScript files in the src/main/js directory. We link to jquery/sizzle as a submodule, so you will need to initialize and update this submodule located in the src/main/js/sizzle directory.

If you have Gradle installed and want to generate a single JS file, run:

$ gradle jar

Yeah, we know this doesn't actually JAR anything, but Gradle relies on the java plugin and we just went with it.

Gradle spits out the full Prime.js file at build/libs/prime.js. Copy this file into your web application (or symlink it). Once you have either the Prime JavaScript file copied into your project, insert the standard script tag in your header and you are SET!

<script type="text/javascript" src="/js/prime.js"></script>

You can also just use the individual Prime JavaScript files instead of the combined file. This will also require that you include the Sizzle JS file. The Sizzle file is located in the Prime.js project under src/main/js/sizzle/sizzle.js.

Credits

Prime.js is built by the developers at Inversoft. If you love working on cool code like Prime, we are always looking for great developers to join our team.

Learn More

Dive into the JSDoc for Prime.js and see what you can find. The JSDoc for Prime.js is located here:

http://inversoft.github.io/prime.js/jsdoc/index.html

Or if you need additional assistance, send a message to the Prime User mailing list here:

https://groups.google.com/forum/?fromgroups#!forum/prime-js-users