midas-guilded

= guilded

http://github.com/midas/guilded/tree/master

== DESCRIPTION

Guilded is a framework for building web based components centered around current web standards and best practices. The current framework is written in ruby, but could be ported to other languages.

Guilded intends to provide a toolset for creating and consuming reusable web components. Currently, this problem domain is filled with JavaScript frameworks. These frameworks are wonderful and work very well. However, they do not degrade gracefully and are not accessible. Guilded seeks to provide the same level of "componentization" and ease of use without sacrificing degradability and accessibility. Guilded will achieve these goals by applying each technology at our disposal to do what it was intended.

XHTML will be employed for content. CSS used for layout and styling. Behavior will be added to a component with JavaScript through progressive enhancement. The user will have the best experience with a Guilded component when CSS and JavaScript are enabled in their browser, but will still be able to use the component when CSS and JavaScript are disabled.

Guilded will use jQuery as it's base JavaScript framework. jQuery was chosen because it lends itself to progressive enhancement due to the way it was authored. In addition, the tight integration of jQuery's selectors with CSS selectors is also highly desirable. When authoring a Guilded component, it is encouraged to write the behavior code as a jQuery plugin. This will allow the jQuery plugin to be used outside of the Guilded project, if desired.

Guilded also seeks to provide a standardized CSS framework for creating layouts that are reusable and predictable.

Guilded will utilize the currently existing RubyGems system to package its components. A new Guilded component will be packaged in a Gem and have a dependency on the Guilded gem.

The Guilded gem contains the framework to build Guilded components.

Update: Due to the quality components, etc. being generated by the MooTools community and the general quality of the library, we have decided to include support for it in Guilded as of release 0.3.0.

== FEATURES

=== Centralized control of CSS and JavaScript assets needed to render a web page.

• Automatic addition of jQuery 1.3.2 library.
• Automatic addition of MooTools 1.2.3 library if a utilized component defines it as a dependency using the :mootools => true option with the Guilder.add() method when defining the component.
• Automatic addition of Yahoo's reset-min.css.
• Redefinition of jQuery's $ method to $j and running jQuery in no conflict mode to allow other libraries to retain control of the $ method.
• Definition of the g namespace to avoid JavaScript name collisions. Simply define your custom functions within the g object.
• Definition of convenience method $j(). Equivalent to jQuery() or $(). Guilded runs jQuery in no conflict mode, giving the $ back to any other JavaScript frameworks in use. You must use $j() or jQuery() in lieu of $().
• Definition of convenience method $jc(). Equivalent to jQuery( '.' + className ).
• Definition of convenience method $jid(). Equivalent to jQuery( '#' + idName ).
• The assets required for each component are added by the author to a central data store. When the view helper to create the component is called, these assets are added to the asset store. This results in a single method call with some options to use a Guilded component. No need to include JavaScript source files or CSS files. Guilded automatically does this for you.
• For CSS assets, Guilded simply loops through the collection of CSS assets creating an HTML link tag for each asset, or one HTML link tag for the cached version of these asset(s), when running in production mode.
• For JavaScript assets, Guilded loops through the collection of JavaScript assets creating an HTML script tag for each, or a single script tag for the cached version of these asset(s), when running in production mode.
• Pass named data structures from the server to the client side environment for use with the Guilder.add_data() method. Once Guilded is initialized, the data structure will be instantiated for you with the name specified within the g object.
• Execute custom JavaScript code after all Guilded components are initialized (ensuring everything you wish to use is instantiated) using the 'guildedInitialized' custom jQuery event defined on the body DOM element.
• g_javascript_include_tag view helper that will explicitly add JavaScript libraries to the libs collection to be included in the assets. This helper will also resolve any libs to their full or compressed versions dependent on the current executing environment.
  Additionally, the symbols :jquery and :mootools will be expanded to the lib version defined in the Guilded configuration.

=== Caching of CSS and JavaScript assets needed to render a web page.

• The CSS assets are cached to form one file. In addition, the JavaScript assets are cached to form one file. These files are named by sorting and concatenating into a single string the names of each individual respective asset. This string is then hashed to generate a reproducable unique string. This file naming technique allows Guilded to find cached asset files that match a combination of Guilded components, not an action, URI, etc. Thus, one file for a certain combination of Guilded components is generated and then reused on any page where the combination appears.

=== Automatic choosing of packed, compressed or minified JavaScript files when in production mode.

• In production mode, Guilded automatically looks for a .pack, .compressed or .min version of the JavaScript assets. If one of these is found, it includes it, otherwise, it includes the version specified by the author in the view helper. This is usually an unpacked version of the file.

=== Additional common utilities

• Determine the browser making a request with the BrowserDetector class and related view helpers.
• Extends ActiveRecord to have a attr_human_hint method. This method works similar to the attr_human_name method except a hint to use on forms, etc is being set.
• Extends InactiveRecord (http://github.com/midas/inactive_record/tree/master) to include the attr_human_hint method.

== GUILDED COMPONENT PROJECTS

• http://github.com/midas/g_already_grid/tree/master
• http://github.com/midas/g_auto_completer/tree/master
• http://github.com/midas/g_flash_growler/tree/master
• http://github.com/midas/g_flot/tree/master
• http://github.com/midas/g_form_submit_protector/tree/master
• http://github.com/midas/g_named_scope_filters/tree/master
• http://github.com/midas/g_nested_select/tree/master
• http://github.com/midas/g_sectioned_shower/tree/master
• http://github.com/midas/g_toggle_block/tree/master

== PROBLEMS

== REQUIREMENTS

• jQuery 1.3.2 (included in Guilded)

== OPTIONALS

• MooTools 1.2.3 (included in Guilded)

== INSTALL

gem sources -a http://gems.github.com sudo gem install midas-guilded

== INSTALL FOR RAILS

Add to environment file:

config.gem "guilded", :version => '0.2.9'

Run:

sudo rake:gems:install

Generate:

script/generate guilded_config script/generate guilded_assets

Edit the settings file at config/initializers/load_guilded_settings.rb. Change any of these settings to reflect how you would like Guilded to be configured. If you change where any file(s) are configured to be located, then also move the respective file(s).

Next you must make a call to the view helper to apply the CSS It should be placed in your layout:

<%= g_apply_style %>

There is also a view helper to apply the JavaScript. You can place this at the bottom of your layout(s) (so you do not have to include it in every template):

<%= g_apply_behavior %>

You also must reset the Guilded singleton that manages everything after each rendering. The best way to do this is a before filter in your application controller:

before_filter :reset_guilded

#...

protected

def reset_guilded Guilded::Guilder.instance.reset! end

Then install one or more Guilded components and you are on your way!

== LICENSE

Copyright (c) 2009 C. Jason Harrelson (midas)

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 PARTICULAR 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.