RSence is a RIA framework designed for responsive GUI applications on the web.
Ruby Other
Switch branches/tags
Nothing to show

README.rdoc

RSence-3.0

Notice

These docs are somewhat outdated at the moment, and RSence needs rsnc.js cloned into /client of this repository.

Sources for rsnc.js:

  • github.com/jammi/rsnc

  • github.com/rsence/rsnc

  • git@rsence.org:rsnc.git

License

  • RSence is licensed under the MIT license

Introduction

RSence is a different and unique development model and software frameworks designed first-hand for real-time web applications. RSence consists of separate, but tigtly integrated data- and user interface frameworks.

RSence could be classified as a thin server - thick client system.

Applications and submobules are installed as indepenent plugin bundles into the plugins folder of a RSence environment, which in itself is a self-contained bundle. A big part of RSence itself is implemented as shared plugin bundles.

The user interface framework of RSence is implemented in high-level user interface widget classes. The widget classes share a common foundation API and access the browser's native API's using an abstracted event- and element layer, which provides exceptional cross-browser compatibility.

The data framework of RSence is a event-driven system, which synchronized shared values between the client and server. It's like a realtime bidirectional form-submission engine that handles data changes intelligently. On the client, changed values trigger events on user interface widgets. On the server, changed values trigger events on value responder methods of server plugin modules. It doesn't matter if the change originates on client or server, it's all synchronized and propagated automatically.

The server framework is implemented as a high-level, modular data-event-driven system, which handles delegation of tasks impossible to implement using a client-only approach. Client sessions are selectively connected to other client sessions and legacy back-ends via the server by using the data framework.

The client is written in Javascript and the server is written in Ruby. The client also supports CoffeeScript for custom logic. In many cases, no custom client logic is needed; the user interfaces can be defined in tree-like data models. By default, the models are parsed from YAML files, and other structured data formats are possible, including XML, JSON, databases or any custom logic capable of producing similar objects. The server can connect to custom environments and legacy backends accessible on the server, including software written in other languages.

Installing RSence

Just run this command in the shell, if you have functioning ruby environment installed. Otherwise, read the {file:INSTALL Install Guide} for full installation instructions.

gem install rsence

Initializing a new RSence environment

The init command will create a directory called `env_dir` in this example. It asks a few questions about the environment. Use a path and project name that matches your purposes.

rsence init /home/me/rsence_projects/env_dir

Project environment structure

The basic structure of a project environment (where `env_dir` is the directory of your project) is:

dir

env_dir/

The environment directory of your project.

file

env_dir/conf/config.yaml

The configuration file to load by default. It extends the {file:default_conf default configuration}.

dir

env_dir/run/

This default directory for runtime files, like the PID file of the running rsence instance.

dir

env_dir/log/

The default directory for log files. rsence.stderr contains error output of the RSence server daemon and installed plugins, including warnings. rsence.stdout contains the standard output of the RSence server daemon and installed plugins.

dir

env_dir/db/

The default directory for database files. ses.db is the standard SQLite session database, if enabled.

dir

env_dir/plugins/

The default directory for installed plugin bundles. A newly initialized environment includes the welcome plugin. Feel free to remove it.

file

env_dir/VERSION

The version of RSence used to initialize the environment. Reserved for future upgrade usage.

file

env_dir/README

A README file template. Describes what the `env_dir` is about. Edit it to match your project.

Configuration file loading order

The configuration files are loaded and applied in this order:

  1. rsence_gem_path/conf/default_conf.yaml

  2. rsence_gem_path/conf/local_conf.yaml

  3. /etc/rsence/config.yaml

  4. ~/.rsence/config.yaml

  5. env_dir/conf/config.yaml

  6. Any files given using --conf arguments, in order of occurrence.

Use the additional configuration files to match system- or user-specific configurations that are common for all projects.

Running a project

Each command-line tool command takes a number of options, the env_dir argument defaults to the current working directory, otherwise specify the relative or full path to your project environment.

Some common options are:

-a

Automatic updates. RSence reloads automatically changed plugin bundles and client libraries.

-f

Doesn't redirect the standard output into a log file. Useful for development when combined with the run command.

-d

Debug mode. Like -a but much more verbose and doesn't obfuscate client data.

Running RSence in foreground

rsence run [options] [env_dir]

Starting the RSence daemon

rsence start [options] [env_dir]

Stopping the RSence daemon

rsence stop [options] [env_dir]

Restarting the RSence daemon

rsence restart [options] [env_dir]

Checking if project is running

rsence status [options] [env_dir]

Example:

rsence run -af /home/me/projects/hello_world

RSence command-line tool help

Lists all available commands

rsence help

Getting detailed help of a command

rsence help <command>

Example:

rsence help run

For more detailed installation and usage instructions, read the {file:INSTALL Install Guide} document.

The bleeding edge (for developers)

RSence comes in two varieties:

  1. rsence : The stable release intended for running in production environments.

  2. rsence-pre : The active development snapshot intended for develoment environments. Runtime-wise, it's nearly as stable as the stable version, but features are constantly added and sometimes changed.

To use “rsence-pre”, install the “rsence-pre” gem and use the “rsence-pre” instead of “rsence” command-line tool.

Commercial support options

  • Riassence Inc. provides commercial RSence support and various other services.

Community support

  • rsence.org/

  • IRC channel #rsence on the FreeNode IRC network

Keywords:

HTML5 Javascript CoffeeScript Ruby RIA Server Client Data-Driven Event-Driven Web Framework