kwartz 3.1.2 → 3.2.0

data/doc/users-guide.html

@@ -13,9 +13,11 @@
    <div class="mainbody">
 
     <div align="left"><h1>Kwartz-Ruby Users' Guide</h1></div>
-<p>$Release: 3.1.2 $<br>
-$Date: 2006-09-30 05:02:08 +0900 (Sat, 30 Sep 2006) $
-</p>
+    <div align="left">
+      release:     $Release: 3.2.0 $<br>
+      last update: $Date$<br>
+    </div>
+
 <a name="preface"></a>
 <h2 class="section1">Preface</h2>
 <p>This is the users' guide of Kwartz-ruby.
@@ -44,7 +46,7 @@ Kwartz-ruby is an implementation of Kwartz in Ruby.
     </li>
     <li><a href="#features">Features Overview</a>
     </li>
-    <li><a href="#example1">Simple Example</a>
+    <li><a href="#example1">Quick Example</a>
     </li>
     <li><a href="#example2">Complex Example</a>
     </li>
@@ -54,12 +56,18 @@ Kwartz-ruby is an implementation of Kwartz in Ruby.
   </li>
   <li><a href="#detail">Features Detail</a>
   <ul>
+    <li><a href="#selector">Selector</a>
+    </li>
     <li><a href="#ruleset">RuleSet and Properties</a>
     </li>
     <li><a href="#directives">Directives</a>
     </li>
     <li><a href="#embed_expr">Embed Expression in Presentation Data</a>
     </li>
+    <li><a href="#lang-independent-expr">Language-Independent Expression</a>
+    </li>
+    <li><a href="#attr-variable">Attribute Variable</a>
+    </li>
     <li><a href="#escape">Escape</a>
     </li>
     <li><a href="#langs">Multi-language</a>
@@ -141,13 +149,10 @@ If you are familiar with CSS, you'll be also familiar with Kwartz.
 </li>
 </ul>
 <div style="text-align: center">
-<span>Figure1. Relation of HTML, CSS, JavaScript, and Kwartz.</span><br />
+<span>Figure1. Components in Presentation Layer.</span><br />
 <img src="img/fig04.png" alt="relation of HTML, CSS, JavaScript, and Kwartz" />
 </div>
-<p>Kwartz-ruby is an implemenation of Kwartz in Ruby.
-</p>
-<p>In the following, the word 'Kwartz' means the specification of the template system
-and the word 'Kwartz-ruby' means the implementation of it in Ruby language.
+<p>If you are interested in concept of Kwartz, see <a href="">this presentation</a>.
 </p>
 <div class="footnote">
  <dl compact>
@@ -229,58 +234,31 @@ Auto-escape and Partial-escape</dt>
 
 
 <a name="example1"></a>
-<h3 class="section2">Simple Example</h3>
-<p>In Kwartz, a template is defined as both presentation data and presentation logic.
-They may be described in separate files.
-</p>
-<p>This is an example of a presentation data file.
-</p>
-<ul type="disc">
-<li>'<strong><code>id="list1"</code></strong>' means "I'll operate this element in presentation logic" (called 'marking' in Kwartz).
-</li>
-<li>'<strong><code>id="mark:item1"</code></strong>' is also an marking.
-   Difference between <code>id="mark:item1"</code> and <code>id="item1"</code> is that id attribute in the former format is removed automatically and the latter format is leaved.
-</li>
-</ul>
-<p>Presentation data file(example1.html):
+<h3 class="section2">Quick Example</h3>
+<p>Here is an example of presentation data file (= HTML template).
 </p>
-<a name="example1.html"></a>
+<div class="program_caption">
+example1.html</div>
 <pre class="program">&lt;table&gt;
-  &lt;tr <strong>id="list1"</strong>&gt;
+  &lt;tr <strong>id="mark:list1"</strong>&gt;
     &lt;td <strong>id="mark:item1"</strong>&gt;foo&lt;/td&gt;
   &lt;/tr&gt;
 &lt;/table&gt;
 </pre>
-<p>And the following is an example of presentation logic.
-In presentation logic, you can operate on elements which are marked in presentation data.
+<p>Points:
 </p>
 <ul type="disc">
