= Vars If

This extension combines two sets of tags which could, ultimately, each be made into
their own extensions.  Since this is just a proof-of-concept, I have kept them
together for simplicity.


== CONDITIONALS == (/lib/if_tags.rb) ==
The purpose of these tags is to consolidate conditional statements.  We already
have <r:if_url>, <r:if_parent>, and <r:if_content>. And just the other day John
authorized a new <r:if_dev>. Then there are the extension developers -- cranking
out their own <r:if_stuff> tags.

The benefits to this method are:

    * Provide consistency and simplify things for users (instead of having to 
      remember that the <r:if_parent> tag has no attributes, but the <r:if_url> 
      has a 'matches' attribute and <r:if_content> has 'part').  All existing 
      <r:if_xxx> tag behavior can be rolled into one -- with one common set of 
      rules.
      
    * Keep the tag namespace clean(prevent all those <r:if_xxx> tags cluttering
      the user's documentation up).
      
    * Make it (almost) trivial to add additional tests for core items without
      having to create things like <r:if_title> or <r:unless_published>.
      
    * Expand the range of conditions that can be evaluated. For instance, the 
      <r:content> tag of today merely tests for the existence of the specified 
      page part.  Instead, we can test whether:
         <r:if cond="content(my page part) is_blank"> or,
         <r:if cond="page(title) matches /someRegexp/">
      
    * Allow extension developers hook into the core of conditionals by exposing 
      their own values to test.  I have seen several extensions that have needed
      to create their own custom <r:if_xxx> tags.  In the spirit of keeping 
      things DRY and simplifying things for users (See bullet 1), this extension
      allows other extensions to add their elements to conditions. (NOT YET 
      IMPLEMENTED)


The result, three tags:
    <r:if cond="your conditional expression here">...</r:if>
    <r:unless cond="your conditional expression here">...</r:unless>
    <r:puts value_for="symbol expression" />


For more info on usage, see the 'available tags' documentation within the
Radiant page view.




== VARIABLES == (/lib/var_tags.rb) ==
Vars, is a simple set of tags to declare variables.  The variable scope is 
determined by the tag -- a single tag declares globally, and a container tag, 
only for the local scope of the container.

Of course this is all useless without some way to retrieve the variables.  Some
refactoring led to making the 'get' tag part of the conditionals piece (above).
This way the same code that gets variables for output, gets them for testing 
conditionals. And extension writers can make use of this common 'get' to render
their extension's values

Finally, I modified the <r:snippet /> tag to allow variables to be declared
there too.  Technically, this isn't necessary since the following two are equal:
  <r:store vars="my variables list"><r:snippet name="mySnip"/></r:store>
  <r:snippet name="mySnip" vars="my variables list">

So, my feelings are mixed on keeping this snippet mod.

But the benefit to all this is that snippets can behave more like rails helpers.
They become simple functions where values can be passed to another Radiant
element and then acted upon there.  For an example, see the end of the next
section.



== EXAMPLE USAGE ==
The 'if/unless' conditionals allow for the replacement/simplification of several
existing tags like:
   <r:if_url matches="MyRegexp"></r:if_url> becomes,
   <r:if cond="page[url] matches /MyRegexp/"></r:if>

   <r:unless_parent></r:unless_parent> becomes,
   <r:unless cond="page[parent]"></r:unless>

   <r:if_content part="My Page Part"></r:if_content> becomes,
   <r:if cond="page.part[My Page Part]"></r:if>

but that's not the main point.  This also adds new possibilities with:
   <r:if cond="page.part[My Page Part] is_blank">
   <r:unless cond="page.part[My Page Part] matches /myRegexp/">


The 'get' function replaces/simplifies other existing tags like:
   <r:slug /> becomes <r:puts value_for="page[slug]" />
   <r:title /> becomes <r:puts value_for="page[title]">

OK, so that didn't really simplify much (though it does clean up the number of
tags floating around and encourages users to organize their thoughts about title
and slug).  It does make it easy to get new items, though -- like publish date, 
or a render a custom value from an extension.


Speaking of a custom extension value, when combined with the 'puts' functionality,
the  Vars piece allows you to set and get variables.
   <r:store vars="myVar: 15" />
   <r:puts value_for="vars[myVar] />

When combined with the 'if/unless' functionality, you can now perform 
conditional branching based on those variables.  Here's a fancy example:

PAGE:
   <r:snippet name="link" vars="linkText: 'Some example link text'; 
   url: my/target/url; class: myClass" />

SNIPPET (named 'link'):
   <a href="<r:puts value_for="vars[url]" />"
     <r:if cond="vars[class]"> class="<r:puts value_for="vars[class]" />"</r:if>
   ><r:puts value_for="vars[linkText]" /></a>
 
RESULT:
   <a href="my/target/url" class="myClass">Some example link text</a>



== ISSUES ==
1.)  Compound Symbols - This is the area that needs the most help.  I wanted a 
     way to expose Radiant elements and, also, extension elements to the user 
     (via puts and if/unless).  The way the user refers to these elements is using
     a convention I call Compound Symbols. Currently there are three problems to
     be solved with them:
     
     a.)  I'm only sort of OK with the syntax.  Currently it is a simple notation:
              ObjectRouting[ItemToEval]
          
          The idea is that the ObjectRouting gives the tag enough info to figure
          out who gets to resolve the ItemToEval (i.e. is it a page element, or 
          something from an extension) and then it hands off the evaluation to 
          that piece.
             
             I'm toying with changing the notation to just page.title or
             children.count and leaving the [] for things that really need addl
             params (examples include:
                page.part[page part name] or 
                page.date[format: %l %p, %b %d, %Y, for: now]
             
          I'm still looking for ideas.  I don't mind having to dance around with
          the code so long as it works elegantly to the user and at least semi-
          elegantly to the extension developer.
          
     b.)  So, whatever the notation, I need a way to access Radiant Elements via
          these symbols.  Currently, it's semi-hard coded (I allow title, url, 
          slug, and breadcrumb).  I'm ok with that but it doesn't seem very
          extensible.  What if a user extends the page model and wants to access
          those new fields, or what if they just want to expose more than I do.
          Seems kinda klunky to have to go in an edit my tags directly.
          
     c.)  Here's the big one.  What if a user creates their own extension with 
          their own values that they want to expose.  How do they do that via
          their extension?  For example my <r:store> stuff should be in a
          separate extension and there should be no sign of how to evaluate
          vars[my variable] in the conditionals stuff.
          
          But how can I do that - allow extension developers to "hook" into the
          evaluation code? 


2.)  Testing - I have created several test tags to allow me to expose private
     routines used by my tags.  This is a bogus solution because they are visible
     in production.  I'd like to have those tags AND their subroutines available
     to my testing but I have NO idea how to pull that off.  Guess I could just
     stick to black box testing.


3.)  Code Improvements - not only do I believe that "more eyes" helps, but I don't
     really claim to be a coder.  There's got to be a better way to do some of
     this stuff.