Rails - Nov 2005 - RFC: Standardising flash usage amongst Rails applications & generators

Hi all

This is (hopefully) a more coherent version of what I posted in reply
to James'' announcement of rails-engines.

With the expected increase in pluggable apps (in the form of engines),
as well as the increasing number of generators being made available, I
would suggest that the community standardise on a few basic flash
names. The utility in doing this, as far as I see, is to make new
engines entirely pluggable, as illustrated by the following.

I was playing around with the new login engine, and dropped it into an
existed application. Within this app (and indeed in all Rails apps I
develop), I check in the flash for flash[:notice] and flash[:warning]
and display them if they exist. The reason for this distinction is so
that normal status messages (:notice) are displayed in one way - an
unobtrusive green background - whilst errors and such (:warning) are
displayed on a more prominent red background. However, in the salted
login generator (and by extension the login engine), the code uses
notice and message instead. Therefore, I had to change all the
occurrences of message with warning to get the engine to play nicely
with my app. Moreover, other apps (probably - I can''t cite any
examples off-hand) use other names. Likewise, other applications add
all messages to notice (login generator for example), which makes it
impossible to distinguish between different types of flash without
going through and changing the code yourself, which somewhat negates
the usefulness of these.

What I propose is that a standard be established for flash names, such
that if you check for and display the standard flash names in your
layout, any engines or generators you use in your app will
automatically fit into your layout. I certainly don''t want to make
supporting this an onerous burden on the part of developers, so I
think that it would be wise to limit these to just a few key
categories. Based on my own experiences, I''d suggest something along
the lines of the following (the names are the best I can think of,
anyone is welcome to suggest better ones):

  :notice for positive feedback (action successful, etc)
  :message for neutral feedback (reminders, etc)
  :warning for negative feedback (action unsuccessful, error encountered, etc)

Then, in your controller or view you could place code such as the following:

  // FLASH_NAMES = [:notice, :warning, :message]

  <% for name in FLASH_NAMES %>
    <% if flash[name] %>
      <%= "<div
id=\"#{name}\">#{flash[name]}</div>" %>
    <% end %>
  <% end %>

and thus gives you the ability to independently theme with CSS the
different flashes according to their nature. Alternately, if you don''t
need (or want to) distinguish between the different flashes you can
choose to theme them the same way and thus not lose anything except a
FEW lines of extra code.

Naturally, my suggestions are influenced by how I use the flash, and
as such I might have overlooked a better way of doing things, or my
proposal might seem unnecessary. If this is the case, please someone
point me to the light!

Your comments?

Luke

Excellent idea! I second that.

In the spirit of convention over configuration though, would it not be an
idea to have added helpers that will make this even easier?

What I suggest is something like what we are all used to in log4j for
instance: logger.debug(..) logger.warn(..) or logger.info(..) (with similar
support on the view side). That way these "standard" categories of
flash
messages can be encapsulated in a more formal way ... yet still be
implemented in the underlying flash structure (somewhat like Struts''
ActionMessage class).


_______________________________________________
Rails mailing list
Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
http://lists.rubyonrails.org/mailman/listinfo/rails

I am behind this 178%. Absolutely.

I can see no harm in settling on a standard set of ''normal''
flash
messages, and the three types you''ve proposed seem quite appropriate.
If Engine developers aren''t keen on this, or want to do something more
esoteric, they should clearly document what their controllers may be
putting into the flash. In fact this is a good idea for all Engines
(and Plugins?) anyway.

In terms of the display, I dont'' think any Engine views should present
anything from the flash -  that should be left as a part of the
application layout and therefore fully in the developer''s domain.

Conventions are fun! ;-)

james