-<li>'<strong><code>#list1 { ... }</code></strong>' represents an element marked with name 'list1' (= '&lt;tr&gt;...&lt;/tr&gt;')
-    <ul type="circle">
-    <li>'<strong><code>logic: { ... }</code></strong>' represents presentation logic of the element.
-    </li>
-    <li>'<strong><code>_stag</code></strong>' represents a start tag (= '&lt;tr&gt;').
-    </li>
-    <li>'<strong><code>_cont</code></strong>' represents content(= '&lt;td id="mark:item1"&gt;foo&lt;/td&gt;').
-    </li>
-    <li>'<strong><code>_etag</code></strong>' represents an end tag(= '&lt;/tr&gt;').
-    </li>
-    <li>'<strong><code>for <em>var</em> in <em>list</em> ...</code></strong>' is a Ruby code to loop.
-       In this case, the element(= start-tag + content + end-tag) is looped.
-    </li>
-    </ul>
+<li>Mark elements by <code>id="mark:xxx"</code> or <code>id="xxx"</code>. The former will be remove at compile stage but the latter will be remained.
 </li>
-<li>'<strong><code>#item1 { ... }</code></strong>' represents an element marked with name 'item1' (= '&lt;td&gt;...&lt;/td&gt;').
-    <ul type="circle">
-    <li>'<strong><code>value: <em>expression</em>;</code></strong>' represents that the content of the element is replaced by value of <code><em>expression</em></code>, which is value of a variable <code>member</code> in this case.
-    </li>
-    </ul>
+<li>No presentation logics in HTML file.
 </li>
 </ul>
+<p>Here is an example of presentation logic file.
+</p>
 <a name="example1.plogic"></a>
 <div class="program_caption">
-Presentation logic file(example1.plogic):</div>
-<pre class="program">/* The element which is marked by 'id="list1"' */
+example1.plogic</div>
+<pre class="program">/* The element which is marked by 'id="mark:list1"' */
 <strong>#list1</strong> {
   logic: {
     for member in @members
@@ -297,28 +275,41 @@ Presentation logic file(example1.plogic):</div>
   value: member;
 }
 </pre>
-<p>(Don't forget the semicolon at the end of line!)
+<p>Points:
 </p>
-<p>Kwartz generates eRuby script from the above files. This action is called 'compiling'.
+<ul type="disc">
+<li>Presentation logic is separated from HTML file.
+</li>
+<li>Format is very similar to CSS with which you are familiar.
+</li>
+<li>Don't forget the semicolon at the end of line!
+</li>
+</ul>
+<p>You must compile presentation data and logic files.
 </p>
 <div class="terminal_caption">
-how to compile</div>
-<pre class="terminal">$ kwartz -p example1.plogic example1.html &gt; example1.rhtml
+Compile</div>
+<pre class="terminal">$ kwartz -l ruby -p example1.plogic example1.html &gt; example1.rhtml
 </pre>
-<p>The following is the compiled output script.
-Notice that <code>id="mark:item1"</code> is removed automatically while <code>id="list1"</code> is leaved.
-</p>
 <a name="example1.expected"></a>
 <div class="program_caption">
-generated output script</div>
+Generated script (example1.rhtml)</div>
 <pre class="program">&lt;table&gt;
-&lt;%     for member in @members %&gt;
-  &lt;tr id="list1"&gt;
-    &lt;td&gt;&lt;%= member %&gt;&lt;/td&gt;
+<strong>&lt;%     for member in @members %&gt;</strong>
+  &lt;tr&gt;
+    &lt;td&gt;<strong>&lt;%= member %&gt;</strong>&lt;/td&gt;
   &lt;/tr&gt;
-&lt;%     end %&gt;
+<strong>&lt;%     end %&gt;</strong>
 &lt;/table&gt;
 </pre>
+<p>Points:
+</p>
+<ul type="disc">
+<li>Kwartz compile presentation data and logic files into eRuby, PHP, JSP, Velocity, ....
+</li>
+<li>This is why Kwartz is so fast and can support multiple programming languages.
+</li>
+</ul>
 <br>
 
 
@@ -491,7 +482,7 @@ See <a href="p-pattern.html">Presentation Pattern Catalog</a> for details.
 </li>
 </ul>
 <ul type="disc">
-<li>Delete elemnt. This is useful for delete dummy data.
+<li>Delete element. This is useful for delete dummy data.
 <pre class="program">#list {
   logic: {
   }
@@ -551,6 +542,33 @@ This way, you don't need to change presentation logic files even if the tag/attr
 
 <a name="detail"></a>
 <h2 class="section1">Features Detail</h2>
+<a name="selector"></a>
+<h3 class="section2">Selector</h3>
+<p>(Experimental) Kwartz now supports class selector, tag selector, and multi selector.
+</p>
+<pre class="program">/* tag selector */
+<strong>h1</strong> {
+  Value: title;
+}
+/* class selector */
+<strong>.list</strong> {
+  attrs: 'bgcolor' color;
+}
+/* multi selector */
+#foo<strong>,</strong> #bar<strong>,</strong> .baz {
+  value: item;
+}
+</pre>
+<p>Compound selector is NOT supported.
+</p>
+<pre class="program">/* compound selector is not supported */
+<strong>#foo .baz</strong> {   // PARSE ERROR
+  value: item;
+}
+</pre>
+<br>
+
+
 <a name="ruleset"></a>
 <h3 class="section2">RuleSet and Properties</h3>
 <p>Format of presentation logic in Kwartz is similar to CSS (Cascading Style Sheet).
