pakkajs

The idea is to provide few pakka simple UI tools. Inspired by http://youmightnotneedjquery.com/ and angularjs v1

Visit site

pakka

This can glue html and javascript seamlessly. (syntax is like angularjs v1)

Code is very small, simple and pakka.

For now see test.html for an example

Advantages

1. It is very light weight compared to any standard view-model kind of libraries.
2. Handles many view-model glue scenarions.
3. Simple to use.
4. Helpful for component/modular/widget based development.

Getting Started

Installation

Note: Pakkajs is dependent on lodash. So lodash also needs to be included.

Using npm

Install using following command.

$ npm install --save lodash pakkajs

Use it as follows:

var _ = require('lodash');
var pakka = require('pakkajs');

Using bower

$ bower install --save lodash pakkajs

Using in browser directly

<script src="/path/to/lodash/lodash.js"></script>
<script src="/path/to/pakkajs/pakka.js"></script>
<script src="your-script.js"></script>

Bootstraping

var app = pakka.create('#id-of-your-app');

or

var app = pakka.create({
    elementsSelector: '#id-of-your-app'
});

or

var app = pakka.create({
    elements: [document.body]
});

Creating components

var Component = pakka({
	html: '<span>your-html-string-here</span>', // assign your HTML as string, useful with requirejs
	css: '.your-css-string-here {}', // assign your CSS as string, useful with requirejs
	controller: function (context) {}
});

var item1 = new Component();
var item2 = new Component();

or if you want only single instance, then use pakka.create

var item = pakka.create({
	html: '<span>your-html-string-here</span>', // assign your HTML as string, useful with requirejs
	css: '.your-css-string-here {}', // assign your CSS as string, useful with requirejs
	controller: function (context) {}
});

Event handle

var Component = pakka({
	html: '<span eventName-handle="callbackPropertyName">your-html-string-here</span>', 
	controller: function (context) {
		context.callbackPropertyName = function(event) {
			// your event handling
		}
	}
});

or

var Component = pakka({
	html: '<span eventName-handle="callbackPropertyName">your-html-string-here</span>'
});

var item1 = new Component();
item1.callbackPropertyName = function (event) {
	// item1's event handling
}

var item2 = new Component();
item2.callbackPropertyName = function (event) {
	// item2's event handling
}

Property binding (Two way binding)

var Component = pakka({

	html: '<span bind-text="propertyName">your-html-string-here</span>', 

	controller: function (context) {
		
		// gets property's value
		context.$get('propertyName'); 
		
		// sets property's value, also reflecting 'new text' in the DOM
		context.$set('propertyName', 'new text'); 
	}
});

var item = new Component();

var Component = pakka({
	html: '<span bind-text="propertyName">your-html-string-here</span>',
});

var item1 = new Component();

// gets property's value from item1
item1.$get('propertyName'); 

// sets property's value, also reflecting 'new text' in the DOM of item1
item1.$set('propertyName', 'new text'); 

var item2 = new Component();

// gets property's value from item2
item2.$get('propertyName'); 

// sets property's value, also reflecting 'some other text' in the DOM of item2
item2.$set('propertyName', 'some other text'); 

API reference

pakka(options)

This function makes an instantiable object(as a class object).

options.controller

User can define a controlling function. context will be passed to this function with few util functions that can be used to glue. Also context will be returned to the instance object created for this. So all the following functions will be available in the instance too.

context.$get(propertyName)

Provide property name to get its value.

context.$set(propertyName, value)

Provide property name and value to set that property. This triggers binding value to DOM.

context.$properties

A reference to the source object where $get and $set executes.

Note: do not try to set things directly to this property if you want pakka to work for this property.

context.$elements

This provides a refenece to the array of elements glued for this component instance.

this can be instantiated using document.querySelectorAll().

context.$id

This provides id generated by pakka for this component instance.

context.$name

This provides name assiged by user or generated by pakka for this component.

context.$options

This provides reference to options assiged by user for this component.

context.$setCss(cssString)

This adds a personal CSS for this component.

context.$setHtml(htmlString)

This detaches previous elements and creates new DOM out of htmlString provided and glues it to the context.

context.$setElements(elements)

This detaches previous elements and glues it to the new set of elements provided.

context.$listeners

This provides the reference to all the events that are attached.

context.$detachEvents([namespace])

This function makes pakka detach events by namespace. If namespace is not provided, pakka detaches all events of this component instance.

context.$propertyBindings

This provides the reference to all the properties that are bound for this component instance.

context.$removePropertyBindings(namespace)

This function makes pakka detach property bindings by namespace. If namespace is not provided, pakka detaches all property bindings of this component instance.

context.$destroy()

This function should be called to purge the component instance properly.

options.css

User can assign a css style definition string. pakka adds this stylesheet to DOM when the first instance would be made.