On 11/4/05, Luke Randall
<luke.randall-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
wrote:
> Hi all
>
> This is (hopefully) a more coherent version of what I posted in reply
> to James'' announcement of rails-engines.
>
> With the expected increase in pluggable apps (in the form of engines),
> as well as the increasing number of generators being made available, I
> would suggest that the community standardise on a few basic flash
> names. The utility in doing this, as far as I see, is to make new
> engines entirely pluggable, as illustrated by the following.
>
> I was playing around with the new login engine, and dropped it into an
> existed application. Within this app (and indeed in all Rails apps I
> develop), I check in the flash for flash[:notice] and flash[:warning]
> and display them if they exist. The reason for this distinction is so
> that normal status messages (:notice) are displayed in one way - an
> unobtrusive green background - whilst errors and such (:warning) are
> displayed on a more prominent red background. However, in the salted
> login generator (and by extension the login engine), the code uses
> notice and message instead. Therefore, I had to change all the
> occurrences of message with warning to get the engine to play nicely
> with my app. Moreover, other apps (probably - I can''t cite any
> examples off-hand) use other names. Likewise, other applications add
> all messages to notice (login generator for example), which makes it
> impossible to distinguish between different types of flash without
> going through and changing the code yourself, which somewhat negates
> the usefulness of these.
>
> What I propose is that a standard be established for flash names, such
> that if you check for and display the standard flash names in your
> layout, any engines or generators you use in your app will
> automatically fit into your layout. I certainly don''t want to make
> supporting this an onerous burden on the part of developers, so I
> think that it would be wise to limit these to just a few key
> categories. Based on my own experiences, I''d suggest something
along
> the lines of the following (the names are the best I can think of,
> anyone is welcome to suggest better ones):
>
>   :notice for positive feedback (action successful, etc)
>   :message for neutral feedback (reminders, etc)
>   :warning for negative feedback (action unsuccessful, error encountered,
etc)
>
> Then, in your controller or view you could place code such as the
following:
>
>   // FLASH_NAMES = [:notice, :warning, :message]
>
>   <% for name in FLASH_NAMES %>
>     <% if flash[name] %>
>       <%= "<div
id=\"#{name}\">#{flash[name]}</div>" %>
>     <% end %>
>   <% end %>
>
> and thus gives you the ability to independently theme with CSS the
> different flashes according to their nature. Alternately, if you
don''t
> need (or want to) distinguish between the different flashes you can
> choose to theme them the same way and thus not lose anything except a
> FEW lines of extra code.
>
> Naturally, my suggestions are influenced by how I use the flash, and
> as such I might have overlooked a better way of doing things, or my
> proposal might seem unnecessary. If this is the case, please someone
> point me to the light!
>
> Your comments?
>
> Luke
> _______________________________________________
> Rails mailing list
> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> http://lists.rubyonrails.org/mailman/listinfo/rails
>

> I am behind this 178%. Absolutely.
Cool, I''m happy to hear that =)
> In terms of the display, I dont'' think any Engine views should
present
> anything from the flash -  that should be left as a part of the
> application layout and therefore fully in the developer''s domain.
Yes, a very good point. If the engine ships with a layout, it should
be in the engine''s layout, and thus easily swappable with a new user
defined layout.

On Fri, Nov 04, 2005 at 03:12:15PM +0000, Luke Randall
wrote:
> What I propose is that a standard be established for flash names, such
> that if you check for and display the standard flash names in your
> layout, any engines or generators you use in your app will
> automatically fit into your layout. I certainly don''t want to make
> supporting this an onerous burden on the part of developers, so I
> think that it would be wise to limit these to just a few key
> categories. Based on my own experiences, I''d suggest something
along
> the lines of the following (the names are the best I can think of,
> anyone is welcome to suggest better ones):
> 
>   :notice for positive feedback (action successful, etc)
>   :message for neutral feedback (reminders, etc)
>   :warning for negative feedback (action unsuccessful, error encountered,
etc)
I like this.  Got a patch?

Thanks,

-- 
Keegan Quinn  <keegan-g9krTqASs3z/gVISOhv/wg@public.gmane.org>
CEO, Producer
the basement productions
http://www.thebasement.org


_______________________________________________
Rails mailing list
Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
http://lists.rubyonrails.org/mailman/listinfo/rails

Hi !