@@ -584,14 +602,14 @@ etag: <em>expr</em>; </b></dt>
 <dt class="dt3"><b>
 elem: <em>expr</em>; </b></dt>
 <dd class="dd3">
-	Replace elemnt by expression value.
+	Replace element by expression value.
 </dd>
 </dl>
 <dl class="dl3">
 <dt class="dt3"><b>
 cont: <em>expr</em>; </b></dt>
 <dd class="dd3">
-	Replace content of element by expressin value.
+	Replace content of element by expression value.
 </dd>
 </dl>
 <dl class="dl3">
@@ -645,6 +663,20 @@ logic: { ... } </b></dt>
 	Logic of the element.
 </dd>
 </dl>
+<dl class="dl3">
+<dt class="dt3"><b>
+before: { ... } </b></dt>
+<dd class="dd3">
+	Logics executed before 'logic:' part.
+</dd>
+</dl>
+<dl class="dl3">
+<dt class="dt3"><b>
+after: { ... } </b></dt>
+<dd class="dd3">
+	Logics executed after 'logic:' part.
+</dd>
+</dl>
 <p>'stag:' and 'elem:' are useful especially for Ruby on Rails.
 The following is an examle to use Kwartz in Ruby on Rails.
 </p>
@@ -814,7 +846,7 @@ presentation data (embed1_ruby.html)</div>
 <a name="embed1_ruby.expected"></a>
 <div class="terminal_caption">
 compile</div>
-<pre class="terminal">$ kwartz -l eruby embed1_ruby.html
+<pre class="terminal">$ kwartz -l ruby embed1_ruby.html
 _buf = ""; _buf &lt;&lt; "&lt;p class=\"<strong>#{klass}</strong>\"&gt;Hello <strong>#{ERB::Util.h user}</strong>&lt;/p&gt;
 &lt;p class=\""; _buf &lt;&lt; <strong>(klass).to_s</strong>; _buf &lt;&lt; "\"&gt;Hello "; _buf &lt;&lt; <strong>ERB::Util.h(user)</strong>; _buf &lt;&lt; "&lt;/p&gt;\n";
 ; _buf
@@ -835,6 +867,121 @@ compile</div>
 <br>
 
 
