- 1 The big picture
- 2 Open Questions
- 3 Terminology
- 4 Layout
- 5 Models
- 6 Helper
- 7 Layout
- 8 Writing Widgets
The big picture¶
- a set of placeable widgets
- a layout that can take widgets (a layout is a set of containers, or areas on the page, where widgets can be placed)
- a way to match widget with layout
Open Questions¶
- Do we use separate controllers or cells for widgets?
- How does the edit mode look like? For possibilities have a look on widgets-page.
Terminology¶
owner: the actual owner of the place (e.g. site-home, profile, dashboard) where the widget is being displayed. this is always a user or a group, and is certain to be there.
widget: some object that can give us the options of the widget. it includes a definition file (definition.yml), and a set of partials, and maybe some controller code. not sure if we are going to base it on cells or something like that or not.
WidgetSetting: a record in a database that records the configuration options for a particular widget in a particular place. a widget setting is therefore associated with a widget and some context.
widgetable: the database object that represents the page that we are going to render with widgets. for a group, it would be the profile. for a user, it could be their profile. if we had dashboard widgets, it would be the user. for site-home, the context would be the site itself.
fixed layout: we come up with some pre-canned partials that then people can place widgets into specific spots.
edit mode: The owner of a widget (site-home admin / group admin) can change the placement and settings for widgets when he is in something like an edit mode. For possible solutions on edit modes see widgets or open questions.
Layout¶
possible fixed layouts:
.-------. .---+---.
| | | | |
+-------+ +---+---+
| | | |
| | | |
'-------' '-------'
.---+---. .---+---. .-------. .-------.
| | | | | | | | | |
+---+---+ +---+---+ +---+---+ +-------+
| | | | | | | | | |
+-------+ +---+---+ +---+---+ +-------+
| | | | | | | |
| | | | | | | |
'-------' '-------' '-------' '-------'
.---+---. .---+---. .---+---.
| | | | | | | | |
| +---+ | | | +---+ |
| | | | | | | | |
+---+---+ +---+---+ +---+---+
| | | | | |
| | | | | |
'---+---' '---+---' '---+---'
or, broken down into possible rows:
.---+---. .---+---. .---+---. .-------. .---+---.
| | | | | | | | | | | | | |
| +---+ | | | +---+ | +-------+ +---+---+
| | | | | | | | |
+---+---+ +---+---+ +---+---+
This breaks down in four possible sizes for widgets:
- Small
- Wide
- Tall
- Full
Instead of these canned list of fixed layouts, we could, in the long term, allow flexible placement of these four different sizes.
Models¶
create_table :widgets do |t|
t.string :name # determines what widget definition file to use
t.string :placement # where in the layout this widget goes
t.integer :size # enum of SIZES
t.integer :widgetable_id # \ a thing that
t.string :widgetable_type # / holds widgets
t.text :options # serialized hash of configured options
end
#
# Create a WIDGETS definition hash in the form of:
#
# { 'widget_name_1' => <<contents of yml definition>>,
# 'widget_name_2' => <<contents of yml definition>> }
#
widget_files = RAILS_ROOT+'/views/widgets/*/definition.yml'
WIDGETS = Hash[
Dir.glob(widget_files).collect {|file|
widget_name = File.basename(File.dirname(file))
definition_hash = YAML::load_file(file)
[widget_name, definition_hash]
}
].freeze
class Widget < ActiveRecord::Base
SIZES = {'wide' => 1, 'tall' => 2, 'small' => 3, 'full' => 4,
1 => 'wide', 2 => 'tall', 3 => 'small', 4 => 'full'}.freeze
# a widgetable is a thing that owns widgets
belongs_to :widgetable, :polymophic => true
def owner
widgetable.entity
end
# returns the view template for this widget
def template
options['partials'][SIZES[self.size]]
rescue
'not_found'
end
def options
WIDGETS[self.name] || {}
end
# returns a hash in the form:
# {'placement1' => <<widgetobject1>>, 'placement2' => <<widgetobject2>>}
def self.to_hash(widgets)
Hash[ widgets.collect{|w|[w.placement,w]} ]
end
end
end
class Profile
has_many :widgets, :as => 'widgetable', :dependent => :destroy
end
Helper¶
# render a single widget
def render_widget(widget)
render :template => widget.template, :locals => {:widget => widget}
end
# extra widgets have no placement, they are just numbered.
# this will render these extra/numbered widgets
def get_the_extra_widgets(widgets, &block)
i = 0
while widgets[i.to_s]
yield widgets[i.to_s]
i+=1
end
end
in controller:
def render_widget_template(profile)
render :template => profile.widget_layout, :locals => {:widgets => Widget.to_hash(profile.widgets)}
end
Layout¶
And the view code for this:
.---+---.
| | |
+---+---+
| |
+-------+
| |
| |
'-------'
<table>
<tr>
<td><%= render_widget(widgets['top_left']) %></td>
<td><%= render_widget(widgets['top_right']) %></td>
</tr>
<tr>
<td colspan="2"><%= render_widget(widgets['middle']) %></td>
</tr>
<% get_the_extra_widgets(widgets) do |widget| %>
<tr>
<td colspan="2"><%= render_widget(widget) %></td>
</tr>
<% end %>
end
</table>
Writing Widgets¶
The widget writer’s api:
there will be different partials depending on the placement of the widget. The possible sizes are:
- tall: a narrow layout, but one that might go on for a while.
- wide: takes up the full width, but has limited height.
- full: no limitations on height or width
- small: limited height and limited width
In the partial, there are these variables: widget, current_user, widget.options.
widgets/upcoming_events/definition.yml
name: Upcoming Events
partials:
wide: events_wide
small: events_small
tall: events_tall
supported_owners:
- group
- user
- site
options:
- name: "limit"
description: "Show no more than this many events"
type: integer
default: 10
- name: "starred_only"
description: "Only starred events"
type: boolean
default: false
widgets/upcoming_events/events_wide.html.erb
events = Event.upcoming.access_by(:owner => widget.owner, :current_user => current_user).starred(widget.options:starred_only).find(:all,:limit => widget.options:limit)
<% events.each do |event| %> <%=h event.title %> <%= friendly_date(event.when) %> <% end %>
Widget with separate controller
----------------------------------
bq. I don't understand what is written here. -elijah
widget/upcoming_events/controller.rb
- \/\/ this actually goes in some seperate module
widgets/upcoming_events/events_wide.html.erb
- options can be passed as local too
events = Event.upcoming.access_by(current_user).starred(
widgets/_page_list.html.erb
<% - expected options:
- - number_of_records
default_options = {:number_of_records => 20}
- merge given options with the widgets default options
options.merge!(@@default_options)
params:path ||= ""
params:path = params:path.split(‘/’)
params:path += ’descending’, ’updated_at’ if params:path.empty?
params:path += [‘limit’,options:number_of_records]
pages = Page.find_by_path(params[:path], options_for_group(group))
-%>
<%= “Page list”:page_list %>
<%= render :partial => ‘pages/list’ %>
Tests
------------------------
Functional Tests for Widgets:
# showing the right widgets
1. Loading a Site Home should work, and show the default widgets for site homes
2. Changing the sites default settings for the site home, should work and end up in showing the widgets on the right position again
3. Changing the users default settings for that site home, should work, and end up in showing the widgets in the right position again.
# editing the widgets (presumes to know in what way the edit mode works)
1. checking all the ajax / js functions for moving, folding and closing widgets
Discussion
--------------------------------
(the original discussion was in German, this is a rough translation)
# Problem: The Site defines default values for displaying the sie-home. This includes a set of widgets to display, and where to display them. Now, once a user changes these settings for himself, we need to find a way to merge the default settings, with the users ones.
Site Settings:
Widget1: :position => 'left_sidebar', :order => 1, :options => { :number_of_records => 12 }
Widget2: :position => 'left_sidebar', :order => 2
Widget3: :position => 'left_sidebar', :order => 3, :options => { :number_of_records => 5 }
User Settings:
Widget2: :position => 'left_sidebar', :order => 1
From these to sets of options
a.) Onlydisplay Widget 2 (as it is the only widget that is found searching by user_id_and_page_id)
b.) Only move Widget2 to the top of the Widgets (when merging the two sets of options)
1 see two possible solutions:
1. I think that as soon as a user updates any setting in a specific widget target (e.g. left_sidebar), all widgets in that target need to get a setting for the user. ah okay, i even thought that all widgets would need a setting for the user. But i think by target could be more convenient.
But what happens when a widget (e.g. group-wiki) is displayed on two targets?
What should happen? nothing happens... Okay :p
I added a position field, because we need to find WidgetSettings by position
. gut, we should discuss in english, then we can put it on the wiki later.
Wollen wir die ganzen verplanten diskussionen nicht raus nehmen? Uebersetzt kommen die eh nicht richtig rueber :)
# a: i think it's enough to save widget_settings for users, because groups will probably not want to define default settings how to view the site home for their users.
# n: i thought like this groups might define default settings for their group home
# a: up to now, i think we're only talking about site homes. But customizing group homes i good as well. But then we need a combination of site_id and group_id .. erm, yeah, well.. entity_id
# n: i just thought it makes sense to be able to save widget settings in different contexts
# n: imho it makes no sense to bind the settings to users, and from the usability of the model nothing changes when using polymorph association
# a: kk
# A: to me it could make sence, when thinking about custom appearance for site home after all, to
# have something like a SiteHomeSettings Model, that is created for a user once he starts to
# customize the site home appearance
# N: widget settings are fetched very often, so the queries should be superfast. having an overall
# settings model would either make that table pretty big, or require serialization (which slows
# things terribly down if the serialized field stores conditions by which you want to find records)