Note: we are not doing any preprocessing yet. So user will have to make the stylesheet having styles along with the component name. Component name can be provided with options.name property.

options.html

User can assign a html string. pakka will create DOM elements and glues it up with the controller.

options.name

User can assign a name to component. pakka adds this name to the root element. So this can be used to write styles as you need that can be specific to the component.

Note: all the instances made from this component will have same name.

options.elements

User can assign elements already loaded into DOM using document.querySelectorAll('<selector>')

pakka.addStyleSheet(css, id[, styleEl])

Personal stylesheet adding function.

Accepts css string, id to be maintained and style element if we already have any.

Returns style element.

pakka.detachEvents(context[, namespace])

Detaches events for a pakka context or instance by namespace. If namespace is not given, then pakka detaches all the events.

Accepts pakka context and namespace.

pakka.detachEvent(event, element, handler, context)

Detaches one event for a pakka context or instance.

Accepts event name, HTML element object, handler callback function and a pakka context.

pakka.removePropertyBindings(context[, namespace])

Removes property bindings for a pakka context or instance by namespace. If namespace is not given, then pakka removes all the property bindings.

Accepts pakka context and namespace string.

pakka.apply(context[, prop, value])

Applies property bindings. if prop and value are not provided, it will apply for all the properties

Accepts pakka context, property name string and value object.

pakka.addClass(element, className)

Adds class to a HTML element.

Accepts HTML element and class name string.

pakka.empty(element)

Empties conetents of an element.

Accepts HTML element.

pakka.linkBinders(element, context, namespace)

Links all the binders noticed in the element.

Accepts HTML element, pakka context and namespace string.

pakka.attachEvents(element, context, namespace)

Attaches all events noticed in the element.

Accepts HTML element, pakka context and namespace string.

pakka.attachEvent(event, element, handler, context, namespace)

Attaches one event.

Accepts events name string, HTML element, handler callback, pakka context and namespace string.

pakka.pushListener(event, element, handler, context, namespace)

Adds the event handler to the listners cache.

Accepts events name string, HTML element, handler callback, pakka context and namespace string.

pakka.addBinder(name, callback)

Can define a new binder.

name will be checked in attributes.

callback will be called only once while instantiation and expects the callback to return a callback for updating on value change.

e.g.

    addBinder('bind-text', function(el, prop, context) {
        return function(value) {
            el.innerText = definitelyGetString(value);
        }
    });

Attribute binding

Like angularjs v1's attribute based directives pakka allows some attribute binders.

bind-text

Binds text to the html from the property assigned.

e.g. <span bind-text="myName"></span> use context.$set('myName', 'the bhaskara') in your controller to set its value.

bind-html

Binds html string to the html from the property assigned. also applies all the binders and events inside it.

e.g. <div bind-html="myTemplate"></div> use context.$set('myTemplate', '<span>the bhaskara is great!</span>') in your controller to set its value.

bind-property

Bind property is like ng-model in angularjs. It binds the value of any input element to the property and vice-versa also gets handled.

e.g. <input type='text' bind-property="username" > use context.$get('username') in your controller to get its value.

bind-component

Binds a pakka component instance to the element.

e.g. <div bind-component="myComponent" ></div> use context.$set('myComponent', new SomePakkaComponent()) in your controller to bind this component.

bind-components

Binds all the pakka component instances given in the ListOfPakkaComponents.

e.g. <div bind-components="myComponents" ></div> use context.$set('myComponents', ListOfPakkaComponents) in your controller to bind this component.

bind-class

Adds or removes classes given in the given property. User can provide 3 types of inputs. Namely String, Array or Object.

When user provides string, it adds the classes provided in the string and removes any class that was added before(which is not present now).

When user provides Array, it does the sane thing as string but the input needs classes seperated by strings(not spaces in strings).

When user provides Object, the key will be treated as class name and the value will be used to add or remove the class(you will have to provide boolean true as the value to add the class otherwise it will be treated as false and be removed).

e.g. <div bind-class="myClasses" ></div> use context.$set('myClasses', 'myClass') or context.$set('myClasses', ['myClass', 'myAnotherClass']) or context.$set('myClasses', {'myClass': true, 'myAnotherClass': false}) in your controller to bind this component.

bind-element

Gives the element handle.

Note: This is a readonly binder. User can actually use the element to do some manipulations but cannot use $set to set another element.

e.g. <div bind-element="myElement" ></div> use context.$get('myElement') in your controller to bind this component.

Events binding

pakka allows attribute based event attaching.

<event_name>-handle="handlerCallback"

Binds event of the element to the handler callback from the pakka context.

e.g. <div click-handle="clicked" ></div> use context.clicked = function(event){ window.alert('clicked!') } in your controller to bind this event

Pending or ongoing activities

• make more binders
• optimize the functions
• make css framework.
• make components like dropdown, table, toggle button, etc.

Interested developers can join hands to make thebhaskaraui better.