Tweak.js - A lightweight component and module driven micro-library.

master: develop:

Introduction

Tweak.js is a lightweight component and module driven micro-library built to help developers' structure code; for use in Web Applications and Web Components. JavaScripters can take advantage of class features, this makes OOP JavaScript easy to use even for JavaScipt purists. Tweak.js becomes even more powerful with JavaScript task runners such as Brunch, Grunt and Gulp. With the use of task runners structuring code into appropriate files/directories is extremely simple and effective.

Tweak.js introduces components to implement further modularization into development. Components are used to create a set of linking modules like the typical Model, Views.. you name it. Components can that can be extended, reused further adding organization. Tweak.js also includes Router, Service and History modules like that of typical frameworks for added support in development. Furthermore, to enhance the relationship between modules Tweak.js modules include a powerful event system. The event system is simple and designed to extend modules with functionality to link actions between the individual modules.

5 key philosophies

• Flexibility - Use any development pattern with any tools and libraries to achieve a better development stack.
• Modularity - Modularize your code into organized modules that improve TDD, maintainability and understandability.
• Simplicity - Keeps your code and structure simple. No complex API's means less time learning more time developing.
• Familiarity - Less unnecessary abstraction, which is typical of monolithic frameworks which alter code structure.
• Minimal - Tweak.js will remain minimal and vows never to be larger that 10kb minified and gzipped.

For a full understanding to the framework please look at the documentation or the source code.

Use

Installation

BOWER: bower install tweak-js

NPM: npm install tweak-js

tweak.light.js

Tweak.js has an extra lightweight version that does not incorporate an inbuilt history API and router module. This allows you to use any other micro-library's that provide this functionality. This version is only 1.4kb minified and gzipped, providing you the core to structure code with minimal overheads. To use these version with bower you will need to override the value of the main property of this module, below is an example to point to the light version of tweak.js.

// Using non-minified version
{
  ...
  "overrides": {
    "tweak.js": {
      "main": [
       "lib/tweak.light.js"
      ]
    }
  }
  ...
}

// Using minified version
{
  ...
  "overrides": {
    "tweak.js": {
      "main": [
       "lib/tweak.light.min.js"
      ]
    }
  }
  ...
}

Dependencies

NONE - Tweak.js has no dependencies. Which allows you to use what you like, how you like. There are many micro framework projects that can extend Tweak.js possibilities. For example with rivet.js you can apply two way data binding to templates.

Templates/Skeletons

A skeleton for Grunt, Brunch and Gulp will shortly be created.

Extensions/Plug-ins

Adding additional functionality such as libraries like rivet.js, handlebars.js, JQuery, underscore and more can't be easier. The simplicity of Tweak.js allows simple implementing of libraries. This prevents complex plug-ins/extensions that require further understanding to the framework.

Concepts

Below is a rough guide to the concepts used within Tweak.js. Additional information can be found on the web to help you understand design patterns. In a nutshell Tweak.js doesn't define what design patterns should be used, but aids in helping you structure to any design pattern. For more in-depth details on what Tweak.js can do, look at the relevant module in the documentation or look at the source code for line by line comments. Better yet just get stuck in and mess around with it; its versatile for lots of needs.

For more information please look at the documentation under the Router section.

Module

Modules's are used to separate concerns and logic, into smaller maintainable modules; that can be extended, reused and organized. A modular development approach comes with many benefits. Modules can then be developed by separate teams with their own life cycles, with better maintainability. Modularity also provides a better TDD environment.

Component

Component's are used to create a set of linking modules like the typical Models, Views and Controllers; that can be configured, extended, reused and organized. A Component will build and tie together modules.

Events

Tweak.js has an Event System, this provides functionality to extending classes to communicate simply and effectively while maintaining an organized structure to your code and applications. A main advantage of using the event system is that an events callbacks get fired synchronously, allowing application flow to continue while tasks take place.

For more information please look at the documentation under the Module class.

Service

A Service is a module that is shared between other modules. A service should provide functionality that is generic to multiple modules thus providing further segregation to modules and providing further maintainability and reusable code. When used with components, they will not be provided with a component linkage, this is because it may be used with other components, and it may have a component property that may not want to be modified.

History

The History is a Service that adds cross-browser friendly version of the HTML5 history API. When available it uses the HTML5 pushState else it provides a backwards compatible solution to having a stored history, either hashState or an interval that checks at a set rate. The History provides routes to your application/component which updates the application/components based on the URL information. The current URL location can also be set to provide a shareable/linkable/bookmark-able URL to specific places in your application.

For more information please look at the documentation under the History section.

Router

The Router which hooks into the Tweak.History change events which provides information back from the URL. The Router module provides routing via events which can control the application and its modules.

OOP JavaScript

OOP is core to Tweak.js as it provides a solution to keep code organised, reusable and extend-able. If using CoffeeScript you may be well adapted the OOP concepts and its functionalities. JavaScript purists can take advantage of Tweak.js' built in methods to embed OOP concepts; please look at the documentation/source for more information - documentation.

Templates

A template, written in a template language, describes the user interface of your application. Tweak.js doesn't limit you to how you create your templates, however as a rough guide; a template normally will be generated from a template engine like handlebars. Template engines will typically tie to a object to use as its construction, in Tweak.js this is normally a relating Model/Collection's attributes. Templates should be generated in a View module, as this is typically considered the correct place for these actions.

Contribution

Feel free to contribute in any way you can. Whether it is contributing to the source code or donating to help development. Tweak.js will always remain open source and I will never ask for your personal details.

License

The MIT License (MIT)

Copyright (c) 2014 Blake Newman

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A ARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE