kodekopelli 0.8.0

data/examples/thankyounotes/generated/README.txt

@@ -0,0 +1 @@
+This folder contains all content generated by Kodekopelli processing.

data/examples/thankyounotes/includes/poem.txt

@@ -0,0 +1,3 @@
+Roses are red,
+Violets are blue,
+That was awfully nice of you!

data/examples/thankyounotes/templates/thanks.txt

@@ -0,0 +1,14 @@
+<%= include_file(att('poem')) %>
+
+<%= Time.now.strftime("%B %d, %Y") %>
+
+Dear <%= att('to', 'Friend') %>,
+
+Thank-you very much for <%= att('purpose', 'everything') %>.
+
+<%= att('closing', 'Yours Truly') %>,
+
+<%= att('from', 'Kodekopelli') %>
+<% unless att('ps',nil).nil? %>
+P.S. <%= att('ps') %>
+<% end %>

data/examples/treemenu/config.xml

@@ -0,0 +1,110 @@
+<kodekopelli
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:noNamespaceSchemaLocation="http://www.kodekopelli.org/xml/schemas/kodekopelli.xsd">
+  <!-- Project structure properties.  These locations should
+  already exist. -->
+  <property location="." name="basedir" />
+  <!-- Folder containing Kodekopelli templates. -->
+  <property location="${basedir}/templates"
+    name="template.dir" />
+  <!-- Folder that should contain all Kodekopelli output. -->
+  <property location="${basedir}/generated"
+    name="output.dir" />
+  <!-- Templates -->
+  <property location="${template.dir}/simple_menu.txt"
+    name="menu" />
+  <property location="${template.dir}/menu_category.txt"
+    name="category" />
+  <property location="${template.dir}/menu_item.txt"
+    name="item" />
+  <property location="${template.dir}/authorized.txt"
+    name="authorized" />
+  <!-- URLs -->
+  <property name="admin.home.url" value="[URL GOES HERE]" />
+  <property name="add.user.url" value="[URL GOES HERE]" />
+  <property name="change.user.url" value="[URL GOES HERE]" />
+  <property name="delete.user.url" value="[URL GOES HERE]" />
+  <property name="admin.sys.url" value="[URL GOES HERE]" />
+  <property name="admin.user.url" value="[URL GOES HERE]" />
+  <property name="site.statistics.url"
+    value="[URL GOES HERE]" />
+  <property name="server.status.url" value="[URL GOES HERE]" />
+  <property name="auditing.url" value="[URL GOES HERE]" />
+  <property name="hr.home.url" value="[URL GOES HERE]" />
+  <property name="some.hr.url" value="[URL GOES HERE]" />
+  <property name="another.hr.url" value="[URL GOES HERE]" />
+  <property name="public.item.one.url"
+    value="[URL GOES HERE]" />
+  <property name="public.item.two.url"
+    value="[URL GOES HERE]" />
+  <property name="marketing.home.url"
+    value="[URL GOES HERE]" />
+  <property name="some.marketing.url"
+    value="[URL GOES HERE]" />
+  <filegroup>
+    <!-- The main menu. -->
+    <file name="${output.dir}/main_menu.jsp">
+      <composite template="${menu}">
+        <composite template="${category}"
+          text="Public Menu Category">
+          <composite template="${menu}">
+            <template target="_blank" template="${item}" text="Public Item One" 
+              url="${public.item.one.url}" />
+            <template template="${item}" text="Public Item Two" 
+              url="${public.item.two.url}" />
+          </composite>
+        </composite>
+        <composite roles="ROLE_MARKETING"
+          template="${authorized}">
+          <composite target="_blank" template="${category}"
+            text="Marketing Menu Category"
+            url="${marketing.home.url}">
+            <composite template="${menu}">
+              <template template="${item}" text="Marketing Item One" url="${some.marketing.url}" />
+            </composite>
+          </composite>
+        </composite>
+        <composite roles="ROLE_HUMAN_RESOURCES"
+          template="${authorized}">
+          <composite target="_blank" template="${category}"
+            text="Human Resources Menu Category"
+            url="${hr.home.url}">
+            <composite template="${menu}">
+              <template template="${item}" text="HR Item One" url="${some.hr.url}" />
+              <template template="${item}" text="HR Item Two" url="${another.hr.url}" />
+            </composite>
+          </composite>
+        </composite>
+        <composite roles="ROLE_SYS_ADMIN"
+          template="${authorized}">
+          <composite target="_blank" template="${category}"
+            text="Amin Menu Category"
+            url="${admin.home.url}">
+            <composite template="${menu}">
+              <composite target="_blank"
+                template="${category}"
+                text="User Administration Menu Category"
+                url="${admin.user.url}">
+                <composite template="${menu}">
+                  <template template="${item}" text="Add User" url="${add.user.url}" />
+                  <template template="${item}" text="Change User" url="${change.user.url}" />
+                  <template template="${item}" text="Delete User" url="${delete.user.url}" />
+                </composite>
+              </composite>
+              <composite target="_blank"
+                template="${category}"
+                text="System Administration Menu Category"
+                url="${admin.sys.url}">
+                <composite template="${menu}">
+                  <template template="${item}" text="Auditing" url="${auditing.url}" />
+                  <template template="${item}" text="Site Statistics" url="${site.statistics.url}" />
+                  <template template="${item}" text="Server Status" url="${server.status.url}" />
+                </composite>
+              </composite>
+            </composite>
+          </composite>
+        </composite>
+      </composite>
+    </file>
+  </filegroup>
+</kodekopelli>

