netzke-core

Create Sencha Ext/Touch + 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 github.com/skozlov/netzke-basepack and github.com/skozlov/netzke-basepack-touch.

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 in the end.

Requirements

Ruby >= 1.9.2 (1.8.7 may work, too)
Rails >= 3.0.0
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"

Netzke assumes that your Ext library is in public/extjs (which can be a symbolic link):

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

Sencha Touch files are assumed to be in public/sencha-touch:

    ln -s ~/code/sencha/sencha-touch-1.0.1 public/sencha-touch

(as the result, make sure that the location of the license.txt file is exactly public/extjs/license.txt or public/sencha-touch/license.txt respectively)

Usage

Refer to github.com/skozlov/netzke-core/wiki/Defining-and-extending-components for details on building/extending components using netzke-core.

API docs: api.netzke.org/core/

“Hello world” component (Ext)

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 => 'Greet the World', :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

Embedding components into Rails views

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

Add netzke routes:

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

In your layout, within the “head” tag, use the netzke_init helper to include all the necessary JavaScript and styles.
```
  <%= netzke_init %>
  # You can optionally specify an Ext theme:
  <%= netzke_init :ext_theme => 'grey' %>
```
In your view use the netzke 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.

Sencha Touch support

netzke-core has support for Sencha Touch. Create reusable code for Sencha Touch with the same ease as you do for Sencha Ext, getting composition, inheritance, and dead-simple client-server communication out-of-the-box.

Here’s how the code for Sencha Touch HelloWorldComponent may look like:

    class HelloWorldComponent < Netzke::Base
      js_base_class "Ext.Panel"
      def configuration
        super.merge({
          :docked_items => [{:dock => :top, :xtype => :toolbar, :title => 'Hello World Component',
            :items => [
              {:text => "Greet the World", :handler => :on_bug_server}
            ]
          }]
        })
      end
      js_method :on_bug_server, <<-JS
        function(){
          this.greetTheWorld();
        }
      JS
      endpoint :greet_the_world do |params|
        {:update => "Hello from the server!"}
      end
    end

Embed the component just the same way you do in case of Ext. The only difference is in calling netzke_init, which should be provided with the :platform config option set to :touch:

    <%= netzke_init :platform => :touch %>

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: github.com/skozlov/netzke-core/wiki/Upgrading-from-0.5.x-to-0.6.0