+<a name="lang-independent-expr"></a>
+<h3 class="section2">Language-Independent Expression</h3>
+<p>Basically, embedded expression should be target language. For example if you are Rails developer then you should embed Ruby expression into html file, or if you are PHP programmer you must embed PHP expression. This will prevent you to share html template files (or reuse) between different projects (such as Rails project and PHP project).
+</p>
+<p>Now Kwartz supports language-independent expression. If expression matches the following pattern then it is recognized as language-independent expression, else as language-depend expression.
+</p>
+<ul type="disc">
+<li><code>variable</code>
+</li>
+<li><code>object.property</code>
+</li>
+<li><code>hash['key']</code>, <code>hash["key"]</code>, <code>hash[:key]</code>
+</li>
+<li><code>array[123]</code>, <code>array[index]</code>
+</li>
+</ul>
+<p>Language-independet expression is converted into target language automatically. For example, <code>user.name</code> will be converted into <code>$user-&gt;name</code> in PHP.
+</p>
+<div class="program_caption">
+Example (expr.html)</div>
+<pre class="program">&lt;p id="value:user"&gt;foo&lt;/p&gt;
+&lt;p id="value:user.name"&gt;foo&lt;/p&gt;
+&lt;p id="value:user['name']"&gt;foo&lt;/p&gt;
+&lt;p id="value:user[:name]"&gt;foo&lt;/p&gt;
+&lt;p id="value:user[0]"&gt;foo&lt;/p&gt;
+&lt;p id="value:user[i]"&gt;foo&lt;/p&gt;
+&lt;div&gt;
+  @!{user}@
+  @!{user.name}@
+  @!{user['name']}@
+  @!{user[:name]}@
+  @!{user[0]}@
+  @!{user[i]}@
+  @!{$user-&gt;name}@
+&lt;/div&gt;
+</pre>
+<div class="terminal_caption">
+Compile:</div>
+<pre class="terminal">$ kwarz -l eruby expr.html
+&lt;p&gt;&lt;%= <strong>user</strong> %&gt;&lt;/p&gt;
+&lt;p&gt;&lt;%= <strong>user.name</strong> %&gt;&lt;/p&gt;
+&lt;p&gt;&lt;%= <strong>user['name']</strong> %&gt;&lt;/p&gt;
+&lt;p&gt;&lt;%= <strong>user[:name]</strong> %&gt;&lt;/p&gt;
+&lt;p&gt;&lt;%= <strong>user[0]</strong> %&gt;&lt;/p&gt;
+&lt;p&gt;&lt;%= <strong>user[i]</strong> %&gt;&lt;/p&gt;
+&lt;div&gt;
+  &lt;%= <strong>user</strong> %&gt;
+  &lt;%= <strong>user.name</strong> %&gt;
+  &lt;%= <strong>user['name']</strong> %&gt;
+  &lt;%= <strong>user[:name]</strong> %&gt;
+  &lt;%= <strong>user[0]</strong> %&gt;
+  &lt;%= <strong>user[i]</strong> %&gt;
+  &lt;%= <strong>$user-&gt;name</strong> %&gt;
+&lt;/div&gt;
+$ kwartz -l php expr.html
+&lt;p&gt;&lt;?php echo <strong>$user</strong>; ?&gt;&lt;/p&gt;
+&lt;p&gt;&lt;?php echo <strong>$user-&gt;name</strong>; ?&gt;&lt;/p&gt;
+&lt;p&gt;&lt;?php echo <strong>$user['name']</strong>; ?&gt;&lt;/p&gt;
+&lt;p&gt;&lt;?php echo <strong>$user['name']</strong>; ?&gt;&lt;/p&gt;
+&lt;p&gt;&lt;?php echo <strong>$user[0]</strong>; ?&gt;&lt;/p&gt;
+&lt;p&gt;&lt;?php echo <strong>$user[$i]</strong>; ?&gt;&lt;/p&gt;
+&lt;div&gt;
+  &lt;?php echo <strong>$user</strong>; ?&gt;
+  &lt;?php echo <strong>$user-&gt;name</strong>; ?&gt;
+  &lt;?php echo <strong>$user['name']</strong>; ?&gt;
+  &lt;?php echo <strong>$user['name']</strong>; ?&gt;
+  &lt;?php echo <strong>$user[0]</strong>; ?&gt;
+  &lt;?php echo <strong>$user[$i]</strong>; ?&gt;
+  &lt;?php echo <strong>$user-&gt;name</strong>; ?&gt;
+&lt;/div&gt;
+</pre>
+<p> This feature is limited for basic expression but will help you to share or reuse html templates between projects.
+</p>
+<br>
+
+
+<a name="attr-variable"></a>
+<h3 class="section2">Attribute Variable</h3>
+<p>Attribute variable represents attribute value of element.
+</p>
+<div class="program_caption">
+presentation data (form.html)</div>
+<pre class="program">&lt;form <strong>action="create"</strong>&gt;
+ Username: &lt;input type="text" id="comment_username" <strong>size="20"</strong>&gt;&lt;br&gt;
+ Comment: &lt;textarea id="comment_body" <strong>cols="40"</strong> <strong>rows="3"</strong>&gt;&lt;/textarea&gt;&lt;br&gt;
+ &lt;input type="submit" id="mark:comment_submit" <strong>value="Send comment"</strong>&gt;
+&lt;/form&gt;
+</pre>
+<div class="program_caption">
+form.plogic</div>
+<pre class="program">form {
+  stag:  start_form_tag :action=&gt;'<strong>$(action)</strong>';
+}
+#comment_username {
+  elem:  text_field 'comment', 'username', :size=&gt;<strong>$(size)</strong>;
+}
+#comment_body {
+  elem:  text_area 'comment', 'body', :rows=&gt;<strong>$(rows)</strong>, :cols=&gt;<strong>$(cols)</strong>;
+}
+#comment_submit {
+  elem:  submit_tag '<strong>$(value)</strong>';
+}
+</pre>
+<div class="terminal_caption">
+compile</div>
+<pre class="terminal">$ kwartz -p form.plogic form.html
+&lt;%= start_form_tag :action=&gt;'<strong>create</strong>' %&gt;
+ Username: &lt;%= text_field 'comment', 'username', :size=&gt;<strong>20</strong> %&gt;&lt;br&gt;
+ Comment: &lt;%= text_area 'comment', 'body', :rows=&gt;<strong>3</strong>, :cols=&gt;<strong>40</strong> %&gt;&lt;br&gt;
+ &lt;%= submit_tag '<strong>Send comment</strong>' %&gt;
+&lt;/form&gt;
+</pre>
+<br>
+
+
 <a name="escape"></a>
 <h3 class="section2">Escape</h3>
 <p>Kwartz supports Automatic-escape and Partial-escape/unescape.
