A first, tentative attempt at newbie documentation
Jim Gagne
am to this whole business. In the spirit of trying to contribute
without driving more experienced people crazy, here is my initial
offering of how to use some of the features that I initially found
confusing. Please feel free to correct any errors. If you think it's
useful, feel free to post it on the wiki -- I couldn't figure out how
to create a new blank page to put it on, and besides I'm sure it needs
some corrections.)
=Getting Started on ActiveScaffold
==Abbreviations:
AS = ActiveScaffold
RoR = Ruby on Rails
CRUD = Create, Read (usually called Show), Update, Delete
LCRUD = List plus CRUD
==Newbie Suggestions
Install AS in your project using the excellent instructions on the
getting started page, http://activescaffold.com/tutorials/. Once
you've installed the plugin, be sure you have a layout page (e.g.,
application.rhtml in the views/layouts folder) that at a minimum says
something like the following:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
_
<head> _
<meta http-equiv="content-type" content="text/html;charset=UTF-8" /
> _ <title>Owners: <%= controller.action_name %></title>
<%= javascript_include_tag :defaults %>
<%= active_scaffold_includes %>
</head> _
<body>
<%= yield %>
</body> _
</html>
If you're new to RoRs, be sure your model displays properly using the
default Rails scaffolding (see any RoR introductory text). Put the
following line in your model_name_controller:
scaffold :model_name
If everything works, turn on AS with the same line slightly modified:
active_scaffold :model_name
==Advantages of AS Over the Default RoR Scaffold
1. Most everything happens live on the same page, using AJAX/
Javascript: the page opens an inline box (temporarily replacing the
line containing the affected record) to Create, Show, or Update a
record. When you're done, the table is restored, including any new
information. AS offers robust behavior when the user has disabled
Javascript in his browser.
2. The user interface and appearance of the table are vastly superior
to the default RoR scaffold. You can readily modify the appearance
using the included CSS file -- but watch out, because every time AS
starts up, the stylesheet in public/stylesheets/active_scaffold/
default/stylesheet.css is replaced, copied from vendor/plugins/
active_scaffold/frontends/default/stylesheets/stylesheet.css (which
you're free to modify). I'm pretty sure the CSS file you use for the
rest of your layout can override the AS stylesheet.css. A CSS editing
program is a good idea here.
3. It's relatively simple to choose which columns (fields) you display
and in what order. Feel free to change the column heading labels.
Different LCRUD actions can display different fields. So long as you
have a method of the same name in your model file (i.e., under app/
models), you can add custom fields, though it takes some work to be
able to sort on these fields by clicking the heading.
4. The built-in Search button opens an input box, which filters the
records based on what was entered. The programmer can choose standard
search (enter some text and press Enter) or LiveSearch, where the
system responds to each key as it's entered (though this may use a lot
of server resources). You can set which fields are searched on; the
default is unmodified ActiveRecord text fields.
5. The user can reorder the records in the table just by clicking on
the column heading of any field. The first click orders the records in
by that field ascending order, second click in descending order, and
the third click restores whatever the order was previously. (This only
works on ActiveRecord fields retrieved from the database -- not
derived or custom fields -- because records are sorted using a
database call, but there are ways around this that I haven't figured
out yet.)
6. The AS Demo (http://demo.activescaffold.com/) does a terrific job
of showing how to set up an active scaffold with a variety of table
relationships: user management, habtm, has_many, belongs_to, has_one,
join model, and polymophic. It's not as good at showing how to put
multiple scaffolds on the same page, or building custom pages - but it
turns out that's easy (see below).
==Displaying Default and Custom Scaffolds
For the default scaffold, you don't need a view (.rhtml) file of the
same name as the model you're displaying, but be sure you do have a
layout file (see above). You can use a custom layout file by including
the following line just before "active_scaffold :model_name" in the
model_controller (where layout_name.rhtml is the layout file in the
app/views/layouts folder):
layout "layout_name"
For custom layouts, here's the drill (http://activescaffold.com/
docs/):
1. Set up and customize a working scaffold in *each* model
controller.rb. So if your models are User, Message, and Product, be
sure you get proper scaffold behavior when you log into http://localhost:3000/user,
http://localhost:3000/method, and http://localhost:3000/product. Make
sure all the fields, custom links, etc., are working properly.
2. Create your view (.rhtml) files, with the following line where you
want the scaffold to go (and see the bottom of http://activescaffold.com/docs/
for an example):
<%= render :active_scaffold => 'model_name', :constraints => {hash
of constraints},:label => 'Custom Scaffold Title' %>
The constraints hash filters (limits) the records displayed, allowing
you to change which records different classes of users can see. Using
this approach, you can have as many different types of scaffolds on a
page as you want.
If the only stuff on the custom page is the scaffold, fixed HTML text,
and some links, you don't need a controller method for that custom
page in your model controller.
So far, I don't know how to customize a given model scaffold for
different users, aside from the varying constraints (different sets of
records) offered by "render :active_scaffold" as described above. How
does one vary the available fields? I've seen talk in the forums about
how to do this, but I've not yet gotten that far. I *suspect* field
and form overrides are one way. Somehow I doubt you could put a whole
new scaffold within a method, or create a new scaffold within a
duplicate (different name) model controller.
==Inserting Custom Links (http://activescaffold.com/docs/api-action-
link)
In my e-mail application, I put a Reply link to the right of each
message in the List table (right where the Edit, Update, and Delete
links go unless you remove them). Here's how. Put the following within
the active_scaffold :model_name do |config| block:
config.action_links.add 'reply_to_message', :label =>
'Reply', :type => :record, :page => true
The ActionLink documentation shows what the options mean, but
"reply_to_message" is the method, "Reply" is the label, ":type
=> :record" puts the link to the right of each record (rather than
once for the scaffold), and ":page => :true" tells AS we'll be moving
to a different view page. AS helpfully sends your method a
params([:id]) containing the record id, free for nothing.
You can add more than one of these custom links. If you had to
completely override one of the standard CRUD actions, I imagine you
can turn it off (e.g., config.actions.exclude :create) and then write
your own custom Create link. Or override the do_create method in your
controller, adding a "super" at the end of the method when/if you want
to return to default behavior.
Jim Gagne
link of this page.
Lance Ivy
Michael K
I went ahead and wiki-fied this (the best I could, the wiki markup is
lacking a little, the table markup doesn't even work :/)
The best place for corrections to occur when it comes to a wiki - is
on the wiki. :)
http://wiki.activescaffold.com/wiki/show/NewbieHelp
Thanks,
Michael
Jim Gagne
> I went ahead and wiki-fied this (the best I could, the wiki markup is
> lacking a little, the table markup doesn't even work :/)
>
> The best place for corrections to occur when it comes to a wiki - is
> on the wiki. :)
Dear Michael,
Looks GREAT! How'd you do that? First, where is the documentation for
the markup syntax? Second, how DO you create a new wiki page?
THANKS FOR YOUR HELP.
---Jim Gagne---
jb
The wiki engine used here is Instiki.
Read this: http://instiki.org/show/WikiSyntax
Further you can use the textile markup see
http://hobix.com/textile/quick.html
http://hobix.com/textile/
To make a new page you can type a word/page in CamelCase
or use [[new page name]]
Save and you see the name with an ? mark. Click on it and you'r in
your new page.
Regards,
Joost