Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

A bit of doc love, for me and for Github.

  • Loading branch information...
commit 02700530fdd69ffe53f4533ebfa5342cdaba3c75 1 parent 8029a27
@baldowl authored
Showing with 103 additions and 110 deletions.
  1. +102 −110 README
  2. +1 −0  README.rdoc
View
212 README
@@ -40,19 +40,18 @@ Streamlined[http://streamlined.relevancellc.com/].
== What isn't it?
-Scaffolding. This is not a view generator for you to then customise.
-Either it provides the interface you want, or it doesn't. (With a
-limited, but hopefully expanding, set of exceptions.)
+Scaffolding. This is not a view generator for you to then customise. Either it
+provides the interface you want, or it doesn't. (With a limited, but hopefully
+expanding, set of exceptions.)
-For everyone. This is for applications that have a public interface and
-a restricted-access administrative interface. Its goal is not to
-generate views you would otherwise have to craft manually, so much as
-generating views you otherwise wouldn't bother to create. Of course, a
-neat side-effect of using this is that your boss (or your client's IT
-manager) can make simple database-level changes that would otherwise
-require a developer to use either the console or direct SQL. If you're
-trying to create an interface for all your users, this probably isn't
-for you.
+For everyone. This is for applications that have a public interface and a
+restricted-access administrative interface. Its goal is not to generate views
+you would otherwise have to craft manually, so much as generating views you
+otherwise wouldn't bother to create. Of course, a neat side-effect of using
+this is that your boss (or your client's IT manager) can make simple
+database-level changes that would otherwise require a developer to use either
+the console or direct SQL. If you're trying to create an interface for all
+your users, this probably isn't for you.
== Where is it?
@@ -86,13 +85,13 @@ case), you must specify it with the <tt>admin_model=</tt> and
class must respond to +authenticate+, +login+, or
+find_by_username_and_password+ and that method must take two strings and
return +nil+ for failure or a non-false value for success. It *must* return
-the authenticated user's id (or, in a less ideal turn, the user object
-itself: we will extract the id by ourself) -- the id will be stored in the
-session using the key provided by +admin_model_id+ and the currently
-logged-in user will be looked for; if the returned value responds to one or
-more of <tt>active?</tt>, <tt>enabled?</tt>, <tt>disabled?</tt> or
-<tt>admin?</tt>, they will be treated appropriately. So if other parts of
-your site do the same, things will Just Work.
+the authenticated user's id (or, in a less ideal turn, the user object itself:
+we will extract the id by ourself) -- the id will be stored in the session
+using the key provided by +admin_model_id+ and the currently logged-in user
+will be looked for; if the returned value responds to one or more of
+<tt>active?</tt>, <tt>enabled?</tt>, <tt>disabled?</tt> or <tt>admin?</tt>,
+they will be treated appropriately. So if other parts of your site do the
+same, things will Just Work.
=== History
@@ -122,8 +121,8 @@ For the optional export mechanism you also need:
== How do I use it?
-Initially (after installing the plugin, obviously), you need to add a
-few lines to the bottom of your environment.rb or in an initializer file:
+Initially (after installing the plugin, obviously), you need to add a few
+lines to the bottom of your environment.rb or in an initializer file:
AutoAdmin.config do |admin|
# This information is used by the theme to construct a useful
@@ -152,27 +151,24 @@ to http://localhost:3000/admin/. Yes, it installs its own routes, but they are
partially configurable; for now, just don't try to use <tt>/admin/</tt> for
anything else.
-To customise which fields appear in the edit and list screens, you go on
-to...
+To customise which fields appear in the edit and list screens, you go on to...
== How does it work? - Part I, Declarative UI definition
-The plugin adds a number of singleton methods to ActiveRecord::Base,
-which permit you to declare how the administration interface should
-behave.
+The plugin adds a number of singleton methods to ActiveRecord::Base, which
+permit you to declare how the administration interface should behave.
-This set of methods, which are quite central to the utility of the
-plugin, have grown rather organically, over a period of time (as has my
-Ruby-fu). I've attempted to clear out the most glaring API
-inconsitencies, but it's still a bit of a mess. Some of the
-implementations definitely leave a bit to be desired. Cleaning this up
-is near the top of my TODO list. That said, it should all work. :)
+This set of methods, which are quite central to the utility of the plugin,
+have grown rather organically, over a period of time (as has my Ruby-fu). I've
+attempted to clear out the most glaring API inconsitencies, but it's still a
+bit of a mess. Some of the implementations definitely leave a bit to be
+desired. Cleaning this up is near the top of my TODO list. That said, it
+should all work. :)
I really need to go through and write decent documentation for all the
-published methods, but for now, the following summary should at least
-act as a guide. Essentially, inside the model, you can use the following
-methods:
+published methods, but for now, the following summary should at least act as a
+guide. Essentially, inside the model, you can use the following methods:
[object_group(group_name)]
Declares which 'object group' this object belongs to, for use in the
@@ -279,29 +275,27 @@ methods:
== Field Definition Block?!?
-A number of the above methods provide for a block to declare what fields
-are to be shown. This is achieved by yielding a builder to the block.
-Depending on context, the mood of a theme author, and the phase of the
-moon, a given block will see several builders in its lifetime. Not all
-builders will have an active object; all will respond to the +object+
-method, though. A basic field definition block will just call a field
-helper on the builder for each field that it wishes to display. The
-+auto_field+ helper (which automatically determines an appropriate field
-type based on column and association metadata) is available if you only
-want to specify the field type for some of the fields. All field helpers
-take <tt>(field_name, options={}, *other_stuff)</tt>. Most just take the two
-parameters, and I'm considering deprecating the extra parameters on
-those that currently support them. Note that unlike a standard builder,
-you don't have to do anything with the return value; the theme's actual
-FormBuilder is wrapped by a DeclarativeFormBuilder, which takes care of
-that for you.
-
-In theory, there's no compelling reason you can't add complex logic to a
-field definition block, such as examining the current user, or even the
-builder's active object (though I strongly encourage you to handle nil
-permissively, at this stage). It would be unwise to vary the fields
-returned based on the object for a list view, for fairly obvious
-reasons.
+A number of the above methods provide for a block to declare what fields are
+to be shown. This is achieved by yielding a builder to the block. Depending on
+context, the mood of a theme author, and the phase of the moon, a given block
+will see several builders in its lifetime. Not all builders will have an
+active object; all will respond to the +object+ method, though. A basic field
+definition block will just call a field helper on the builder for each field
+that it wishes to display. The +auto_field+ helper (which automatically
+determines an appropriate field type based on column and association metadata)
+is available if you only want to specify the field type for some of the
+fields. All field helpers take <tt>(field_name, options={},
+*other_stuff)</tt>. Most just take the two parameters, and I'm considering
+deprecating the extra parameters on those that currently support them. Note
+that unlike a standard builder, you don't have to do anything with the return
+value; the theme's actual FormBuilder is wrapped by a DeclarativeFormBuilder,
+which takes care of that for you.
+
+In theory, there's no compelling reason you can't add complex logic to a field
+definition block, such as examining the current user, or even the builder's
+active object (though I strongly encourage you to handle nil permissively, at
+this stage). It would be unwise to vary the fields returned based on the
+object for a list view, for fairly obvious reasons.
== Available Form Helpers
@@ -339,17 +333,17 @@ reasons.
* +static_image+ sports a number of options used to build an hash suitable for
the +tag+ helper responsible for the creation of final <tt><img></tt> tag:
- * <tt>:controller</tt> (default "auto_admin") and :action (default "edit")
- allows to select a controller which should return the image based upon
- this object's id;
+ * <tt>:controller</tt> (default "auto_admin") and <tt>:action</tt> (default
+ "edit") allows to select a controller which should return the image based
+ upon this object's id;
- * :src override the previous two options and can be used with any URL,
- static or dynamic;
+ * <tt>:src</tt> override the previous two options and can be used with any
+ URL, static or dynamic;
- * with :size one can write the width and height used to show the image
- (format: "XxY");
+ * with <tt>:size</tt> one can write the width and height used to show the
+ image (format: "XxY");
- * :alt, which defaults to this object's to_label().
+ * <tt>:alt</tt>, which defaults to this object's +to_label+.
Everything else is passed as is to the +tag+ helper (so one could use
<tt>:style</tt> or <tt>:class</tt> to alter the looks of <tt><img></tt>).
@@ -373,12 +367,12 @@ reasons.
* +hyperlink+ automatically generates a link to the "edit view" of its first
argument (which must be one of the primary objects); alternatively you can
- use the :url option to generate a custom link:
+ use the <tt>:url</tt> option to generate a custom link:
f.hyperlink :picture, :url => f.object.picture.url
Anyway, the link caption will be the URL itself, unless you use the option
- :link_text as follow:
+ <tt>:link_text</tt> as follow:
f.hyperlink :picture, :url => f.object.picture.url,
:link_text => 'The picture'
@@ -392,16 +386,15 @@ reasons.
== How does it work? - Part II, Themes
The theme bundled with the plugin is named 'django'; all credit for its
-excellent appearance goes to the Django project. I hope we can get a
-couple of standard themes, but they won't be coming from me...
-experience shows that I shouldn't try to make things look good. I
-believe I've successfully drawn lines in all the right places for what
-is in the plugin's core, and what's in a theme. I've already developed
-most of a second theme (which will not be released) for my employer, so
-the infrastructure is mostly proven. A more coherent HOWTO on creating
-themes (which can just be installed as seperate Rails plugins, then
-selected in environment.rb) will be forthcoming Real Soon Now, though
-this section has ended up covering most of the basics.
+excellent appearance goes to the Django project. I hope we can get a couple of
+standard themes, but they won't be coming from me... experience shows that I
+shouldn't try to make things look good. I believe I've successfully drawn
+lines in all the right places for what is in the plugin's core, and what's in
+a theme. I've already developed most of a second theme (which will not be
+released) for my employer, so the infrastructure is mostly proven. A more
+coherent HOWTO on creating themes (which can just be installed as seperate
+Rails plugins, then selected in environment.rb) will be forthcoming Real Soon
+Now, though this section has ended up covering most of the basics.
The 30 second summary -- a theme comprises:
@@ -447,46 +440,45 @@ methods to a directory(*subdirs) singleton method, which you must define --
presumably using \_\_FILE\_\_.
NB: For good reasons that I can't remember right now, a couple of helper
-methods have APIs that don't match the standard Rails FormBuilder,
-despite matching names. The one that comes to mind is +select+ -- the
-choices have been moved into the options hash, to keep all method
-signatures of the form (field_name, options, *other_stuff).
+methods have APIs that don't match the standard Rails FormBuilder, despite
+matching names. The one that comes to mind is +select+ -- the choices have
+been moved into the options hash, to keep all method signatures of the form
+(field_name, options, *other_stuff).
== What's planned, but missing?
-The ability for the application to inject custom field types into the
-base FormBuilder and FormProcessor. The theme-specific versions of these
-classes are available so that, for example, a theme can decide how a
-date_field should be presented, and can correspondingly recover the
-values from multiple inputs... they don't map as well to an
-application's requirement for a 'currency' field. Of course, there's
-nothing stopping an application re-opening the classes and adding an
-appropriate helper method to each... there's just a bit of undesirable
-complexity involved if you want auto_field to detect and use it (which
-suggests to me that auto_field needs a bit of a rethink).
+The ability for the application to inject custom field types into the base
+FormBuilder and FormProcessor. The theme-specific versions of these classes
+are available so that, for example, a theme can decide how a date_field should
+be presented, and can correspondingly recover the values from multiple
+inputs... they don't map as well to an application's requirement for a
+'currency' field. Of course, there's nothing stopping an application
+re-opening the classes and adding an appropriate helper method to each...
+there's just a bit of undesirable complexity involved if you want auto_field
+to detect and use it (which suggests to me that auto_field needs a bit of a
+rethink).
-A way for the application to reliably extend the AutoAdminController,
-and add appropriate views somewhere, for those occasions when you have a
-couple of screens that need to be hand-crafted, such as a statistics
-display, or a particular edit screen that needs a specialised workflow.
-Note that if you feel this constraint too much, you're probably pushing
-the plugin into a role it doesn't fit.
+A way for the application to reliably extend the AutoAdminController, and add
+appropriate views somewhere, for those occasions when you have a couple of
+screens that need to be hand-crafted, such as a statistics display, or a
+particular edit screen that needs a specialised workflow. Note that if you
+feel this constraint too much, you're probably pushing the plugin into a role
+it doesn't fit.
-Simple methods allowing an application to add navigation options, and
-perhaps the ability to insert Components into the "dashboard" on the
-index page?
+Simple methods allowing an application to add navigation options, and perhaps
+the ability to insert Components into the "dashboard" on the index page?
-A top-level "menu", containing links to the primary object lists by
-default, that a theme can permanently display.
+A top-level "menu", containing links to the primary object lists by default,
+that a theme can permanently display.
== Longer-term architectural considerations?
-After starting off defining the administration interfaces directly in
-the models (as Django does), I was strongly considering moving them all
-into an application-specific controller, that would subclass
-AutoAdminController. I haven't gotten around to doing that, and am now
-quite intruiged by the approach taken by Streamlined -- adding a new
-type of class. Any such move is primarily aimed at solving a problem I'm
-not yet sufferring, though, so for now it's just a topic to ponder.
+After starting off defining the administration interfaces directly in the
+models (as Django does), I was strongly considering moving them all into an
+application-specific controller, that would subclass AutoAdminController. I
+haven't gotten around to doing that, and am now quite intruiged by the
+approach taken by Streamlined -- adding a new type of class. Any such move is
+primarily aimed at solving a problem I'm not yet sufferring, though, so for
+now it's just a topic to ponder.
View
1  README.rdoc
Please sign in to comment.
Something went wrong with that request. Please try again.