Roadmap

[Brenton]

Sandbar started out as a place for me to put common code that I was
using in several web applications. This code was often not very well
thought out and a little ugly because of my lack of experience with
Clojure. Some of it still is.

I would like to move toward a 1.0 release of Sandbar and so would like
to define what that would look like. I write a lot of web applications
that I would call "tool" applications. They are used within businesses
to perform some task. There are several things that I find myself
needing in every one of these applications:

Authentication and authorization
Forms and form validation
Dynamic tables which can filter, sort and page data
Search capabilities

I would like for Sandbar to provide support for these capabilities
using idiomatic Clojure and in a way that leverages Clojure and Ring
to move a step ahead of existing methods in any other language or
framework. I don't want Sandbar to be a framework. It will provide a
set of libraries that work well together and where each piece can be
used on it's own.

I am currently not very fond of templating. Sandbar will provide no
support for templating and will generate html for forms and tables.
This is not a limitation and does not prevent you from using templates
for the rest of your application.

For version 1.0 I would like to have the first three items above
complete. Sandbar currently contains implementations of each of these
in various states of disorder. Additionally it contains support for
working with the session as a global map; which I think is very
helpful and foundational to building the other pieces. Complete means:
having a solid API, complete documentation with examples and 100% test
coverage. I may do the documentation as a series of blog posts which
will also end up in the project's wiki.

As of now, I am mostly happy with the API for sessions, validation,
authentication and authorization and the recent changes to forms.
sandbar.tables works but is a complete mess and will change a lot
before it is ready.

Future versions may include:

Search capabilities
Logging
Internationalization
...

To prepare for this, I have moved a lot of the none 1.0 code out of
Sandbar and into a project named bewwen. I have also changed the
structure of the remaining code into its 1.0 form.

If you would like to help out, here are some easy things that you can
do to get started:

Write some validators. The validation namespace provides a way to do
form validation but doesn't provide many built-in validators.

Write tests. If you run script/coverage you can see all of the
functions which are untested. At this point I would avoid doing this
for the sandbar.tables namespace as it will change drastically.

Take a hard look at sandbar.auth. It uses clojure.contrib.error-kit
for exception handling and I am not sure that it should. It also
supports a limited set of use cases.

If you happen to be a designer. It would be great to have some nice
form layouts and designs that people can build on. If you are
interested then please contact me.

Try it out, ask questions, fix problems that you find and give your
feedback on this list.

Of course, if you would like to work on anything else then go ahead.
All help is appreciated.

Thanks,
Brenton

[David Nolen]

On Dec 8, 3:50 pm, Brenton <bashw...@gmail.com> wrote:
> I am currently not very fond of templating. Sandbar will provide no
> support for templating and will generate html for forms and tables.
> This is not a limitation and does not prevent you from using templates
> for the rest of your application.

Personally I won't find Sandbar very useful if you go this route.
Hardcoding any kind of HTML generation into forms is death. Same with
tables. Providing default behavior is fine, but tying them into your
particular implementation is short-sighted.

I'll chime in my opinions about forms in general on the forms thread.

David

[Brenton]

David,

Thank you for challenging me on this. I like good feedback.

> Hardcoding any kind of HTML generation into forms is death. Same with
> tables.

I don't agree. The trick is to make sure that you don't take away any
design opportunities from your designers. One of the goals with
sandbar forms is to provide layouts similar to how you would design a
form for a desktop application. Currently there is only a grid layout
and the orientation of the field label, error message and field are
"hardcoded" (which I agree is bad). In the future I would like to give
the developer complete control over this and that may take the form of
an HTML snippet. All aspects of a form's layout will be grouped into a
style. One option to defform will allow you to set and change the
form's style. Styles may be shared. If you don't like a style then you
can create a new one. A style will only effect where things are
located, CSS will still determine how each elements looks.

I want to be able to program at a higher level and not always be
trapped at the level that HTML provides. For example, I want to have a
muti-checkbox form element which doesn't exist in HTML. To get this I
have to generate HTML or I would have to re-create it every time in a
template.

If I can program at a higher level of abstraction, arrange form
elements in any way that I like and set any attribute on any form
element so that designers can control how it looks, I don't see how
HTML generation is bad.

I know I am breaking a lot of rules here and may be totally wrong.

Brenton

[David Nolen]

On Thu, Dec 9, 2010 at 2:42 PM, Brenton <bash...@gmail.com> wrote:

David,

Thank you for challenging me on this. I like good feedback.

> Hardcoding any kind of HTML generation into forms is death. Same with
> tables.

I don't agree. The trick is to make sure that you don't take away any
design opportunities from your designers. One of the goals with
sandbar forms is to provide layouts similar to how you would design a
form for a desktop application.

You can still get there without chaining consumers to your particular layout engine. You just can't predict what users will want. Build defaults for newbs and provide a good design so that experts can easily customize. With most OO langs keeping thing open means *a lot* of implementation complexity. Not so with Clojure. Leverage that. You have defrecord, protocols, and for syntactic sugar, macros. You have the tools to Do The Right Thing without an resorting to an over engineered implementation. Django and Rails are particularly guilty of this. Java frameworks are much, much worse.

 

Currently there is only a grid layout
and the orientation of the field label, error message and field are
"hardcoded" (which I agree is bad). In the future I would like to give
the developer complete control over this and that may take the form of
an HTML snippet.

This is not the way to go. Provide a FormWidget protocol.

(defprotocol FormWidget

   validate-field [field]

   render-field [field])

(defrecord UsernameWidget []

   ...)

(defrecord EmailWidget []

   ...) 

