doc/guides/html/building_templates.html in browsercms-3.1.0 vs doc/guides/html/building_templates.html in browsercms-3.1.1
- old
+ new
@@ -133,11 +133,11 @@
<tr>
<td class="sidebar" valign="top">
<div id="subCol">
<h3 class="chapter"><img src="images/chapters_icon.gif" alt="" />Chapters</h3>
<ol class="chapters">
-<li><a href="#introduction">Introduction</a><ul><li><a href="#typical-design-process">Typical Design Process</a></li><li><a href="#design-considerations">Design Considerations</a></li></ul></li><li><a href="#creating-a-page-template">Creating a Page Template</a><ul><li><a href="#files-or-content">Files or Content?</a></li><li><a href="#understanding-containers">Understanding Containers</a></li><li><a href="#adding-a-sidebar-container">Adding A Sidebar Container</a></li></ul></li><li><a href="#tags-quick-reference">Tags Quick Reference</a><ul><li><a href="#required-tags">Required Tags</a></li><li><a href="#container-tag"><tt>container</tt> Tag</a></li><li><a href="#cms-toolbar-tag"><tt>cms_toolbar</tt> Tag</a></li><li><a href="#html-head-tag"><span class="caps">HTML</span> Head Tag</a></li><li><a href="#page-title-tag"><tt>page_title</tt> Tag</a></li><li><a href="#current-page-tag"><tt>current_page</tt> Tag</a></li><li><a href="#render-portlet-tag"><tt>render_portlet</tt> Tag</a></li><li><a href="#render-connectable-tag"><tt>render_connectable</tt> Tag</a></li></ul></li><li><a href="#navigation">Navigation</a><ul><li><a href="#basic-rules-of-menus">Basic Rules of Menus</a></li><li><a href="#using-menus">Using Menus</a></li><li><a href="#how-deep-should-menus-be">How Deep Should Menus Be?</a></li><li><a href="#primary-navigation">Primary Navigation</a></li><li><a href="#sub-navigation">Sub Navigation</a></li><li><a href="#site-maps-and-flyout-menus">Site Maps and Flyout Menus</a></li><li><a href="#using-breadcrumbs">Using Breadcrumbs</a></li></ul></li><li><a href="#using-partials">Using Partials</a><ul></ul></li></ol></div>
+<li><a href="#introduction">Introduction</a><ul><li><a href="#typical-design-process">Typical Design Process</a></li><li><a href="#design-considerations">Design Considerations</a></li></ul></li><li><a href="#creating-a-page-template">Creating a Page Template</a><ul><li><a href="#files-or-content">Files or Content?</a></li><li><a href="#understanding-containers">Understanding Containers</a></li><li><a href="#adding-a-sidebar-container">Adding A Sidebar Container</a></li></ul></li><li><a href="#tags-quick-reference">Tags Quick Reference</a><ul><li><a href="#required-tags">Required Tags</a></li><li><a href="#container-tag"><tt>container</tt> Tag</a></li><li><a href="#container-has-block-tag"><tt>container_has_block?</tt> Tag</a></li><li><a href="#cms-toolbar-tag"><tt>cms_toolbar</tt> Tag</a></li><li><a href="#html-head-tag"><span class="caps">HTML</span> Head Tag</a></li><li><a href="#page-title-tag"><tt>page_title</tt> Tag</a></li><li><a href="#current-page-tag"><tt>current_page</tt> Tag</a></li><li><a href="#render-portlet-tag"><tt>render_portlet</tt> Tag</a></li><li><a href="#render-connectable-tag"><tt>render_connectable</tt> Tag</a></li></ul></li><li><a href="#navigation">Navigation</a><ul><li><a href="#basic-rules-of-menus">Basic Rules of Menus</a></li><li><a href="#using-menus">Using Menus</a></li><li><a href="#how-deep-should-menus-be">How Deep Should Menus Be?</a></li><li><a href="#primary-navigation">Primary Navigation</a></li><li><a href="#sub-navigation">Sub Navigation</a></li><li><a href="#site-maps-and-flyout-menus">Site Maps and Flyout Menus</a></li><li><a href="#using-breadcrumbs">Using Breadcrumbs</a></li></ul></li><li><a href="#using-partials">Using Partials</a><ul></ul></li></ol></div>
</td>
<td class="guides">
<h2>Templates Guide</h2>
<p>This guide covers how to set up templates for BrowserCMS. After reading this guide, you should understand how to:</p>
<ul>
@@ -227,18 +227,19 @@
<p>Having seen the sample templates, it should be possible to construct <span class="caps">HTML</span> templates using typical <span class="caps">HTML</span> and <span class="caps">CSS</span>, place containers in them where content should appear and get a reasonable looking set of templates.</p>
<h3 id="tags-quick-reference">3 Tags Quick Reference</h3>
<p>This section covers a reference for all the tags (aka Helper Methods) that can be used in Page Templates to render various elements. Here is a quick list of the available tags, their purpose and whether they are required or not.</p>
<p>._ Name |<em>. Purpose | Required? |
| <tt>container</tt> | A named area that allows users to add/edit content | Yes |
-| <tt>cms</em>toolbar</tt></notextile> | Renders the <span class="caps">CMS</span> toolbar controller required for editing and navigation. Should be very first element in <tt>body</tt> | Yes |
+| <tt>container_has_block</tt> | To hide markup if a container is empty | No |
+| <tt>cms_toolbar</tt> | Renders the <span class="caps">CMS</span> toolbar controller required for editing and navigation. Should be very first element in <tt>body</tt> | Yes |
| <tt>yield :html_head | This allows the CMS to insert javascript and other information into the page. Should be last element in </tt>head+ | Yes |
| <tt>page_title</tt> | Inserts the ‘Name’ of the page (or ‘Title’ if it exists) | No |
| <tt>current_page</tt> | Returns a reference to the <tt>Page</tt> object that is currently being rendered | No |
| <tt>render_breadcrumbs</tt> | Generates breadcrumbs based on the current page and its location in the sitemap | No |
| <tt>render_menu</tt> | Generates a menu based on the current page and its location in the sitemap | No |
| <tt>render_portlet</tt> | Renders a specific portlet by name | No |
-| <tt>render_connectable</tt> | Renders a specific content block | No |</p>
+| <tt>render</em>connectable</tt></notextile> | Renders a specific content block | No |</p>
<p>In addition, since Page Templates are Rails layouts, you can make use of any of the Asset Tags":http://guides.rubyonrails.org/layouts_and_rendering.html#structuring-layouts like <tt>stylesheet_link_tag</tt> or <tt>image_tag</tt>.</p>
<h4 id="required-tags">3.1 Required Tags</h4>
<p>While most of the tags are optional, there are several tags which must be included or page template just won’t work correctly. Here’s the minimum necessary tags required.</p>
<p>1. <tt>yield :html_head</tt> – Leaving this out will cause problems with in page editing.
2. <tt>cms_toolbar</tt> – Leaving this out will provide editing and navigation to other <span class="caps">CMS</span> pages.
@@ -247,46 +248,52 @@
<p>This tag is used to allow areas of the page to be editted and render through the <span class="caps">CMS</span>. It takes a single argument which is the name of the container. Template developers can name containers whatever they like, but its recommened that the names should generally reflect the area or purpose of a particular container.</p>
<div class="code_container"><code class="html"><div><%= container :main %></div>
<div><%= container :footer %></div></code></div>
<p>Container names are just labels. So if you defined 5 containers on a template (header, footer, left, main, right), you could swap between any two templates which defined all those containers.</p>
<div class='note'><p>Be aware that if you add content to a page in a container (like <tt>:sidebar</tt>) then change a pages template to one which does not have that container, the content will be ‘orphaned’. To remove that content, you would need to swap back to the previous template, remove the content, then change back to the new template again.</p></div>
-<h4 id="cms-toolbar-tag">3.3 <tt>cms_toolbar</tt> Tag</h4>
+<h4 id="container-has-block-tag">3.3 <tt>container_has_block?</tt> Tag</h4>
+<p>This tag can be used to hide or show containers based on whether a user has placed content in them. While an empty <tt>container</tt> tag won’t show anything, very frequently template builders will create ‘wrapper’ markup around containers that shouldn’t appear when nothing is placed there. For example, suppose we have a sidebar container that we want to have a styled border on, but we only want it to appear when something is in that container. Here’s how you would do that:</p>
+<div class="code_container"><code class="html"><% unless container_has_block? :sidebar %>
+ <div id="sidebar"><%= container :sidebar %></div>
+ <% end %></code></div>
+<p>This tag returns true if the user is in edit mode as well, regardless of whether there is content within the container. This is important, because otherwise, an editor would never be able to select the container to add content to!</p>
+<h4 id="cms-toolbar-tag">3.4 <tt>cms_toolbar</tt> Tag</h4>
<p>This tag is how the toolbar is inserted into templates. It should be the first element in the <tt>body</tt> element of a page. In most cases, you can just use it as follows:</p>
<div class="code_container"><code class="html"><body>
<%= cms_toolbar %>
<h2>About Us</h2>
<!-- Text goes here -->
</body></code></div>
<p>The toolbar is written out as an iframe which makes its less likely that styles/javascript will clash with the page being editted.</p>
-<h4 id="html-head-tag">3.4 <span class="caps">HTML</span> Head Tag</h4>
+<h4 id="html-head-tag">3.5 <span class="caps">HTML</span> Head Tag</h4>
<p>This tag is technically a standard <tt>yield</tt> call, with a particularly named <tt>:html_head</tt>. This tag must be included in all <span class="caps">CMS</span> templates to allow it to insert the necessary javascript and style elements. It should probably be the last element in <tt>head</tt> element of a page.</p>
<div class="code_container"><code class="html"><head>
<title><%= page_title %></title>
<%= yield :html_head %>
</head></code></div>
-<h4 id="page-title-tag">3.5 <tt>page_title</tt> Tag</h4>
+<h4 id="page-title-tag">3.6 <tt>page_title</tt> Tag</h4>
<p>This tag will output the <tt>name</tt> attribute of the current page. If the <tt>title</tt> attribute is specified, it will output that instead. This allows users to have one label for a page appear in the navigation (navigation and the sitemap always use <tt>name</tt>) and another in the header or title bar on a page.</p>
<p>Example:</p>
<div class="code_container"><code class="html"><title>My Site | <%= page_title %></title></code></div>
<p>This is using the page_title tag to title element of a page.</p>
<div class="code_container"><code class="html"><h1><%= page_title %></h1></code></div>
<p>Another common usage of <tt>page_title</tt> is for the H1 or H2 on a page.</p>
-<h4 id="current-page-tag">3.6 <tt>current_page</tt> Tag</h4>
+<h4 id="current-page-tag">3.7 <tt>current_page</tt> Tag</h4>
<p>This doesn’t render anything, but returns a reference to the current <tt>Page</tt> object that is being rendered. It can be used to access other attributes of the page, like the name of the section or the <tt>description</tt> of the Page. Here are some common examples:</p>
<div class="code_container"><code class="html"><%= current_page.name %></code></div>
<p>This outputs the <tt>name</tt> attribute of the page, similar to how <tt>page_title</tt> works. You might do this if you had specified a <tt>title</tt> attribute for pages which was different than the <tt>name</tt>, but wanted to compare names.</p>
<div class="code_container"><code class="html"><%= current_page.section.name %></code></div>
<p>This outputs the <tt>name</tt> of the current page’s section.</p>
<div class="code_container"><code class="html"><% if current_page.top_level_section.name == 'About Us' %>
<%= image_tag "/fancy/about_us_section_image.png" %>
<% end %></code></div>
<p>This renders a specific image if the page is within the top level ‘About Us’ section. The <tt>top_level_section</tt> method finds the very top level section for a give page, regardless of how far down it is in the sitemap. Useful for making comparisons based on the first level of navigation.</p>
<div class='note'><p>Any page or section attribute is reachable in the way. You will need to look at the <span class="caps">API</span> documentation for <tt>Page</tt> and <tt>Section</tt> to see all the available attributes.</p></div>
-<h4 id="render-portlet-tag">3.7 <tt>render_portlet</tt> Tag</h4>
+<h4 id="render-portlet-tag">3.8 <tt>render_portlet</tt> Tag</h4>
<p>This tag will render a portlet from a template. Normally portlets are placed individually on each page by users. This tag is useful for common elements that might appear on multiple pages throughout the site. An example of this might be a Login Portlet which should appear as part of the header on all pages. Here’s an example:</p>
<div class="code_container"><code class="html"><%= render_portlet "Nav Login Form" %></code></div>
<p>The only argument to <tt>render_portlet</tt> is a name. This name will match the name specified in the UI when you add a portlet. You will need to create the portlet and name in appropriately for this tag to work. The portlet will render itself based on its template.</p>
-<h4 id="render-connectable-tag">3.8 <tt>render_connectable</tt> Tag</h4>
+<h4 id="render-connectable-tag">3.9 <tt>render_connectable</tt> Tag</h4>
<p>This tag can render a specific block in a page. It takes one argument, the block itself. This could be used to automatically include, say a footer, into a page as part of the template. For instance:</p>
<div class="code_container"><code class="html"><% footer = HtmlBlock.find(12) %>
<%= render_connectable(footer) %></code></div>
<p>Here we use Active Record to query for a specific HtmlBlock (i.e. Text) with the id of 12. Then we pass it to <tt>render_connectable</tt> to display itself.</p>
<h3 id="navigation">4 Navigation</h3>