rails-bootstrap-widgets 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 YOURNAME
+
+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 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.

data/README.md

@@ -0,0 +1,220 @@
+# About [![Build Status](https://travis-ci.org/nepalez/widgets.png?branch=master)](https://travis-ci.org/nepalez/rails-bootstrap-widgets)
+
+The project defines a collection of widgets to be used inside views. It also contains some js files to provide additional behavior for html elemets, created by those widgets. Both helpers and js are compatible with Twitter Bootstrap framework.
+
+# Installation
+
+Add this line to your application's ```Gemfile```:
+```Ruby
+gem 'rails-bootstrap-widgets'
+```
+And then execute:
+```
+$ bundle
+```
+Or install it yourself as:
+```Ruby
+$ gem install rails-bootstrap-widgets
+```
+# Available widgets
+## List widgets
+This group consists of two widgets to be used in views that contain items lists.
+### pagination_widget (helper method)
+```Ruby
+pagination_widget(items, options = {})
+```
+The widget simply wraps pager (from the ```will-paginate``` gem) into the aside tag with some class.
+#### Example
+```Ruby
+pagination_widget @items, class: 'pagination-top'
+```
+This will create
+```Html
+<aside class="pagination-top">
+  <!-- Standard result of 'will_paginate(items, inner_window: 0, outer_window: 0)' call -->
+</aside>
+```
+### filters_widget (helper method)
+```Ruby
+filters_widget(items, options = {})
+```
+The widgets create html for filtering, ordering and paging a list of items. Provided html will include:
+
+1. Input field to select filter from those are available
+2. Input field to select order from those are available
+3. (Hidden) button to reset filter values
+4. Button to reload the page with new filter values
+5. Items pager
+
+This html code should provide basic functionality without js support.
+
+If js support is turned on in a client's browser, jQuery method will show reset button (js required) and hide reload button. It also makes current page to be updated authomatically after new filter or ordering is selected, or reset button clicked.
+
+#### Example
+```Ruby
+filters_widget (
+  @items,
+  filters: { published: :Published, unpublished: :Unpublished}, # list of filters to select from in a format { key: :name }
+  filter: 'published',                                          # key of the current filter to apply to items
+  orders: { tree: :Tree, feed: :Feed },                         # list of types of items ordering to select from
+  order: 'tree'                                                 # key of the current order type
+)
+```
+This will provide html:
+```HTML
+<form accept-charset="UTF-8" action="/" class="span8" id="filters" method="get">
+  <div style="margin:0;padding:0;display:inline">
+    <input name="utf8" type="hidden" value="&#x2713;" />
+  </div>
+  <div class="input-prepend">
+    <span class="add-on">
+      <i class="icon-filter"></i>
+    </span>
+    <select id="filter" name="filter">
+      <option value="published" selected="selected">Published</option>
+      <option value="unpublished">Unpublished</option>
+    </select>
+  </div>
+  <div class="input-prepend">
+    <span class="add-on">
+      <i class="icon-order"></i>
+    </span>
+    <select id="order" name="order">
+      <option value="tree" selected="selected">Tree</option>
+      <option value="feed">Feed</option>
+    </select>
+  </div>
+  <a href="#" class="btn add-on hide" id="reset">
+    <i class="icon-reset"></i>
+  </a>
+  <div class="input-prepend" id="reload">
+    <span class="add-on">
+      <i class="icon-reload"></i>
+    </span>
+    <input class="btn" name="commit" type="submit" value="Reload" />
+  </div>
+</form>
+<aside class="span4">
+  <!-- Standard result of 'will_paginate(items, inner_window: 0, outer_window: 0)' call -->
+</aside>
+```
+### Filters js support
+The module adds file ```filters.js.coffee``` to ```app/assets/js/``` to authomatically reload current page after new filter or ordering selected by a user.
+
+When current page is reloaded:
+
+1. Filters reload button is removed (reloading became authomatic instead)
+2. Filters reset button is added (it clears both filter and order field and reload the page with no filter|order set. They can be set by default within a controller)
+3. Adds reloading the page on selecting new input field value (filter or order)
+
+## Modal widgets and js
+
+### modal_form_widget (helper method)
+```Ruby
+modal_form_widget(options = {}, &block)
+```
+The widget puts a list of fields (inputs, selectors etc.) into a modal form window (presented by ```<form id='modal' class='modal fade'...>```)
+#### Details
+```Ruby
+modal_form_widget (
+  title: 'modal window title',              # required
+  action: 'path to corresponding route',    # required
+  method: 'request method for the form',    # "post" by default, "post", "get", "put" or "delete" extected
+  button: 'text on the submit button',      # I18n.t("buttons.submit") by default
+  cancel: 'text on the cancel form button'  # I18n.t("buttons.cancel") by default
+) do
+  "" # html code of form fields
+end
+```
+#### Example
+```Ruby
+modal_form_widget(title: 'Title', button: 'Button', method: :put, action: '/some_addr', cancel: "Cancel") { "content" }
+```
+This will create
+```Html
+<form accept-charset="UTF-8" action="/some_addr" class="modal fade" data-remote="true" id="modal" method="post">
+  <div style="margin:0;padding:0;display:inline">
+    <input name="utf8" type="hidden" value="&#x2713;" />
+  </div>
+  <input id="_method" name="_method" type="hidden" value="put" />
+  <header class="modal-header">
+    <button aria-hidden="true" class="close" data-dismiss="modal" type="button">&times;</button>
+    <h1>Title</h1>
+  </header>
+  <div class="modal-body">content</div>
+  <div class="modal-footer">
+    <a href="#" aria-hidden="true" class="btn" data-dismiss="modal">Cancel</a>
+    <input class="btn btn-primary" id="submit" name="commit" type="submit" value="Button" />
+  </div>
+</form>
+```
+### modal_view_widget (helper method)
+```Ruby
+modal_view_widget(options = {}, &block)
+```
+The widget puts html code into a modal window (presented by ```<div id='modal' class='modal fade'>```)
+#### Details
+```Ruby
+modal_view_widget (
+  title: 'modal window title',              # required
+  href: 'path for redirection to details',  # required
+  redirect: true|false,                     # whether redirect button should be shown in the modal window footer (true by default),
+  button: 'text on the redirect button',    # I18n.t("buttons.details") by default
+  cancel: 'text on the cancel form button'  # I18n.t("buttons.cancel") by default
+) do
+  "" # modal window's html content
+end
+```
+#### Example
+```Ruby
+modal_view_widget(title: 'Title', button: 'Button', href: '/some_addr', cancel: "Cancel") { "content" }
+```
+This will create
+```Html
+<div class="modal fade" id="modal">
+  <header class="modal-header">
+    <button aria-hidden="true" class="close" data-dismiss="modal" type="button">&times;</button>
+    <h1>Title</h1>
+  </header>
+  <div class="modal-body">content</div>
+  <div class="modal-footer">
+    <a href="#" aria-hidden="true" class="btn" data-dismiss="modal">Cancel</a>
+    <a href="/some_addr" class="btn btn-primary">Button</a>
+  </div>
+</div>
+```
+### showModal (js function)
+```jQuery
+showModal(href, template, width = nil)
+```
+Provides jQuery method "show_modal" to download and open modal window via ajax.
+#### Arguments
+```href``` - path to corresponding ajax request (required).
+
+*When modal window is loaded, any link with selected ```href``` and ```data-remote='true'``` attribute is converted to modal window call. Direct links (without ```data-remote```) remain unchanged.*
+
+*Before another modal window is loaded, the calls are reverted back to ajax links. Next time the modal should be downloaded by ajax again. To prevent excess downloading, use http request caching (see <a href='http://railscasts.com/episodes/321-http-caching'>RailsCast episode #321</a> for example).*
+
+```template``` - path to modal window template (required).
+
+*This template will be rendered and incerted by ajax to html - before the closing ```</body>``` tag.*
+
+*Before another modal window is loaded, previous modal window is removed. Therefore at any given time the page will contain no more than one modal window*
+
+```width``` - width in pixels for the modal link. If not set, the default bootstrap modal window is rendered.
+
+#### Example
+In the ```app/views/posts/show.js.coffee``` you could call:
+```jQuery
+showModal('<%= post_path(@item) %>', "<%= j render 'modal/show' %>")
+```
+# Contributing
+
+1. Fork it
+2. Create your feature branch (git checkout -b my-new-feature)
+3. Commit your changes (git commit -am 'Add some feature')
+4. Push to the branch (git push origin my-new-feature)
+5. Create new Pull Request
+
+# License
+This project rocks and uses MIT-LICENSE.

data/Rakefile

@@ -0,0 +1,40 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'RailsBootstrapWidgets'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/app/assets/javascripts/rails-bootstrap-widgets/application.js

@@ -0,0 +1,15 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// the compiled file.
+//
+// WARNING: THE FIRST BLANK LINE MARKS THE END OF WHAT'S TO BE PROCESSED, ANY BLANK LINE SHOULD
+// GO AFTER THE REQUIRES BELOW.
+//
+//= require jquery
+//= require jquery_ujs
+//= require_tree .

data/app/assets/javascripts/rails-bootstrap-widgets/filters.js.coffee

@@ -0,0 +1,12 @@
+# encoding: utf-8
+# removes reload and displays reset button to reset fields via ajax
+jQuery ->
+	$(document).ready ->
+		$('form#filters #reset').removeClass('hide').removeAttr('href')
+		$('form#filters #reload').remove()
+		$('form#filters select').change ->
+			$('form#filters').submit()	
+		$('#reset').click ->
+			$('form#filters select').find('option:first').attr('selected', 'selected').parent('select');
+			$('form#filters select').prop('selectedIndex', -1);
+			$('form#filters').submit()

data/app/assets/javascripts/rails-bootstrap-widgets/show_modal.js

@@ -0,0 +1,26 @@
+var showModal = function(href, template, width) {
+
+	// close and remove previous modals and their calls
+	$('.modal').modal('hide');
+	$('.modal').remove();
+	$("*[data-toggle='modal']").attr('data-remote', 'true').removeAttr('data-target').removeAttr('data-toggle');
+
+	// add new modal and its calls
+	$('body').append(template);
+	$("a[href*='" + href + "'][data-remote='true']").removeAttr('data-remote').attr('data-target', '#modal').attr('data-toggle', 'modal');
+
+	// lock button after sending a request
+	$("#modal").submit(function(){ $('input[type=submit]', this).attr('disabled', 'disabled'); });
+
+	// set width of the modal
+	if (width.length > 0) {
+		$('#modal').modal({ backdrop: true, keyboard: true }).css({ width: width, 'margin-left': function () { return -($(this).width() / 2); }});
+	}
+
+	// add vertical scroll
+	$('.modal-body').css({ "max-height": function() { return ($(window).height() * 0.55); }});
+	$(window).resize(function(){ $('.modal-body').css({ "max-height": function() { return ($(window).height() * 0.5); }}); });
+
+	// open the new modal
+	$('#modal').modal('show');
+}

data/app/helpers/rails-bootstrap-widgets/application_helper.rb

@@ -0,0 +1,4 @@
+module RailsBootstrapWidgets
+  module ApplicationHelper
+  end
+end

data/app/helpers/rails-bootstrap-widgets/filters_helper.rb

@@ -0,0 +1,58 @@
+# encoding: utf-8
+module RailsBootstrapWidgets
+	module FiltersHelper
+		
+		def pagination_widget(items, options = {})
+			if items.present?
+				content_tag(:aside, (options[:class].to_s.present? ? { class: options[:class] } : {})) do
+					will_paginate(items, inner_window: 0, outer_window: 0).html_safe
+				end
+			end
+		end
+
+		def filters_widget(items, options = {})
+			if (options = _prepare(options)).present?
+				form_tag(url_for("/"), method: :get, id: :filters, class: :span8) do
+        	(_selector(:filter, options[:filters], options[:filter]) << _selector(:order, options[:orders], options[:order]) << _reset << _reload).html_safe
+      	end
+      else
+      	""
+			end << pagination_widget(items, class: :span4)
+		end
+
+	private
+
+		def _prepare(options = {})
+			_options = {}
+			_options.merge!({ filters: options[:filters], filter: options[:filter].to_s }) if _consistent?(options[:filters], options[:filter])
+			_options.merge!({ orders: 	options[:orders],  order:  options[:order].to_s }) 	if _consistent?(options[:orders],  options[:order])
+			return _options
+		end
+
+		def _consistent?(list, item)
+			list.class == Hash && item.to_s.present? && list.keys.collect{ |key| key.to_s }.include?(item.to_s)
+		end
+
+	  def _selector(type, list, item)
+	    if list
+	      content_tag(:div, class: "input-prepend") do
+	        content_tag(:span, class: "add-on") { "<i class=\"icon-#{ type }\"></i>".html_safe } <<
+	        select_tag(type, options_for_select(list.to_a.collect{ |i| i.reverse }, item))
+	      end
+	    else
+	      ""
+	    end
+	  end
+
+	  def _reset
+	    link_to("<i class=\"icon-reset\"></i>".html_safe, '#', class: "btn add-on hide", id: :reset)
+	  end
+
+	  def _reload
+	    content_tag(:div, id: :reload, class: "input-prepend") do
+	      content_tag(:span, class: "add-on") { "<i class=\"icon-reload\"></i>".html_safe } <<
+	      submit_tag(I18n.t("buttons.reload"), class: "btn")
+	    end
+	  end
+	end
+end

data/app/helpers/rails-bootstrap-widgets/modal_helper.rb

@@ -0,0 +1,61 @@
+# encoding: utf-8
+module RailsBootstrapWidgets
+	module ModalHelper
+
+		def modal_form_widget(options = {}, &block)
+			if (options = _prepare(options, :form)) && (content = block_given? ? capture(&block) : nil)
+		    form_tag(options[:action], method: :post, id: "modal", class: "modal fade", remote: true) do
+		      (_hidden(options[:method]) << _header(options[:title]) << _body(content) << _footer(:submit, options[:button], options[:cancel])).html_safe
+		    end
+		  else
+		  	''
+		 	end
+	 	end
+
+		def modal_view_widget(options = {}, &block)
+			content = block_given? ? capture(&block) : nil
+			if (options = _prepare(options, :view)) && content
+				content_tag(:div, id: "modal", class: "modal fade") do
+					(_header(options[:title]) << _body(content) << _footer(:button, options[:button], options[:cancel], options[:href], options[:redirect])).html_safe
+				end
+			else
+				''
+			end
+		end
+
+	private
+
+		def _prepare(options, type)
+			if (options.class == Hash) && %w(form view).include?(type.to_s)
+				options[:redirect] = true unless options[:redirect] == false
+				options[:method] = 'post' unless %w(get put delete).include?(options[:method].to_s)
+				options[:cancel] ||= I18n.t('buttons.cancel')
+				options[:button] ||= (type == :form ? I18n.t('buttons.submit') : I18n.t('buttons.details'))
+				return options if options[:title].present? && (((type == :view) && options[:href].present?) || ((type == :form) && options[:action].present? && options[:cancel].present?))
+			end
+			return nil
+		end
+
+		def _hidden(method)
+			method.to_s == "post" ? "" : hidden_field_tag(:_method, method.to_s)
+		end
+
+	  def _header(title)
+	    content_tag(:header, class: 'modal-header') do
+	      button_tag(type: :button, class: :close, "data-dismiss" => :modal, "aria-hidden" => 'true') { "\&times;".html_safe } << 
+	      content_tag(:h1, title)
+	    end
+	  end
+
+	  def _body(content)
+	    content_tag(:div, class: "modal-body") { content }
+	  end
+
+	  def _footer(type, button, cancel, href = nil, redirect = true)
+	    content_tag(:div, class: 'modal-footer') do
+	      link_to(cancel, "#", class: "btn", "data-dismiss" => "modal", "aria-hidden" => "true") << 
+	      (type == :submit ? submit_tag(button, id: :submit, class: "btn btn-primary") : (redirect ? link_to(button, href, class: "btn btn-primary") : ""))
+	    end
+	  end
+	end
+end