<html>
<body>

<h1>ReportLab Binder: Documentation</h1>

<p>This page describes how to create URLs which either generate a specific document or link to a pre-expanded or pre-populated brochure creation page</p>

<h2>I. Direct Document Generation API</h2>

<p>URLs requesting any document can be systematically built up following a few quick steps:</p>

<ol>





<table>
    <tr style="background:#ccc">
        <th>Name</th>
        <th>Slug</th>
        <th>Section ID</th>
        <th>Abstract</th>
        <th>Mandatory</th>
    </tr>
    {%for s in sections%}
    <tr {%if s.abstract%}style="background:#ddd"{%endif%}>
        <td>
            {{s.name}}
        </td>
        <td>
            {{s.slug}}
        </td>
        <td>
            {{s.id}}
        </td>
        <td>
            {%if s.abstract%}x{%endif%}
        </td>
        <td>
            {%if s.mandatory%}x{%endif%}
        </td>
    </tr>
    {%endfor%}
</table>






<li><i>Type the root</i> - this will stay the same for any given document and is the URL of the public facing search page followed by /api/?.  For this particular document, the root is:
<br><br>

<code>http://binder.ebrochures.org/brochure/doc-name/api/?</code>
</li>
<br>

<li><i>Define the sections to be included</i> as a comma separated list after the root; possible values are given in the table below.  Sections marked "mandatory" will always be included and including a section marked "abstract" will include every section within it.  An example of a document with just the short programmes and masters degrees sections would be:
<br><br>
{%for s in sections%}
{%if s.abstract%}
<code><a href="http://bpp.ebrochures.org/brochure/law/api/?sections={{s.name}}" target="_blank">http://bpp.ebrochures.org/brochure/law/api/?sections=short-programmes,masters-degrees</a></code>
{%endif%}
{%endfor%}
</li>
<br>

<li><i>Define any extra text fields</i> that are supported in the document template, including <b>title, subtitle, blurb, header, footer,</b> and<b> reference</b>.  Separate each piece of the URL with the "&amp;" symbol.  For example, to add a custom title and subtitle to the above document:
<br><br>
<code><a href="http://bpp.ebrochures.org/brochure/law/api/?sections=short-programmes,masters-degrees&title=BPP Law Brochure&subtitle=Customised for John Smith" target="_blank">http://bpp.ebrochures.org/brochure/law/api/?sections=short-programmes,masters-degrees&title=BPP Law Brochure&subtitle=Customised for John Smith</a></code>
</li>
<br>

<li><i>Define the "disposition"</i> (the way in which the document is served).  Possible values are:
<br><br>
<ul>
<li><code>inline</code> - return PDF content inline (open in pdf viewer inside browser) - this is the default.</li>
<li><code>attachment</code> - return PDF content as an attachment</li>
<li><code>html</code> - returns a html page with a link to the document</li>
<li><code>url (lower case)</code> - returns text of the document URL</li>
<li><code>flip_book</code> - returns a redirect to flash 'flipbook' version of the document</li>
<li><code>email</code> - attaches the document to an email and sends it.  Takes the following
additional parameters:</li><br>
<ul>
<li><code>&lt;email_to&gt;</code> (required) a single email address to send to.</li>
<li><code>&lt;subject&gt;</code> (optional) email subject line; defaults to 'You have been sent an
eBrochure'.</li>
<li><code>&lt;body&gt;</code> (optional) email body text; defaults to 'Your eBrochure is attached'.</li>
<li><code>&lt;email_from&gt;</code> (optional) if set, the subject line will read 'x has sent you an
eBrochure' - this option will override any prior definition of the subject field</li><br>
</ul>
</ul>

For example, to send the above document in an email with a custom subject:
<br><br>
<code><a href="http://bpp.ebrochures.org/brochure/law/api/?sections=short-programmes,masters-	degrees&title=BPP Law Brochure&subtitle=Customised for John Smith&disposition=email&email_to=john.smith@sampleemail.com&subject=John's BPP brochure" target="_blank">http://bpp.ebrochures.org/brochure/law/api/?sections=short-programmes,masters-	degrees&title=BPP Law Brochure&subtitle=Customised for John Smith&disposition=email&email_to=john.smith@sampleemail.com&subject=John's BPP brochure</a></code>
<br><br>
Or to download it directly:
<br><br>
<a href="http://bpp.ebrochures.org/brochure/law/api/?sections=short-programmes,masters-	degrees&title=BPP Law Brochure&subtitle=Customised for John Smith&disposition=attachment" target="_blank">http://bpp.ebrochures.org/brochure/law/api/?sections=short-programmes,masters-	degrees&title=BPP Law Brochure&subtitle=Customised for John Smith&disposition=attachment</a>
</li>
</ol>


<!--
<p><code>http://&lt;domain&gt;/brochure/&lt;documentName&gt;/api/?&lt;param1&gt;=val1,val2&&lt;param2&gt;=val1</code></p>

<p>The <code>&lt;section&gt;</code> parameter is required, with at least one value set.</p>

