Masterview devel - Jun 2006 - On default config values for dir locations (templates, directives)

Jeff - some thoughts on some of the current default config settings for key
locations that MV deals with.

[long, this is kind of a "thinking out loud" msg to elaborate some
alternatives]

Current MV config defaults:

- template source directory;
   - rails app: app/views/masterview
   - non-rails config: not sure if there''s a good default assumption
      [I put in ''./masterview/templates'' for now...]

- template output directory:
    - rails app: app/views
    - non-rails config: nil - client needs to say what they want

- directives load path:
    - initialized to load mv built-in directives:
        [ "#{MV_LIB_DIR}/masterview/directives'' ]

I''m now quite happily in the process of converting some content pages
for a
site that I''m moving onto rails into masterview templates.  This is a
relatively simple use case scenario: mainly wrapping some existing, fairly
static content in MV templates with mv:generate="*" specs to spit out
body
content into an .rhmtl for the <%= @content_for_layout %> slot in the
rails
site''s layout.  Some lightweight usage of mv/rails facilities (mv:attr
to
map some hrefs between ref in my template sandbox to how the urls look in
the real site).

Aside from still needing to settle on notation for mv:generate to provide
"magic values" ("*" or "#{template_rel_ref}" or a
pythonic-style
"__template_rel_ref_" or ...) or var subst for target path,
I''m quite happy
with how this works.  MV lets me create content pages as complete, valid
xhtml docs and supports declarative-style markup using the mv: attributes.
Very nice.

But I''ve gone through several variations of "where do I want to
keep my
template files" over the past week, partly just to play with the mechanisms
and test things.  I''ve used:

    app/views/masterview - the default config
    app/mv-templates - sibling structure which maps output into app/views

[and not tried but might consider: app/views/masterview/templates - fits in
with the MasterviewController structure]

I somewhat prefer the sibling dir alongside app/views over the current
default w/in the views dir - I like the symmetry of the parallel structure,
rather than pushing masterview templates into a somewhat odd,
not-used-in-quite-the-usual-fashion area within app/views.

But what I''ve actually settled on, which what I wanted in the first
place
and is the right structure in the long run:

    app/views - MV .html templates live right where they belong

The fact that generated .rhtml files appear alongside my .html templates is
simply an artifact of the current MV implementation.  Someday (*), the
.rhtml intermediate files won''t need to be there - a view ref that maps
onto
a MV template will do the same magic compile-on-the-fly and caching that
rails does now for its .rhtml files.

(*) maybe even soon, because I can begin to see a way to do this, at least
for this simple scenario where there aren''t inter-template
generate/import
dependencies

After first pass to settle the basic structure in my site, I now see an
opportunity to use a custom directive to simplify some annoying markup
redundancy in the original static impl.  I''m going to give that a try
and if
it works out it''ll be a good example to deliver with MV.  Specific case
is
that I have a number of pages which are just indexes to report files and
each report link has a little document icon indicating the form of the
report (an html view or a printable view or a PDF file).  So a little
icon_for_link directive would be a really handy gadget for this site.

All of which is the rationale leading into other thought on MV config
defaults: believe it would be useful for the default config for a rails
application to have a point of view on where it might find app-specific
directives to automatically load.  If app dir''s directory exist, append
to
config.directive_paths after the MV built-ins.

Not sure putting directives code in config/masterview/directives is the
right place.  Possible app/masterview/directives; possibly
app/lib/masterview/directives is better (but need to review rails loading
magic to see if that would work, don''t want rails itself to auto-load
things
in there)

Opinion?  I hypothesize that the empty directives dir in the masterview
trunk was your notion for providing a convention for this, but don''t
think
that''s the right place.

~ Deb

Yes, we are on pretty much the same page here.

I think that ultimately they should go in the app/views directory right
where they belong. The only reason I didn''t put them there originally
is
because I didn''t want users to get confused and such. However once we
can
eliminate the erb intermediate file then there is no confusion.

So app/views/controller/action.html will work out well.

I think I can add the direct to erb cache pretty soon, but if we wanted to
so something like app/masterview in the meantime we could since that has the
advantage of being the same subdirectory depth as app/views.

As for the directives, I too wasn''t sure where to put them. I put them
down
in the plugin directory because that seemed to be where to keep everything
together, but it isn''t necessarily the best place. And I was trying to
think
about ways where they could reuse the custom directives across apps, so it
is fine to allow them to put things into an app config directory but I want
to make sure to have a way for directives to be loaded in other directories
too. It turns out though that as long as they load masterview.rb first, then
they can simply require anything else in that they want and they will show
up as directives (if they inherited from directive_base)>

Your suggestion about using app/masterview/directives sounds like a good
one.

For keyword expansion, I started out with ruby inline substitution but since
that conflicted with the erb inline substitution using the same notation, I
fell back to plan B.

Plan B was to just do simple keyword expansion of simple text.
Here is the keywords I used in my first iteration of this.

For template path = app/views/masterview/foo/bar.html where
app/views/masterview is the template root
TEMPLATE_PATH = foo/bar.html
* = foo/bar
SHORTNAME = foo/bar (same as *, its the template_path minus the extension)
CONTROLLER = foo
ACTION = bar
EXTENSION = .html

I originally had additional ones but I think these would be the core.

We could even allow this to be configurable too, if for instance someone
wanted to use one of these. That would theoretically allow them to use
something like {template_path} if they wanted to for the keyword rather than
the all capital names.

But I like this simplicity since upper case is typically seen as a
replacement (or constant) and * is not typically used for a path, then
something like this works well. It also stands out when you ready it and is
cleaner than using {template_path} so they would do
layouts/CONTROLLER.rhtml    *.rhtml etc.

We can also assume that if they don''t specify an extension that it
would use
the default setup ''.rhtml'' that way they can just use * and be
done.

The way I wrote the keyword expander is that it would start with the longest
strings first so even if we ended up having keywords that used the same
subwords (not recommended) but it would still work.

Typically keyword expansion is only needed on generate, gen_* and import*
commands so by having it default to on only for those it doesn''t affect
most
other directives.

Jeff


On 6/7/06, Deb Lewis <djlewis at acm.org> wrote:
>
> Jeff - some thoughts on some of the current default config settings for
> key
> locations that MV deals with.
>
> [long, this is kind of a "thinking out loud" msg to elaborate
some
> alternatives]
>
> Current MV config defaults:
>
> - template source directory;
>    - rails app: app/views/masterview
>    - non-rails config: not sure if there''s a good default
assumption
>       [I put in ''./masterview/templates'' for now...]
>
> - template output directory:
>     - rails app: app/views
>     - non-rails config: nil - client needs to say what they want
>
> - directives load path:
>     - initialized to load mv built-in directives:
>         [ "#{MV_LIB_DIR}/masterview/directives'' ]
>
> I''m now quite happily in the process of converting some content
pages for
> a
> site that I''m moving onto rails into masterview templates.  This
is a
> relatively simple use case scenario: mainly wrapping some existing, fairly
> static content in MV templates with mv:generate="*" specs to spit
out body
> content into an .rhmtl for the <%= @content_for_layout %> slot in the
> rails
> site''s layout.  Some lightweight usage of mv/rails facilities
(mv:attr to
> map some hrefs between ref in my template sandbox to how the urls look in
> the real site).
>
> Aside from still needing to settle on notation for mv:generate to provide
> "magic values" ("*" or "#{template_rel_ref}"
or a pythonic-style
> "__template_rel_ref_" or ...) or var subst for target path,
I''m quite
> happy
> with how this works.  MV lets me create content pages as complete, valid
> xhtml docs and supports declarative-style markup using the mv: attributes.
> Very nice.
>
> But I''ve gone through several variations of "where do I want
to keep my
> template files" over the past week, partly just to play with the
> mechanisms
> and test things.  I''ve used:
>
>     app/views/masterview - the default config
>     app/mv-templates - sibling structure which maps output into app/views
>
> [and not tried but might consider: app/views/masterview/templates - fits
> in
> with the MasterviewController structure]
>
> I somewhat prefer the sibling dir alongside app/views over the current
> default w/in the views dir - I like the symmetry of the parallel
> structure,
> rather than pushing masterview templates into a somewhat odd,
> not-used-in-quite-the-usual-fashion area within app/views.
>
> But what I''ve actually settled on, which what I wanted in the
first place
> and is the right structure in the long run:
>
>     app/views - MV .html templates live right where they belong
>
> The fact that generated .rhtml files appear alongside my .html templates
> is
> simply an artifact of the current MV implementation.  Someday (*), the
> .rhtml intermediate files won''t need to be there - a view ref that
maps
> onto
> a MV template will do the same magic compile-on-the-fly and caching that
> rails does now for its .rhtml files.
>
> (*) maybe even soon, because I can begin to see a way to do this, at least
> for this simple scenario where there aren''t inter-template
generate/import
> dependencies
>
> After first pass to settle the basic structure in my site, I now see an
> opportunity to use a custom directive to simplify some annoying markup
> redundancy in the original static impl.  I''m going to give that a
try and
> if
> it works out it''ll be a good example to deliver with MV.  Specific
case is
> that I have a number of pages which are just indexes to report files and
> each report link has a little document icon indicating the form of the
> report (an html view or a printable view or a PDF file).  So a little
> icon_for_link directive would be a really handy gadget for this site.
>
> All of which is the rationale leading into other thought on MV config
> defaults: believe it would be useful for the default config for a rails
> application to have a point of view on where it might find app-specific
> directives to automatically load.  If app dir''s directory exist,
append to
> config.directive_paths after the MV built-ins.
>
> Not sure putting directives code in config/masterview/directives is the
> right place.  Possible app/masterview/directives; possibly
> app/lib/masterview/directives is better (but need to review rails loading
> magic to see if that would work, don''t want rails itself to
auto-load
> things
> in there)
>
> Opinion?  I hypothesize that the empty directives dir in the masterview
> trunk was your notion for providing a convention for this, but
don''t think
> that''s the right place.
>
> ~ Deb
>
>
> _______________________________________________
> Masterview-devel mailing list
> Masterview-devel at rubyforge.org
> http://rubyforge.org/mailman/listinfo/masterview-devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://rubyforge.org/pipermail/masterview-devel/attachments/20060607/1f12ae50/attachment-0001.htm

RE; default template src dir
 
>> if we wanted to so something like app/masterview in the meantime we
could
>> since that has the advantage of being the same subdirectory depth as
app/views.

I think I like do like that better than lurking down in
app/views/masterview, so I''ll go ahead and make that change to the
default
config.
 
>> think about ways where they could reuse the custom directives across
apps...
>> want to make sure to have a way for directives to be loaded in other
directories 
 
Yep, and in fact I''ll probably do exactly that.  Just append any
ol'' path
name you want to config.directive_paths in your settings.rb or env config.
 
But it would be nice to have a convenient "if you have the conventional
directives dir in your rails app we''ll load it automagically". 
I''ll put in
app/masterview/directives for now and test-drive it with something to make
sure it "feels good" in the overall organization of my app.
 
still contemplating your caps plan B fallback for import/gen directives -
it''s a bit grating, I do prefer "{template_path}" over
"TEMPLATE_PATH".
Making the notation itself configurable seems like a bad idea - the basic
notation should be simple and standard.
 
Maybe TEMPLATE_SHORT_PATH or TEMPLATE_BASE_PATH rather than SHORTNAME?
Trying to find the right name to fit with "standard" file system
terminology
and the existing File protocol in ruby.  File::basename get you just the
base file name w/out path or extension, so maybe "base path" captures
the
no-ext intent?
 
Don''t like CONTROLLER and ACTION - that may happen to be what those
elements
of a path represent, but it''s not necessarily so.  And there''s
potentially
diffs in url path fragments vs. controller impl structures.  So I think the
notions we allow to be expressed in the keywords we support should be
restricted just to the concepts of the template file living in some relative
scope of the file system structure - thus just name, extension,
full/relative paths.
 
>> Typically keyword expansion is only needed on generate, gen_* and
import*
commands 
>> so by having it default to on only for those it doesn''t affect
most other
directives.
 
Take a stronger point of view: these *are* the only directives that this
applies to.  Let''s don''t open it to other directives until
there''s a clear
need and an understanding of what might be appropriate.  [don''t invent
overly general mechanism until we need it - YAGNI]
 
~ Deb
 
YAGNI:
http://xp.c2.com/YouArentGonnaNeedIt.html
 
 
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://rubyforge.org/pipermail/masterview-devel/attachments/20060607/69013d71/attachment-0001.htm

On 6/7/06, Deb Lewis <djlewis at acm.org> wrote:
>
>  RE; default template src dir
>
> >> if we wanted to so something like app/masterview in the meantime
we
> could
> >> since that has the advantage of being the same subdirectory depth
as
> app/views.
> I think I like do like that better than lurking down in
> app/views/masterview, so I''ll go ahead and make that change to the
default
> config.
>
ok. We just need to make sure the generator and watcher are putting things
in the right place too. Might search for ''app/views'' across
the tree to see
if it was hard coded anywhere else. Shame on me if I didn''t use a
constant
everywhere. Of course that will all be centralized soon when I get the
centralized IO stuff in.

>> think about ways where they could reuse the custom directives across
> apps...
> >> want to make sure to have a way for directives to be loaded in
other
> directories
>
> Yep, and in fact I''ll probably do exactly that.  Just append any
ol'' path
> name you want to config.directive_paths in your settings.rb or env config.
>
> But it would be nice to have a convenient "if you have the
conventional
> directives dir in your rails app we''ll load it
automagically".  I''ll put in
> app/masterview/directives for now and test-drive it with something to make
> sure it "feels good" in the overall organization of my app.
>
> still contemplating your caps plan B fallback for import/gen directives -
> it''s a bit grating, I do prefer "{template_path}" over
"TEMPLATE_PATH".
> Making the notation itself configurable seems like a bad idea - the basic
> notation should be simple and standard.
>
I see your point. If you like {template_path} better then many other people
will too, so I am ok with that. I will have to test but I don''t think
it
will be any problem to use the {} syntax around the keywords.


Maybe TEMPLATE_SHORT_PATH or TEMPLATE_BASE_PATH rather than
SHORTNAME?
> Trying to find the right name to fit with "standard" file system
terminology
> and the existing File protocol in ruby.  File::basename get you just the
> base file name w/out path or extension, so maybe "base path"
captures the
> no-ext intent?
>
I had a hard time figuring out what to call that. I basically want the
relative pathname to the root (app/masterview) without extension. I
couldn''t
think of a good name for it. Looking at the ruby util Pathname it has a
function that is close ''relative_path_from''. So
{template_path_no_ext} or
one of the other ones you mentiond.

I took your advice on the path stuff by not worrying about native file paths
and only working with forward slash paths. By doing this Pathname does much
of what I needed and the rest was easily added in. So I use extended
Pathname for path operations and have the consolidated io to handle the
details about where to read and write the files from (file system with this
base path, db, hash, ...)

I think it is going to turn out nice.


Don''t like CONTROLLER and ACTION - that may happen to be what those
elements
> of a path represent, but it''s not necessarily so.  And
there''s potentially
> diffs in url path fragments vs. controller impl structures.  So I think the
> notions we allow to be expressed in the keywords we support should be
> restricted just to the concepts of the template file living in some
relative
> scope of the file system structure - thus just name, extension,
> full/relative paths.
>

Yeah I didn''t like that much either, however it is what the standard
rails
view layout looks like so I was trying to talk in terms that users would
understand. You are right in that obviously people don''t have to use
that
convention and can have more levels or other path arrangements.

So maybe something like

{template_full_path}
{template_path}
{template_path_no_ext} or *
{parent}
{filename}
{basename}
{extension}

>> Typically keyword expansion is only needed on generate, gen_* and
import*
> commands
> >> so by having it default to on only for those it doesn''t
affect most
> other directives.
>
> Take a stronger point of view: these *are* the only directives that this
> applies to.  Let''s don''t open it to other directives
until there''s a clear
> need and an understanding of what might be appropriate.  [don''t
invent
> overly general mechanism until we need it - YAGNI]
>

You are probably right. Simpler is better.

Thanks for the continued refinement and input! It will save much confusion
down the road.
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://rubyforge.org/pipermail/masterview-devel/attachments/20060607/46b4521f/attachment-0001.htm

Jeff - ok, I like this last round: all-caps is too much like SHOUTING_AT_ME,
simple bracket w/out the # is recognizably something a bit different that
usual by still close enough to ruby string subst. notation to be
comfortable, I think.  Latter also argues for following ruby var naming
convection (snake_case)
 
So I like:
 
{template_full_path}
{template_path}
{template_path_no_ext} or *

where {template_path} is rel path within template src dir.  
 
And at this point I''d drop "*" completely.
mv:generate="{template_path}.xxx" generates .xxx extension,
mv:generate="{template_path}" with no extension picks up default
output file
extension (.rhtml; could be made a config setting if necessary)
 
That last _no_ext guy is still awk.  What if we just take the point of view
that neither {template_path} or {template_full_path} include file ext and be
done with it.  Support {extension} to allow reference the template''s
extension if needed (tho I don''t know how useful that is)
 
Rather than {parent}, maybe {template_dir_path}, which is ''''
for template
file in the root templates src dir and ''foo/bar'' for nested
guys.
 
Not sure we need the following, maybe defer and just activate if we get
request?

{filename}
{basename}

I don''t think we need to bring controller/action into this -
it''s a notion
from a diff space (dispatch routing, and even there there''s issue
between
url routing paths and controller impl hieriarchies).  We just need to deal
with file paths here, I think.
 
So... I like this.  It''s simple and it''s pretty clear to a
reader, and it
handles the cases I''ve come up with so far.
 
??maybe we need escape convention someday to allow generating a file name
containing squigglies, but I wouldn''t worry about it until the problem
arises.
 
~ Deb
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://rubyforge.org/pipermail/masterview-devel/attachments/20060607/ab732fb7/attachment.htm

Alright, I think we are getting some where :-)

Taking into account your email, how about this?

{template_full_path}
{template_path} (picks up default extension)
{extension}
{template_dir_path}
{template_basename} (I need this one)

Jeff
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://rubyforge.org/pipermail/masterview-devel/attachments/20060608/70b26a9b/attachment.htm

Yes, I think that''s a good set.  Go with it!
 
Just to clarify: template_path and template_full_path are the
dir/file-base-name path components, but don''t include extension, right?
Then it''s consistent, and if needed ref to template''s own
extension is
hardcoded or used {extension}.
 
So test understanding - mv:generate target mapping examples in template
"foo/bar/testpage.html":
 
    mv:generate="{template_path}" 
        -> output file "foo/bar/testpage.rhtml"
    mv:generate="{template_path}.xxx 
        -> output file "foo/bar/testpage.xxx"
    mv:generate="somewhere/different/{template_basename}" 
       -> output file "somewhere/different/testpage.rhtml"
 
mv:generate="{template_dir_path}/{template_basename}-subsectionX.{extension}
" 
        -> output file "foo/bar/testpage-subsection.html"
 
~ Deb

  _____  

From: Jeff Barczewski [mailto:jeff.barczewski at gmail.com] 
Sent: Thursday, June 08, 2006 3:07 AM
To: djlewis at acm.org; masterview-devel at rubyforge.org
Subject: Re: [Masterview-devel] On default config values for
dirlocations(templates, directives)


Alright, I think we are getting some where :-)

Taking into account your email, how about this?

{template_full_path}
{template_path} (picks up default extension)
{extension}
{template_dir_path}
{template_basename} (I need this one) 

Jeff


-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://rubyforge.org/pipermail/masterview-devel/attachments/20060608/696a6473/attachment.htm

Yes, and similar to your example I couldn''t see a need for the template
full
path (in fact I don''t necessarily have access to it, since you might be
rendering to a hash or db), so I took out the template_full_path one.

All the others work as you indicated.

On 6/8/06, Deb Lewis <djlewis at acm.org> wrote:
>
>  Yes, I think that''s a good set.  Go with it!
>
> Just to clarify: template_path and template_full_path are the
> dir/file-base-name path components, but don''t include extension,
right?
> Then it''s consistent, and if needed ref to template''s own
extension is
> hardcoded or used {extension}.
>
> So test understanding - mv:generate target mapping examples in
> template "foo/bar/testpage.html":
>
>     mv:generate="{template_path}"
>         -> output file "foo/bar/testpage.rhtml"
>     mv:generate="{template_path}.xxx
>         -> output file "foo/bar/testpage.xxx"
>     mv:generate="somewhere/different/{template_basename}"
>        -> output file "somewhere/different/testpage.rhtml"
>
>
mv:generate="{template_dir_path}/{template_basename}-subsectionX.{extension}"
>
>         -> output file "foo/bar/testpage-subsection.html"
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://rubyforge.org/pipermail/masterview-devel/attachments/20060608/56f00971/attachment-0001.htm