2005/11/5, Keegan Quinn <keegan@thebasement.org>:
> On Fri, Nov 04, 2005 at 03:12:15PM +0000, Luke Randall wrote:
> >   :notice for positive feedback (action successful, etc)
> >   :message for neutral feedback (reminders, etc)
> >   :warning for negative feedback (action unsuccessful, error
encountered, etc)
>
> I like this.  Got a patch?
I don't have a patch, I have a plugin instead.  Unfortunately, it
doesn't work at the moment.  I can't get tests to run, and when I add
the plugin, WEBrick fails silently at startup, with no error messages
:(

Code can be found here:  http://opensvn.csie.org/flash_helper_plugin/trunk/

If anybody would be good enough to give me a hand, I'd be very
grateful.  I thought I could release that yesterday afternoon, but I
was pressed for time.  I'm probably 80% of the way there.

Project's home page is at: 
https://opensvn.csie.org/traccgi/flash_helper_plugin/trac.cgi/

Blog article about the plugin:
http://rubyurl.com/pz0
http://blog.teksol.info/articles/2005/11/05/flash-helper-plugin-flash-standardization

Thanks for any help you may provide.

Bye !
--
François Beausoleil
http://blog.teksol.info/

_______________________________________________
Rails mailing list
Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
http://lists.rubyonrails.org/mailman/listinfo/rails

I can''t give you a patch right now, but inspecting the code,
there''s a
few things:

init.rb, in your requires: "fb" should be
"francois_beausoleil"

lib/francois_beausoleil/flash_helper/application.rb: the syntax for
''alias'' is:

alias :new_thing :old_thing, not alias :new_thing, :old_thing (i.e. no comma)

Finally, you can''t send :include methods to ApplicationController from
a plugin''s init.rb - the class has yet to be loaded. You can see the
warning if you run script/console, rather than script/server. So
instead, you''ll have to require users to include your modules in their
own application.rb/application_helper.rb files..

hope that helps

- james

On 11/5/05, Francois Beausoleil
<francois.beausoleil-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
wrote:
> Hi !
>
> 2005/11/5, Keegan Quinn
<keegan-g9krTqASs3z/gVISOhv/wg@public.gmane.org>:
> > On Fri, Nov 04, 2005 at 03:12:15PM +0000, Luke Randall wrote:
> > >   :notice for positive feedback (action successful, etc)
> > >   :message for neutral feedback (reminders, etc)
> > >   :warning for negative feedback (action unsuccessful, error
encountered, etc)
> >
> > I like this.  Got a patch?
>
> I don''t have a patch, I have a plugin instead.  Unfortunately, it
> doesn''t work at the moment.  I can''t get tests to run,
and when I add
> the plugin, WEBrick fails silently at startup, with no error messages
> :(
>
> Code can be found here:  http://opensvn.csie.org/flash_helper_plugin/trunk/
>
> If anybody would be good enough to give me a hand, I''d be very
> grateful.  I thought I could release that yesterday afternoon, but I
> was pressed for time.  I''m probably 80% of the way there.
>
> Project''s home page is at:
> https://opensvn.csie.org/traccgi/flash_helper_plugin/trac.cgi/
>
> Blog article about the plugin:
> http://rubyurl.com/pz0
>
http://blog.teksol.info/articles/2005/11/05/flash-helper-plugin-flash-standardization
>
> Thanks for any help you may provide.
>
> Bye !
> --
> François Beausoleil
> http://blog.teksol.info/
>
> _______________________________________________
> Rails mailing list
> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> http://lists.rubyonrails.org/mailman/listinfo/rails
>
>
>

> > I like this.  Got a patch?
I did have a few patches, but most of them have been superceded by
Francois'' work =)
> I don''t have a patch, I have a plugin instead.
Hey Francois

I haven''t had time to play with your code yet (other than look at the
code a bit), so I don''t have any ideas as to what''s wrong.
However, I
will have a chance to look into it in the next couple of days, and
hopefully will be able to help. However, I like what I''ve seen of it.
I didn''t really know how best to implement what I suggested, so
I''m
glad you have come up with this since it is much better than anything
I would have thought up =) The textile support is a good addition.

What is the general concensus on Engines relying on plugins? I had
gone through the login engine and fixed up the flash messages to
comply with the spec. However, if people (engine developers) are happy
to rely on the flash_helper then it makes sense for me to go through
it again and change the code to use Francois'' new plugin. James?

A patch (bonus points for added appropriate documentation!) for the
LoginEngine to either conform to the mooted guidelines or use
Francois'' plugin should be submitted to the Trac site (linked from
rails-engines.rubyforge.org), although I''m hesitant to add couplings
between the LoginEngine with other plugins at the moment, for two
reasons:

* There''s currently an issue with creating dependencies between
plugins (and therefore between plugins and Engines), which I''ve
outlined in Ticket #2723 on the Rails Trac site -
http://dev.rubyonrails.org/ticket/2723
* It also reduces the simplicity of Engines if requisites must be
satisfied for them to run properly. Then again, the Engines plugin
itself is a prerequisite for any Engine, so perhaps this issue is
already upon us.

The latter reason is just my personal feeling - I''m not the boss of
anyone who wants to write a plugin which uses the Engines plugin and
also depends on other plugins :) I''ve certainly wanted to do it
myself.... I suppose I''m just being cautious :)

- james

