---
title:  Partials
blurb:  Take advantage of <em>Middlemac</em>’s partials, and maybe even learn to
        write your own!
layout: template-logo-medium
---
<%= md_links %>
<%= md_images %>


<%= current_page.data.title %>
==============================

<%= current_page.data.blurb %>

_Middlemac_ includes several partials that it uses to provide a structured,
easy to use framework for generating Apple Help Books. You can use these 
partials as they are or modify them to suit your preferences.

The included partials are mostly functional, but you can also make partials for
other content that you use repeatedly throughout your project.

Note that all partials source filenames are prefixed with an underscore, and
they also don’t have an `.html` extension. Partials will be included in your
content pages; we don’t want _Middleman_ to output them into the build
directory!
{:.note}

Although the partials discussed below are included in the source code for this
documentation project, they’re not used in this project. Instead this project
uses the helpers that correspond to the partials below.
{:.note}


Included partials
-----------------

Note: because partials are included with the `partial` helper without the
leading underscore and extension, by convention they are mentioned in this
documentation without these decorations, too.

`nav_breadcrumbs` and `nav_breadcrumbs_alt`
 : These (two variations) render the breadcrumbs widget at the top of the 
   window.

`nav_brethren` and `nav_brethren_index`
 : These partials render lists of all sibling pages that have a sort order and
   are part of the current target and feature settings. `nav_brethren` includes
   the page’s `:blurb` front matter data, and `nav_brethren_index` lacks this.
 
`nav_legitimate_children`
 : Renders a list with link and blurb for all legitimate children, i.e.,
   children that have a sort order and are allowed by the current target and
   features settings.

`nav_prev_next`
 : This partial renders the navigation widget on pages that have it enabled.

`nav_toc_index`
 : Renders a site-map style index starting at `current_page` or at a passed-in
   resource.
   
Partials are an excellent alternative to the provided helpers, especially if
you want to make modifications. Because they correspond exactly with their
eponymic helpers, you should refer to the [helper API reference][helpers_ref].


Your Own Partials
-----------------

The included partials are purely functional, i.e., they provide service to key
parts of _Middlemac_’s framework. You can write your own partials that provide
functionality, too, such as rendering something from a
[local data file][using_local_data].

You can also use partials to contain oft-used content. Maybe pieces of a change
log, should you want to present that information to your users in multiple
places. Maybe common warnings that can be included in multiple pages.


Conventions
-----------

Partials should be placed into the correct `partials` directory so that
_Middleman_’s `partial` helper can find them.

Because partials are not rendered into final HTML output files, you should
prefix their filenames with and underscore, and _not_ include `.html` in the
extensions chain.

When using the `partial` helper, _Middleman_ already expects the actual file to
be prefixed with an underscore, therefore you should _not_ include the
underscore when you use the helper.

~~~ erb
<%%= partial 'include_me' %>
~~~

_not_

~~~ erb
<%%= partial '_include_me' %>
~~~

You can pass data to partials as local variable context within the partial.
For example:

~~~ erb
<%%= partial 'hello_world', :locals => { :one => 'Rabbit', :color => 'pink' } %>
~~~

Then, within the code of the partial, you will have local variables `one` and
`color` available to you with their respective values.

Note: these hash key-values use a symbol as a key, and a value as the value for
the key. This is not the same as assigning a value to the Ruby symbol, because
the symbol’s value is simply itself. The hash key is like an `id` object in an
`NSDictionary`. Then when passed to the partial, there will exist a new local
variable using the symbol name. The symbol `:one` becomes the variable `one`
having a string value “pink” in this example.
{:.note}