(defrecord MyForm [req]

   sandbar.Form

   (css [this] "/path/to/some/styles.css")

   (fields [this]

       {:username {:type :string :widget (UsernameWidget.)}}

       {:email {:type :string :widget (EmailWidget.)}}))

 

I want to be able to program at a higher level and not always be
trapped at the level that HTML provides. For example, I want to have a
muti-checkbox form element which doesn't exist in HTML. To get this I
have to generate HTML or I would have to re-create it every time in a
template.

I want to program at higher level as well when customizing your nice framework. For example, I may want all the *behavior* of your multi-checkbox form processing thing, but none of the *display*. Don't make me abandon your whole thing because I would be forced to swallow both at the same time.

If you do force me to abandon it at a bare minimum it should be easy for me to *provide* something that is a multi-checkbox form processing thing as far as Sandbox is concerned. This can be done with well defined protocols.

 

If I can program at a higher level of abstraction, arrange form
elements in any way that I like and set any attribute on any form
element so that designers can control how it looks, I don't see how
HTML generation is bad.

Default HTML generation is fine. But you must have a design that requires you to eat your own dog food. Build an easily extensible system and code to this design. You don't have to solve all problems, just provide clear entry points of extension so people can solve their own specific problems in the context of your framework.

Otherwise it will not be an improvement on what's out there. And what's out there is *incredibly* mediocre as far as these things are concerned.

David 

[David Nolen]

On Thu, Dec 9, 2010 at 3:21 PM, David Nolen <dnolen...@gmail.com> wrote:

(defprotocol FormWidget

   validate-field [field]

   render-field [field])

(defrecord UsernameWidget []

   ...)

(defrecord EmailWidget []

   ...) 

(defrecord MyForm [req]

   sandbar.Form

   (css [this] "/path/to/some/styles.css")

   (fields [this]

       {:username {:type :string :widget (UsernameWidget.)}}

       {:email {:type :string :widget (EmailWidget.)}}))

With something like the above it would be trivial to write a newb-friendly form macro that expands into the right thing:

(def-form MyForm

   :username :username

   :email        :email))

... while underneath you have powerful extensible core. This is the kind of thing that Clojure excels at.

[Brenton]

David,

You are absolutely right. I thought you were telling me how I should
work, but instead you were telling me not to tell others how they
should work.

I will work on this and keep this list posted.

Thanks,
Brenton

[Nicolas Buduroi]

Unless I'm mistaken, to accomplish David's objectives to provide a way for users to handle the form rendering, we could provide a higher-level interface than what he proposed. Currently the entry point for html rendering is the template and form-layout-grid. Those functions are called from show-form which just process some of the form options, so I think the simplest way would be to add a protocol as a layer between them. We could add the following protocol:

(defprotocol form-renderer

   template [method action attrs]

   fields [layout name fields request form-data properties])

And modify show-form to use that. It would put the burden of rendering logic on the user tough. It would also need changes to some functions like actualize-html (not sure what it does) and we could get rid of template multimethod at the same time. I'm just beginning to understand how forms rendering work, so I may be totally wrong.

P.S.: After looking at the rendering code, I see a lot of multimethod using single dispatch. maybe they would be another part of the code to convert to protocols.

[David Nolen]

On Thu, Dec 9, 2010 at 4:32 PM, Brenton <bash...@gmail.com> wrote:

Thanks for listening. Clojure's web story really needs something like Sandbar. I look forward to seeing where it goes (and when I'm less busy, contributing!)

David

[Brenton]

Nicolas,

I am not afraid to make a lot of changes at this point. I think we
will want to have more fine grained protocols so that users will only
need to implement the parts that they have to and can rely on the
defaults for everything else.

I would like to end up with an interface that is close to what we have
now, but that is implemented along the lines that David suggests.

Right now, each kind of form field is represented by a map. Two
elements of this map contain hard-coded HTML: :html and :label. The
value of :html can be a function, as it is for muti fields, which
allows them to be dynamically generated for each request (that is what
actualize-html does).

I think we can still represent form fields as maps but without the
HTML. Internally, all form information would be represented as Clojure
data. The very last step before returning a response would be to
render the form as HTML. This will be done in a way that will allow
users to either stick with the defaults or provide their own
implementation.

I think that doing this will also clean up a lot of the other code as
well.

The main reason I was opposed to templates was that I didn't want to
have have to come up with "the way" to use them. By keeping it open,
each developer would be able to make that decision.

I think this will be huge improvement as it will allow developers to
create rapid working prototypes and then customize them later.

Brenton

On Dec 9, 1:53 pm, Nicolas Buduroi <nbudu...@gmail.com> wrote:
> Unless I'm mistaken, to accomplish David's objectives to provide a way for
> users to handle the form rendering, we could provide a higher-level
> interface than what he proposed. Currently the entry point for html
> rendering is the template and form-layout-grid. Those functions are called
> from show-form which just process some of the form options, so I think the
> simplest way would be to add a protocol as a layer between them. We could
> add the following protocol:
>
> (defprotocol form-renderer
>    template [method action attrs]
>    fields [layout name fields request form-data properties])
>
> And modify show-form to use that. It would put the burden of rendering logic
> on the user tough. It would also need changes to some functions like
> actualize-html (not sure what it does) and we could get rid of template
> multimethod at the same time. I'm just beginning to understand how forms
> rendering work, so I may be totally wrong.
>
> P.S.: After looking at the rendering code, I see a lot of multimethod using
> single dispatch. maybe they would be another part of the code to convert to
> protocols.
>

[Brenton]

Thanks for taking the time to make your point. This is the kind of
feedback I am always looking for. Until you have time to contribute,
we are happy to have you as an adviser.

On Dec 9, 1:56 pm, David Nolen <dnolen.li...@gmail.com> wrote: