First Draft Grails Reference Docs

[Corey-24]

Excellent work!

Sorry if I missed this in the thread, but will it be made available as a
pdf also? I would love to be able to print it up.


Cheers!


On Tuesday 13 November 2007 07:44:48 am Tom Nichols wrote:

> Looks great!
>
> If I can make a suggestion --
>
> If you're willing to add a little JavaScript, make the left panes more
> hierarchical so your top-level elements:
> Command Line
> Constraints
> Controllers
> ...etc
>
> expand when clicked on to show sub-items, which avoids the extra visual
> noise.
>
> Also, since the User Guide and Reference probably link to each other a
> lot, I would suggest a top and bottom left pane, for the User Guide
> navigation and reference guide navigation respectively.  You might be
> able to Combine the two navigation panes easily enough if you were
> willing to use JS to expand and collapse the tree.
>
> One more thing -- it appears that links in the ref point to the
> single.html user guide page -- I would suggest making those links
> point to the multi-page version of the user guide.
>
> Excellent work.
>
> -Tom
>
> On 11/12/07, Graeme Rocher <graeme@...> wrote:
> > Hi All,
> >
> > I've put up the first draft of the official Grails reference docs.
> > Could those of you interested please read through and email back in
> > this thread any mistakes or suggestions you find.
> >
> > http://grails.org/doc/RC1/
> >
> > Look forward to the feedback.
> >
> > Cheers
> >
> > --
> > Graeme Rocher
> > Grails Project Lead
> > G2One, Inc. Chief Technology Officer
> > http://www.g2one.com
> >
> > ---------------------------------------------------------------------
> > To unsubscribe from this list please visit:
> >
> >     http://xircles.codehaus.org/manage_email
>
> ---------------------------------------------------------------------
> To unsubscribe from this list please visit:
>
>     http://xircles.codehaus.org/manage_email

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

[felipenasc]

Great job guys.


In Logging section, an example on how to setup diferente outputs for different artefacts, would be good. I spent some time to figure this out, I have once answered in the mail list about this issue.

Lets say I want everything to log to a file, and I want MailService to log to another file. How to do this?

log4j {
    appender.fout='org.apache.log4j.RollingFileAppender'
    appender." fout.File"='/home/tomcat/logs/app.log'
    appender."fout.MaxFileSize"='900KB'
    appender."fout.MaxBackupIndex"='10'
    appender."fout.layout"='org.apache.log4j.PatternLayout '
    appender."fout.layout.ConversionPattern"='%d{DATE} %p %t %c - %m%n'

    appender.mailout='org.apache.log4j.RollingFileAppender'
    appender."mailout.File"='/home/tomcat/mail.log'
    appender."mailout.MaxFileSize"='900KB'
    appender."mailout.MaxBackupIndex"='10'
    appender."mailout.layout"='org.apache.log4j.PatternLayout'
    appender." mailout.layout.ConversionPattern"='%p %d{DATE} %c - %m%n'

    rootLogger="info,fout"
    logger {
       
        grails."app.service.MailService"="info, mailout"
        grails.app="info,fout"
        org {
            codehaus.groovy.grails.web.servlet="info,fout"  //  controllers
            codehaus.groovy.grails.web.pages="info,fout" //  GSP
            codehaus.groovy.grails.web.sitemesh="info,fout" //  layouts
            codehaus.groovy.grails."web.mapping.filter"="info,fout" // URL mapping
            codehaus.groovy.grails ."web.mapping"="info,fout" // URL mapping
            codehaus.groovy.grails.commons="info,fout" // core / classloading
            codehaus.groovy.grails.plugins="info,fout" // plugins
            codehaus.groovy.grails.orm.hibernate="info,fout" // hibernate integration
            springframework="off,fout"
            hibernate="off,fout"
        }
       
       
    }
    additivity."default" = false
    additivity {
        grails=false
        org {
            codehaus.groovy.grails=false
            springframework=false
            hibernate=false
        }
    }
}


Very nice work so far.

Felipe

2007/11/13, Corey <corey_s@...>:

Excellent work!

Sorry if I missed this in the thread, but will it be made available as a
pdf also? I would love to be able to print it up.


Cheers!


On Tuesday 13 November 2007 07:44:48 am Tom Nichols wrote:

> Looks great!
>
> If I can make a suggestion --
>
> If you're willing to add a little JavaScript, make the left panes more
> hierarchical so your top-level elements:
> Command Line
> Constraints
> Controllers
> ...etc
>
> expand when clicked on to show sub-items, which avoids the extra visual
> noise.
>
> Also, since the User Guide and Reference probably link to each other a
> lot, I would suggest a top and bottom left pane, for the User Guide
> navigation and reference guide navigation respectively.  You might be
> able to Combine the two navigation panes easily enough if you were
> willing to use JS to expand and collapse the tree.
>
> One more thing -- it appears that links in the ref point to the
> single.html user guide page -- I would suggest making those links
> point to the multi-page version of the user guide.
>
> Excellent work.
>
> -Tom
>
> On 11/12/07, Graeme Rocher <graeme@...> wrote:
> > Hi All,
> >
> > I've put up the first draft of the official Grails reference docs.
> > Could those of you interested please read through and email back in
> > this thread any mistakes or suggestions you find.
> >
> > http://grails.org/doc/RC1/
> >
> > Look forward to the feedback.
> >
> > Cheers
> >
> > --
> > Graeme Rocher
> > Grails Project Lead
> > G2One, Inc. Chief Technology Officer
> > http://www.g2one.com
> >
> > ---------------------------------------------------------------------
> > To unsubscribe from this list please visit:
> >
> >     http://xircles.codehaus.org/manage_email
>
> ---------------------------------------------------------------------
> To unsubscribe from this list please visit:
>
>     http://xircles.codehaus.org/manage_email

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