@@ -1490,7 +1637,7 @@ print statement because they can escape or unescape exression value.
 <a name="begin"></a>
 <h3 class="section2">Add Code at Beginning/End of Document</h3>
 <p>'#DOCUMENT' is a special selector which represents the document.
-In '#DOCUMENT', properties 'begin:' and 'end:' are available to add codes at beginning/end of document.
+You can use 'before:' and 'after:' to add codes at beginning/end of document<sup>(<a href="#fnref:6" name="fnlink:6">*6</a>)</sup>.
 </p>
 <a name="document-test.html"></a>
 <div class="program_caption">
@@ -1503,11 +1650,11 @@ document-test.html</div>
 <div class="program_caption">
 document-test.plogic</div>
 <pre class="program"><strong>#DOCUMENT</strong> {
-  <strong>begin:</strong> {
+  <strong>before:</strong> {
     title = cgi['title']
     user  = cgi['user']
   }
-  <strong>end:</strong> {
+  <strong>after:</strong> {
     print "&lt;!--end--&gt;\n"
   }
 }
@@ -1523,6 +1670,12 @@ compile</div>
 &lt;/html&gt;
 <strong>&lt;%= "&lt;!--end--&gt;\n" %&gt;</strong>
 </pre>
+<div class="footnote">
+ <dl compact>
+  <dt>(<a name="fnref:6" href="#fnlink:6">*6</a>)</dt>
+  <dd>'begin:' and 'end:' are also available but obolete. Please use 'before:' and 'after:' instead.</dd>
+ </dl>
+</div>
 <br>
 
 
@@ -1632,6 +1785,8 @@ _erbout
 <p>This section shows how to use Kwartz with Ruby on Rails.
 See 'examples/rails1' and 'examples/rails2' for examples.
 </p>
+<p><span style="color:#FF0000">NOTICE: THIS IS OBSOLETE INFORMATION.</span>
+</p>
 <a name="rails_template"></a>
 <h3 class="section2">Support of Ruby on Rails</h3>
 <p>If you want to use Kwartz with Ruby on Rails, add the following code in your 'app/controllers/application.rb' and restart web server.

data/kwartz.gemspec

@@ -3,8 +3,8 @@
 ###
 ### RubyGems Specification file for Kwartz-ruby
 ###
-### $Rev: 142 $
-### $Release: 3.1.2 $
+### $Rev$
+### $Release: 3.2.0 $
 ### copyright(c) 2004-2006 kuwata-lab.com all rights reserved
 ###
 
@@ -14,7 +14,7 @@ spec = Gem::Specification.new do |s|
   ## package information
   s.name        = 'kwartz'
   s.author      = 'Makoto Kuwata'
-  s.version     = ("$Release: 3.1.2 $" =~ /[\.\d]+/) && $&
+  s.version     = ("$Release: 3.2.0 $" =~ /[\.\d]+/) && $&
   s.platform    = Gem::Platform::RUBY
   s.homepage    = 'http://www.kuwata-lab.com/kwartz'
   s.summary     = "a template system for Ruby, PHP, and Java"
@@ -45,7 +45,7 @@ spec = Gem::Specification.new do |s|
   #           #"doc/design.css", "doc/design.html",
   #         ]
   files += Dir.glob('doc-api/**/*')
-  files += %w[README.txt ChangeLog LGPL setup.rb kwartz.gemspec]
+  files += %w[README.txt CHANGES LGPL setup.rb kwartz.gemspec]
   s.files       = files
   s.executables = ["kwartz"]
   s.bindir      = "bin"