On 11/5/05, Luke Randall
<luke.randall-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
wrote:
> > > I like this.  Got a patch?
>
> I did have a few patches, but most of them have been superceded by
> Francois'' work =)
>
> > I don''t have a patch, I have a plugin instead.
>
> Hey Francois
>
> I haven''t had time to play with your code yet (other than look at
the
> code a bit), so I don''t have any ideas as to what''s
wrong. However, I
> will have a chance to look into it in the next couple of days, and
> hopefully will be able to help. However, I like what I''ve seen of
it.
> I didn''t really know how best to implement what I suggested, so
I''m
> glad you have come up with this since it is much better than anything
> I would have thought up =) The textile support is a good addition.
>
> What is the general concensus on Engines relying on plugins? I had
> gone through the login engine and fixed up the flash messages to
> comply with the spec. However, if people (engine developers) are happy
> to rely on the flash_helper then it makes sense for me to go through
> it again and change the code to use Francois'' new plugin. James?
> _______________________________________________
> Rails mailing list
> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> http://lists.rubyonrails.org/mailman/listinfo/rails
>

Hi,

On 5-Nov-05, at 8:02 AM, James Adam wrote:
>
> Finally, you can''t send :include methods to ApplicationController
from
> a plugin''s init.rb - the class has yet to be loaded. You can see
the
> warning if you run script/console, rather than script/server. So
> instead, you''ll have to require users to include your modules in
their
> own application.rb/application_helper.rb files..
By sending the :includes to ApplicationController and ApplicationHelper  
it would seem that you expect this plugin''s features to be available to
all controllers and views in a given rails application.

If that''s the case then I''d probably just send the :includes
to
ActionController::Base and ActionView::Base.

Of course, this is just my personal taste (for this particular plugin).

Regards,
Trevor

> hope that helps
>
> - james
>
> On 11/5/05, Francois Beausoleil
<francois.beausoleil-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>> Hi !
>>
>> 2005/11/5, Keegan Quinn
<keegan-g9krTqASs3z/gVISOhv/wg@public.gmane.org>:
>>> On Fri, Nov 04, 2005 at 03:12:15PM +0000, Luke Randall wrote:
>>>>   :notice for positive feedback (action successful, etc)
>>>>   :message for neutral feedback (reminders, etc)
>>>>   :warning for negative feedback (action unsuccessful, error  
>>>> encountered, etc)
>>>
>>> I like this.  Got a patch?
>>
>> I don''t have a patch, I have a plugin instead.  Unfortunately,
it
>> doesn''t work at the moment.  I can''t get tests to
run, and when I add
>> the plugin, WEBrick fails silently at startup, with no error messages
>> :(
>>
>> Code can be found here:   
>> http://opensvn.csie.org/flash_helper_plugin/trunk/
>>
>> If anybody would be good enough to give me a hand, I''d be very
>> grateful.  I thought I could release that yesterday afternoon, but I
>> was pressed for time.  I''m probably 80% of the way there.
>>
>> Project''s home page is at:
>> https://opensvn.csie.org/traccgi/flash_helper_plugin/trac.cgi/
>>
>> Blog article about the plugin:
>> http://rubyurl.com/pz0
>> http://blog.teksol.info/articles/2005/11/05/flash-helper-plugin- 
>> flash-standardization
>>
>> Thanks for any help you may provide.
>>
>> Bye !
>> --
>> François Beausoleil
>> http://blog.teksol.info/
>>
>> _______________________________________________
>> Rails mailing list
>> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
>> http://lists.rubyonrails.org/mailman/listinfo/rails
>>
>>
>>
> _______________________________________________
> Rails mailing list
> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> http://lists.rubyonrails.org/mailman/listinfo/rails
>
--
Trevor Squires
http://somethinglearned.com

Hello James !

2005/11/5, James Adam <james.adam@gmail.com>:
> I can't give you a patch right now, but inspecting the code,
there's a
> few things:
Geez, how could I be so stupid :)  Thanks for the info.

Bye !
François

_______________________________________________
Rails mailing list
Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
http://lists.rubyonrails.org/mailman/listinfo/rails

Hi !

2005/11/6, Trevor Squires <trevor@protocool.com>:
> If that's the case then I'd probably just send the :includes to
> ActionController::Base and ActionView::Base.
That's exactly what I did.  Look for the announcement on the list in a
few moments.

Bye !
François

_______________________________________________
Rails mailing list
Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
http://lists.rubyonrails.org/mailman/listinfo/rails