data/examples/treemenu/content.rhtml

@@ -0,0 +1,324 @@
+<p class="note">
+  <strong>Please Note</strong> This example should be considered a work in progress.
+  Although all associated configuration files and templates have been completed and
+  are included in this example, not all supporting text has been added.
+</p>
+<p>
+  This simple example demonstrates basic Kodekopelli functionality
+  and recommended practices.  The following Kodekopelli concepts
+  not covered by previous examples are illustrated herein:
+</p>
+<ul>
+  <li>
+    Integrating other view layer technologies
+    (JSP custom tags) in Kodekopelli templates.
+  </li>
+  <li>
+    Nesting <a href="<%= att 'manual' %>#composites">composite</a>
+    elements in Kodekopelli configuration files.
+  </li>
+</ul>
+<p>
+  Unlike the introductory examples (<a href="/examples/thankyounotes">Thank-You Notes</a>
+  and <a href="/examples/faqomatic">FAQ-O-Matic</a>),
+  this example doesn't strive to impart deep knowledge of the Kodekopelli
+  directives used herein; rather, it presents those templates and configuration
+  files necessary to achieve the goal state shown below.
+</p>
+<h2>Problem</h2>
+<p>
+  Several sites on your corporate intranet make use of complex tree menus.
+  Each menu is composed of one (1) or more top level menu categories and
+  each menu category is composed of one (1) or more menu items or additional
+  categories.  Further, the menus often must nest to three (3) or four (4)
+  levels deep.  To complicate things even more, each menu category and menu item
+  may need to be wrapped, individually, with one or more JSP custom tags that provide
+  access control, among other things.  When combined with significant CSS
+  directives, your menu-related JSPs have become unwieldy and prone to human
+  error.
+</p>
+<h2>Solution</h2>
+<p>
+  Use Kodekopelli as an additional layer of abstraction for
+  generating tree menu JSP fragments.  The relevant menu-related
+  entries in the Kodekopelli configuration file(s) will then
+  serve as a kind of
+  <a href="http://en.wikipedia.org/wiki/Domain_Specific_Language"
+  target="">domain-specific language</a> that is easily
+  modifiable by humans, leaving the tedious process of JSP construction
+  to Kodekopelli.
+</p>
+<h3>Project Structure</h3>
+<p>
+  As with the previous examples, those files that Kodekopelli
+  <em>generates</em> will be separated from those
+  that he uses to generate said files.  Starting from a fresh, empty folder
+  of your choice, create subfolders mirroring the following structure:
+</p>
+<pre class="code">
+  /generated
+  /templates
+</pre>
+<h3>The Goal</h3>
+<ul>
+	<li>
+		Public Menu Category 
+		<br />
+		<ul>
+			<li>
+				<a href="" target="">
+					Public Item One
+				</a>
+			</li>
+			<li>
+				<a href="" target="">
+					Public Item Two
+				</a>
+			</li>
+		</ul>
+	</li>
+	<li>
+		<a href="" target="">
+			Marketing Menu Category
+		</a>
+		<br />
+		<ul>
+			<li>
+				<a href="" target="">
+					Marketing Item One
+				</a>
+			</li>
+		</ul>
+	</li>
+	<li>
+		<a href="" target="">
+			Human Resources Menu Category
+		</a>
+		<br />
+		<ul>
+			<li>
+				<a href="" target="">
+					HR Item One
+				</a>
+			</li>
+			<li>
+				<a href="" target="">
+					HR Item Two
+				</a>
+			</li>
+		</ul>
+	</li>
+	<li>
+		<a href="" target="">
+			Amin Menu Category
+		</a>
+		<br />
+		<ul>
+			<li>
+				<a href="" target="">
+					User Administration Menu Category
+				</a>
+				<br />
+				<ul>
+					<li>
+						<a href="" target="">
+							Add User
+						</a>
+					</li>
+					<li>
+						<a href="" target="">
+							Change User
+						</a>
+					</li>
+					<li>
+						<a href="" target="">
+							Delete User
+						</a>
+					</li>
+				</ul>
+			</li>
+			<li>
+				<a href="" target="">
+					System Administration Menu Category
+				</a>
+				<br />
+				<ul>
+					<li>
+						<a href="" target="">
+							Auditing
+						</a>
+					</li>
+					<li>
+						<a href="" target="">
+							Site Statistics
+						</a>
+					</li>
+					<li>
+						<a href="" target="">
+							Server Status
+						</a>
+					</li>
+				</ul>
+			</li>
+		</ul>
+	</li>
+</ul>
+<h3>Templates</h3>
+<p>
+  The menu shown above may be created using four simple templates, described
+  below.
+</p>
+<h4>Simple Menu Template</h4>
+<pre class="code">
+  &lt;ul&gt;&lt;% child_iterator { |current_child, text| %&gt;
+    &lt;%= text %&gt;&lt;% } %&gt;
+  &lt;/ul&gt;
+</pre>
+<h4>Menu Category Template</h4>
+<pre class="code">
+  &lt;li&gt;&lt;% unless att('url',nil).nil? %&gt;&lt;a href="&lt;%= att('url') %&gt;"
+  target="&lt;%= att('target') %&gt;"
+  &gt;&lt;% end %&gt;&lt;%= h att('text') %&gt;&lt;% unless att('url',nil).nil? %&gt;&lt;/a&gt;&lt;% end %&gt;&lt;br /&gt;
+  &lt;%= child_output %&gt;&lt;/li&gt;
+</pre>
+<h4>Menu Item Template</h4>
+<pre class="code">
+  &lt;li&gt;&lt;% unless att('url',nil).nil? %&gt;&lt;a href="&lt;%= att('url') %&gt;"
+  target="&lt;%= att('target') %&gt;"
+  &gt;&lt;% end %&gt;&lt;%= h att('text') %&gt;&lt;% unless att('url',nil).nil? %&gt;&lt;/a&gt;&lt;% end %&gt;&lt;/li&gt;
+</pre>
+<h4>Authorization Control Template</h4>
+<p>
+  This template leverages the <em>authz</em> JSP custom tag library provided by
+  the open source <a href="http://acegisecurity.sourceforge.net/" 
+  target="_blank">Acegi Security System</a>.
+</p>
+<pre class="code">
+  &lt;authz:authorize ifAnyGranted="&lt;%= att('roles') %&gt;"&gt;&lt;%= child_output %&gt;&lt;/authz:authorize&gt;
+</pre>
+<h3>Configuration File</h3>
+<p>
+  The completed Kodekopelli configuration file is shown, in its entirety,
+  below.
+</p>
+<pre class="code">
+  &lt;kodekopelli&gt;
+    &lt;!-- Project structure properties.  These locations should
+    already exist. --&gt;
+    &lt;property location="." name="basedir" /&gt;
+    &lt;!-- Folder containing Kodekopelli templates. --&gt;
+    &lt;property location="${basedir}/templates"
+      name="template.dir" /&gt;
+    &lt;!-- Folder that should contain all Kodekopelli output. --&gt;
+    &lt;property location="${basedir}/generated"
+      name="output.dir" /&gt;
+    &lt;!-- Templates --&gt;
+    &lt;property location="${template.dir}/simple_menu.txt"
+      name="menu" /&gt;
+    &lt;property location="${template.dir}/menu_category.txt"
+      name="category" /&gt;
+    &lt;property location="${template.dir}/menu_item.txt"
+      name="item" /&gt;
+    &lt;property location="${template.dir}/authorized.txt"
+      name="authorized" /&gt;
+    &lt;!-- URLs --&gt;
+    &lt;property name="admin.home.url" value="[URL GOES HERE]" /&gt;
+    &lt;property name="add.user.url" value="[URL GOES HERE]" /&gt;
+    &lt;property name="change.user.url" value="[URL GOES HERE]" /&gt;
+    &lt;property name="delete.user.url" value="[URL GOES HERE]" /&gt;
+    &lt;property name="admin.sys.url" value="[URL GOES HERE]" /&gt;
+    &lt;property name="admin.user.url" value="[URL GOES HERE]" /&gt;
+    &lt;property name="site.statistics.url"
+      value="[URL GOES HERE]" /&gt;
+    &lt;property name="server.status.url" value="[URL GOES HERE]" /&gt;
+    &lt;property name="auditing.url" value="[URL GOES HERE]" /&gt;
+    &lt;property name="hr.home.url" value="[URL GOES HERE]" /&gt;
+    &lt;property name="some.hr.url" value="[URL GOES HERE]" /&gt;
+    &lt;property name="another.hr.url" value="[URL GOES HERE]" /&gt;
+    &lt;property name="public.item.one.url"
+      value="[URL GOES HERE]" /&gt;
+    &lt;property name="public.item.two.url"
+      value="[URL GOES HERE]" /&gt;
+    &lt;property name="marketing.home.url"
+      value="[URL GOES HERE]" /&gt;
+    &lt;property name="some.marketing.url"
+      value="[URL GOES HERE]" /&gt;
+    &lt;filegroup&gt;
+      &lt;!-- The main menu. --&gt;
+      &lt;file name="${output.dir}/main_menu.jsp"&gt;
+        &lt;composite template="${menu}"&gt;
+          &lt;composite template="${category}"
+            text="Public Menu Category"&gt;
+            &lt;composite template="${menu}"&gt;
+              &lt;template target="_blank" template="${item}" text="Public Item One" 
+                url="${public.item.one.url}" /&gt;
+              &lt;template template="${item}" text="Public Item Two" 
+                url="${public.item.two.url}" /&gt;
+            &lt;/composite&gt;
+          &lt;/composite&gt;
+          &lt;composite roles="ROLE_MARKETING"
+            template="${authorized}"&gt;
+            &lt;composite target="_blank" template="${category}"
+              text="Marketing Menu Category"
+              url="${marketing.home.url}"&gt;
+              &lt;composite template="${menu}"&gt;
+                &lt;template template="${item}" text="Marketing Item One" url="${some.marketing.url}" /&gt;
+              &lt;/composite&gt;
+            &lt;/composite&gt;
+          &lt;/composite&gt;
+          &lt;composite roles="ROLE_HUMAN_RESOURCES"
+            template="${authorized}"&gt;
+            &lt;composite target="_blank" template="${category}"
+              text="Human Resources Menu Category"
+              url="${hr.home.url}"&gt;
+              &lt;composite template="${menu}"&gt;
+                &lt;template template="${item}" text="HR Item One" url="${some.hr.url}" /&gt;
+                &lt;template template="${item}" text="HR Item Two" url="${another.hr.url}" /&gt;
+              &lt;/composite&gt;
+            &lt;/composite&gt;
+          &lt;/composite&gt;
+          &lt;composite roles="ROLE_SYS_ADMIN"
+            template="${authorized}"&gt;
+            &lt;composite target="_blank" template="${category}"
+              text="Amin Menu Category"
+              url="${admin.home.url}"&gt;
+              &lt;composite template="${menu}"&gt;
+                &lt;composite target="_blank"
+                  template="${category}"
+                  text="User Administration Menu Category"
+                  url="${admin.user.url}"&gt;
+                  &lt;composite template="${menu}"&gt;
+                    &lt;template template="${item}" text="Add User" url="${add.user.url}" /&gt;
+                    &lt;template template="${item}" text="Change User" url="${change.user.url}" /&gt;
+                    &lt;template template="${item}" text="Delete User" url="${delete.user.url}" /&gt;
+                  &lt;/composite&gt;
+                &lt;/composite&gt;
+                &lt;composite target="_blank"
+                  template="${category}"
+                  text="System Administration Menu Category"
+                  url="${admin.sys.url}"&gt;
+                  &lt;composite template="${menu}"&gt;
+                    &lt;template template="${item}" text="Auditing" url="${auditing.url}" /&gt;
+                    &lt;template template="${item}" text="Site Statistics" url="${site.statistics.url}" /&gt;
+                    &lt;template template="${item}" text="Server Status" url="${server.status.url}" /&gt;
+                  &lt;/composite&gt;
+                &lt;/composite&gt;
+              &lt;/composite&gt;
+            &lt;/composite&gt;
+          &lt;/composite&gt;
+        &lt;/composite&gt;
+      &lt;/file&gt;
+    &lt;/filegroup&gt;
+  &lt;/kodekopelli&gt;
+</pre>
+<h2>Notes</h2>
+<ul>
+  <li>
+    It would be very simple to enhance the templates to allow for specifying
+    CSS classes for all menu elements, allowing for greater control
+    over menu aesthetics.  Numerous sites, like
+    <a href="http://css.maxdesign.com.au/listamatic/" target="">Listamatic</a>,
+    provide great examples for controlling the look and feel (LAF) of
+    menus based on unordered lists.
+  </li>
+</ul>