[jlo_gestalt]

Excellent documentation. Really needed for grails development.
One thing I see missing and expect is what closures are available for Domain classes such as documenting hasMany, belongsTo, optionals, etc.

Graeme Rocher-2 wrote:

Hi All,

I've put up the first draft of the official Grails reference docs.
Could those of you interested please read through and email back in
this thread any mistakes or suggestions you find.

http://grails.org/doc/RC1/

Look forward to the feedback.

Cheers

--
Graeme Rocher
Grails Project Lead
G2One, Inc. Chief Technology Officer
http://www.g2one.com

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

[hcunningham]

great docs!

a couple of small suggestions:

- it would be nice if the reference section could also be viewed on a
   single page
- perhaps add a section on where to get help? including tips on how to
   search the jira, nabble, and the codebase would be good.
- the thing I find hardest to get used to is the gant style of configuration
   and scripting, and I usually hit trouble whenever I have to translate some
   config from .properties or .xml to .groovy. probably just my ignorance, but
   if there are others like me (and given that a lot grails development uses
   tools that have their own docs referencing xml config) some more
   documentation of how to make this transition might help

great work, anyhow!

best,
--
Hamish
http://www.dcs.shef.ac.uk/~hamish/

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

[barrymac]

Thanks a million!

[Niels Bech Nielsen-3]

Oh, and while speaking of closures.
Perhaps include a note why controllers use closures for functionality as
opposed to methods. I believe there was a link once, but I cannot
remember the reason, anymore.

Cheers
/Niels

jlo_gestalt skrev:

> Excellent documentation. Really needed for grails development.
> One thing I see missing and expect is what closures are available for Domain
> classes such as documenting hasMany, belongsTo, optionals, etc.
>
>
> Graeme Rocher-2 wrote:
>  
>> Hi All,
>>
>> I've put up the first draft of the official Grails reference docs.
>> Could those of you interested please read through and email back in
>> this thread any mistakes or suggestions you find.
>>
>> http://grails.org/doc/RC1/
>>
>> Look forward to the feedback.
>>
>> Cheers
>>
>> --
>> Graeme Rocher
>> Grails Project Lead
>> G2One, Inc. Chief Technology Officer
>> http://www.g2one.com
>>
>> ---------------------------------------------------------------------
>> To unsubscribe from this list please visit:
>>
>>     http://xircles.codehaus.org/manage_email
>>
>>
>>
>>    
>
>  

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

[mchenryc]

Very good to see documentation being made a top priority!

In terms of 'flow' however, it feels... disorganized, considering page and navigation layout.

What you have are two documents: reference and guide. Shown first is the single-page "guide" and the TOC of section-per-page links of the "reference".

Have you considered putting the "reference" as an appendix of the "guide"? The "gotchas" and "FAQ" might make good Appendices too. This way, all could be found in the "single-page" no-frames view, and with frames, both reference and guide sections are displayed for navigation or quick lookup.

To offer both section-per-page views or all-one-page, you might have another pair of links next to the "Frames | No Frames" links offering "Section Per Page | All One Page" which if frames were shown, could show one of two TOC pages. I don't think I've ever seen that before though and am not sure if it would be useful or just feel "gimmicky". It just seemed that you were trying to keep both available by linking to section-per-page reference, while showing all-one-page for the guide.

An expanding/collapsing TOC might be useful for some. I think indenting hierarchically would make it a bit more readable, even if not collapsible.

I would not miss the top left "Reference Guide" and Grails icon if it were removed or simply made shorter. It takes up space where more TOC links could be shown.

The logos shown at the top are resized by img tags, leaving the browsers to shrink them, which do not always do well. Consider generating new .pngs of the intended size so the opening view does not have jagged graphics.

Critique's aside, great work putting all of this together!

...Chad

Tom Nichols wrote:

Looks great!

If I can make a suggestion --

If you're willing to add a little JavaScript, make the left panes more
hierarchical so your top-level elements:
Command Line
Constraints
Controllers
...etc

expand when clicked on to show sub-items, which avoids the extra visual noise.

Also, since the User Guide and Reference probably link to each other a
lot, I would suggest a top and bottom left pane, for the User Guide
navigation and reference guide navigation respectively.  You might be
able to Combine the two navigation panes easily enough if you were
willing to use JS to expand and collapse the tree.

One more thing -- it appears that links in the ref point to the
single.html user guide page -- I would suggest making those links
point to the multi-page version of the user guide.

Excellent work.

-Tom

On 11/12/07, Graeme Rocher <[e-mail]> wrote:
> Hi All,
>
> I've put up the first draft of the official Grails reference docs.
> Could those of you interested please read through and email back in
> this thread any mistakes or suggestions you find.
>
> http://grails.org/doc/RC1/
>
> Look forward to the feedback.
>
> Cheers
>
> --
> Graeme Rocher
> Grails Project Lead
> G2One, Inc. Chief Technology Officer
> http://www.g2one.com
>

[hcunningham]

mchenryc wrote:

> Have you considered putting the "reference" as an appendix of the "guide"?

+1

best
--
Hamish
http://www.dcs.shef.ac.uk/~hamish/

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

[mchenryc]

Neither the Data Binding section (6.1.6) nor bindData entry (in the reference) mention the caveats found in the wiki:

 - properties [id, version, metaClass, properties] are not bound
 - nested objects must explicitly use the 'excludes' parameter

Graeme Rocher-2 wrote:

I've put up the first draft of the official Grails reference docs.
Could those of you interested please read through and email back in
this thread any mistakes or suggestions you find.