<p>The API recognises the following document generation parameters:</p>
<p><strong>1. &lt;sections&gt;</strong></p>
<p>The sections to be included in the document.  The available sections for each
document can be seen at the following url:</p>
<p><code>http://&lt;domain&gt;/brochure/&lt;documentName&gt;/help/</code></p>
<p>The section names, ids and slugs are listed at the bottom of the page, along with
the section type (abstract or mandatory).</p>

<p>The parameter value should be a comma separated list of section id numbers
and/or slugs (slugs are preferred).  Any abstract sections listed will automatically 
have all their subsections included.  Mandatory sections are always included.</p>

<strong>2. &lt;title&gt;,&lt;subtitle&gt;,&lt;blurb&gt;,&lt;header&gt;,&lt;footer&gt;,&lt;reference&gt;</strong>
<p>These parameters are all strings which display in the generic binder
table-of-contents page when set.</p>

<strong>3. &lt;disposition&gt;</h3></strong>
<p>Sets the 'content-disposition' of the HTTP Response.  Possible values:</p>
-->


<h2>II. Selection Page</h2>

<p>Similarly, URLs can be constructed which link to the brochure creation page and define its initial appearance:</p>

<ol>
<li>Start with root; this will be the URL of the brochure creation page followed by /?.  For this document, it would be:
<br><br>
<code>http://bpp.ebrochures.org/brochure/law/?</code>
</li>
<br>

<li>Define which headings are initially expanded in a comma separated list:
<br><br>
<code><a href="http://bpp.ebrochures.org/brochure/law/?expanded=short-programmes,masters-degrees" target="_blank">http://bpp.ebrochures.org/brochure/law/?expanded=short-programes,masters-degrees</a></code>
</li>
<br>

<li>Define which sections are pre-checked in a comma separated list:
<br><br>
<code><a href="http://bpp.ebrochures.org/brochure/law/?expanded=short-programmes,masters-degrees&sections=summer-school,ma-law-with-business" target="_blank">http://bpp.ebrochures.org/brochure/law/?expanded=short-programmes,masters-degrees&amp;sections=summer-school,ma-law-with-business</a></code>
</li>
<br>

<li>Control which download options are displayed and which is selected initially; possible values are
<br><br>

    <ul>
    <li>'download' or 1
    <li>'flip_book' or 2
    <li>'email' or 3
    </ul>
<br>

So to serve the above document with only download of flip-book options and flip-book initially selected:
<br><br>

<code><a href="http://bpp.ebrochures.org/brochure/law/?expanded=short-programmes,masters-degrees&sections=summer-school,ma-law-with-business&download_display=download,flip_book&download_option=flip_book" target="_blank">http://bpp.ebrochures.org/brochure/law/?expanded=short-programmes,masters-degrees&sections=summer-school,ma-law-with-business&download_display=download,flip_book&download_option=flip_book</a>
</li>
</ol>

<h2>III. Other Useful URLS</h2>

<p><code>http://&lt;domain&gt;/brochure/&lt;documentName&gt;/help/</code><p>

<p>This page.  General documentation; also lists the available sections
for <code>&lt;documentName&gt;</code></p>

<p><code>http://&lt;domain&gt;/brochure/&lt;documentName&gt;/sections</code></p>
<p>Returns a plain text JSON listing of the available sections for &lt;documentName&gt;</p>

<hr>

<h1>Available sections for document '{{pdf.name}}</h1>

<table>
    <tr style="background:#ccc">
        <th>Name</th>
        <th>Slug</th>
        <th>Section ID</th>
        <th>Abstract</th>
        <th>Mandatory</th>
    </tr>
    {%for s in sections%}
    <tr {%if s.abstract%}style="background:#ddd"{%endif%}>
        <td>
            {{s.name}}
        </td>
        <td>
            {{s.slug}}
        </td>
        <td>
            {{s.id}}
        </td>
        <td>
            {%if s.abstract%}x{%endif%}
        </td>
        <td>
            {%if s.mandatory%}x{%endif%}
        </td>
    </tr>
    {%endfor%}
</table>
<br>
<strong>Key:</strong>
<ul>
	<li><strong>Name:</strong> the name of the section as it will appear on the selection page</li>
<li><strong>Slug:</strong> a unique identifying string for a section</li>
<li><strong>Section ID:</strong> a unique identifying number for a section</li>
<li><strong>Abstract: </strong> Signifies that this section has no content of its own but is a container section.  A mandatory section contains all the sections listed below it until the next mandatory section is defined.</li>
<li><strong>Mandatory:</strong> Signifies that this section will always appear in the output document.  This section (or any sections it contains, if it's an abstract section) will be listed on the selection page but it will not be possible to deselect it.</li>
</ul>
<a href="../sections/">Click here for a listing of sections in JSON format.</a>
<!--
<h1>Subsets defined for this document:</h1>
<table>
    <tr style="background:#ccc">
        <th>ID</th>
        <th>Slug</th>
    </tr>
    {%for s in subsets%}
    <tr>
        <td>
            {{s.id}}
        </td>
        <td>
            {{s.name}}
        </td>
        <td>
        </td>
    </tr>
    {%endfor%}
</table> -->

</body>
</html>
