= netzke-core

Create Ext JS + Rails components with minimum effort.

This is the bare bones of the Netzke framework. Use it to build your own components from scratch. For pre-built components (like panels, grids, forms, trees, applications), see the netzke-basepack (http://github.com/skozlov/netzke-basepack) project.

The idea behind the Netzke framework is that it allows you write reusable client/server code. Create a component, and then embed it straight to your Rails' view, load it dynamically into your Ext-based applications, or use it as a building block for other (composite) components. For more info, see the links below.

== Requirements

* Rails >= 3.0.0
* Ruby >= 1.9.2 (1.8.7 should work, but may not be supported as diligently)
* Ext >= 3.3.0

== Installation

For the latest ("edge") stuff, tell bundler to get the gem straight from github:

    gem 'netzke-core', :git => "git://github.com/skozlov/netzke-core.git"

Or install as plugin:

    rails plugin install git://github.com/skozlov/netzke-core.git
    
Netzke assumes that your ExtJS library is in public/extjs (which may be a symbolic link):

    ln -s ~/code/sencha/ext-3.3.0 public/extjs

== Usage

Let's create a simple "Hello world!" component and embed it into a Rails' view. It'll be an Ext.Panel-based component with a button that triggers a client-server communication.

Create YOUR_APP/app/components/hello_world_component.rb, and put in the following content:

    class HelloWorldComponent < Netzke::Base
      # Ext.Panel's config option "title"
      js_property :title, "My Hello World Component"

      # Bottom bar with an automatically created action
      js_property :bbar, [:bug_server.action]
      
      # Action to be placed on the bottom bar
      action :bug_server, :text => 'Ask server', :icon => :accept
      
      # Method in the JS class that (by default) processes the action's "click" event
      js_method :on_bug_server, <<-JS
        function(){
          // Remotely calling the server's method greet_the_world (defined below)
          this.greetTheWorld();
        }
      JS

      # Server's method that gets called from the JS
      endpoint :greet_the_world do |params|
        # Tell the client side to call its method showGreeting with "Hello World!" as parameter
        {:show_greeting => "Hello World!"}
      end

      # Another method in the JS class that gets remotely called by the server side
      js_method :show_greeting, <<-JS
        function(greeting){
          this.body.update("Server says: " + greeting);
        }
      JS
    end


To embed a Netzke component into your Rails view do the following:

1. Add <tt>netzke</tt> routes:

    # in routes.rb
    RailsApp::Application.routes.draw do
      netzke
      ...
    end

2. In your layout, within the "head" tag, use the <tt>netzke_init</tt> helper to include all the necessary JavaScript and styles.

    <%= netzke_init %>

    # You can optionally specify an Ext theme:

    <%= netzke_init :ext_theme => 'grey' %>
      
3. In your view use the <tt>netzke</tt> helper to embed the component:

    <%= netzke :hello_world_component %>

That's it. While playing with the component, use Firebug or similar tool to check the AJAX requests to understand better what's going on behind the scenes. Also check the source code of the page embedding the component.

== Running tests

netzke-core is bundled with cucumber and RSpec tests. Before you can run them, you must link your Ext JS library to test/rails_app/public, e.g. (from plugin's root):

    ln -s ~/code/sencha/ext-3.3.0 test/rails_app/public/extjs

For cucumber tests:

    cucumber features
    
RSpec tests:

    rspec spec
    
== Testing playground

The bundled test/rails_app application is also a convenient playground to learn more about the framework, as it may be run as a stand-alone Rails app. It's also a pretty good source of examples. After starting it, access any of the app/components/netzke test components by using the following url:

    http://localhost:3000/components/<name of the component's class>

e.g.:
  
    http://localhost:3000/components/ServerCaller

or, for scoped components:

    http://localhost:3000/components/ScopedComponents::SomeScopedComponent

== Migrating from 0.5.x

There have been a significant amount of changes that made 0.6 version backward-incompatible. Please, refer to CHANGELOG.rdoc for the (hopefully) full list of changes that most certainly would make your current application break. Additionally, this wiki page may be of some help, too: http://github.com/skozlov/netzke-core/wiki/Upgrading-from-0.5.x-to-0.6.0

== More info
Netzke website: http://netzke.org

Live-demo with sample code: http://demo.netzke.org

Tutorials: http://blog.writelesscode.com

Twitter: http://twitter.com/skozlov

The netzke-basepack project (pre-built full-featured components): http://github.com/skozlov/netzke-basepack

---

Copyright (c) 2008-2010 Sergei Kozlov, released under the MIT license