-
Notifications
You must be signed in to change notification settings - Fork 6
/
Copy pathREADME
133 lines (89 loc) · 4.75 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
ChainSelects
============
Let's say you are developing an application for a car dealer. Assuming that the car dealer sells many types of cars from different manufacturers. Each car manufacturer has many types of brands. For each brand, there are many models. The big question is: how do you deal with the interface for the user for this kind of hierarchical content?
Chain selects can provide an intuitive interface for this kind of problem. Chain or dependent selects are html drop-down select boxes that are linked to each other. On the examples below, let's say you selected Toyota as manufacturer, brands under Toyota will automatically be displayed on the second drop-down. Selecting a particular brand will then display the models on the third drop-down for a particular brand.
ChainSelects makes it easier for you to generate these drop-down boxes. Install, configure, run and you're done! Fully working AJAX-based chained select boxes with minimal work.
Example
=======
a. Simple
chain_select_ajax(:models => [:manufacturer, :brand, :make_model])
b. Values Specified
chain_select_ajax(:models => [:manufacturer, :brand, :make_model], :spacer => '|', :values => {:manufacturer => 2, :brand => 4, :make_model => 3}, :prefix => 'chain_select_two')
c. Separate Rendering
chain_select_stand_alone(:manufacturer, :prefix => 'chain_select_three', :value => 2)
chain_select_stand_alone(:brand, :prefix => 'chain_select_three', :value => 4, :parent => 2)
chain_select_stand_alone(:make_model, :prefix => 'chain_select_three', :value => 3, :parent => 4)
chain_select_indicator_stand_alone('chain_select_three')
Please see http://chainselects.hypermediasoft.com/ for live examples.
Installation
=======
1. Install
./script/plugin install git://github.com/diwadm/ChainSelects.git
./script/generate chain_selects_route
2. Configure your models
Note: models need to have a name method, as the text in the drop-downs will come from this.
class Manufacturer < ActiveRecord::Base
has_many :brands, :dependent => :destroy
validates_presence_of :name
acts_as_chainable :to => :brand, :root => true
end
class Brand < ActiveRecord::Base
belongs_to :manufacturer
validates_presence_of :name
has_many :make_models, :dependent => :destroy
acts_as_chainable :to => :make_model, :from => :manufacturer
end
class MakeModel < ActiveRecord::Base
belongs_to :brand
validates_presence_of :name
acts_as_chainable :select_label => 'Model', :from => :brand
end
3. Render
In your controller:
include ChainSelectsHelper
# sample controller
class DemoController < ApplicationController
layout 'public'
def index
end
end
In your view:
<html>
<head>
<%= javascript_include_tag :defaults %>
<%= stylesheet_link_tag 'chain_selects' %>
</head>
<body>
<%= chain_select_ajax(:models => [:manufacturer, :brand, :make_model]) %>
</body>
</html>
Done!
Parameters and Options
=======
chain_select_ajax(options = {})
* :prefix - Prefix is the name of a set of chain selects. You can have multiple chain-selects - just like in the examples above - which accesses the same set of models. Prefix is important as it is used to differentiate the html elements.
* :models - Array which contains the models for the chained select. The order in which the drop-downs are rendered depends on the way you specified them.
* :spacer - Text or code that will be rendered between two drop-downs.
* :disable_ajax_indicator - Set to true if you don't want the AJAX spinner indicator.
* :values - You can set the values that are selected when the page is loaded. Example:
:values => {:manufacturer => 2, :brand => 4, :make_model => 3}
Note that you could not skip the value for a model that has a child.
chain_select_stand_alone(model_name, options = {})
* model_name - Name of the model.
* options[:prefix] - Name of the chain select set where the models belongs. Make sure you have the same prefix for all the models that you are rendering separately.
* options[:value] - Value selected.
* options[:parent] - Value selected for the model's parent. You need to specify both the :parent and :value.
acts_as_chainable(options = {})
* :to - Name of the model's child.
* :root - Set to true if the model is the top of the hierarchy.
* :from - Name of the model's parent. Not applicable for root model.
* :select_label - First option that will appear in the model's drop-down. Default is "--[model name]--".
* :order - Ordering of the data. Same option from ActiveRecord::Base.
* :limit - Limits the number of rows of data. Same option from ActiveRecord::Base.
* :conditions - Conditions for the model. Same option from ActiveRecord::Base.
Copyright and Author
=======
Copyright (c) 2010 Diwa del Mundo, released under the MIT license
Credits
=======
Peter Berkenbosch - bug fix