<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Web Status — Buildbot 0.8.12 documentation</title>
<link rel="stylesheet" href="../_static/agogo.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.8.12',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="shortcut icon" href="../_static/buildbot.ico"/>
<link rel="top" title="Buildbot 0.8.12 documentation" href="../index.html" />
<link rel="up" title="Buildbot Development" href="index.html" />
<link rel="next" title="Master-Slave API" href="master-slave.html" />
<link rel="prev" title="File Formats" href="formats.html" />
</head>
<body role="document">
<div class="header-wrapper" role="banner">
<div class="header">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/header-text-transparent.png" alt="Logo"/>
</a></p>
<div class="headertitle"><a
href="../index.html">Buildbot 0.8.12 documentation</a></div>
<div class="rel" role="navigation" aria-label="related navigation">
<a href="formats.html" title="File Formats"
accesskey="P">previous</a> |
<a href="master-slave.html" title="Master-Slave API"
accesskey="N">next</a> |
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |
<a href="../genindex.html" title="General Index"
accesskey="I">index</a>
</div>
</div>
</div>
<div class="content-wrapper">
<div class="content">
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="web-status">
<h1>Web Status<a class="headerlink" href="#web-status" title="Permalink to this headline">¶</a></h1>
<div class="section" id="jinja-web-templates">
<span id="id1"></span><h2>Jinja Web Templates<a class="headerlink" href="#jinja-web-templates" title="Permalink to this headline">¶</a></h2>
<p>Buildbot uses Jinja2 to render its web interface. The authoritative source for
this templating engine is
<a class="reference external" href="http://jinja.pocoo.org/2/documentation/">its own documentation</a>,
of course, but a few notes are in order for those who are
making only minor modifications.</p>
<div class="section" id="whitespace">
<h3>Whitespace<a class="headerlink" href="#whitespace" title="Permalink to this headline">¶</a></h3>
<p>Jinja directives are enclosed in <code class="docutils literal"><span class="pre">{%</span> <span class="pre">..</span> <span class="pre">%}</span></code>, and sometimes also have
dashes. These dashes strip whitespace in the output. For example:</p>
<div class="highlight-none"><div class="highlight"><pre><span></span>{% for entry in entries %}
<li>{{ entry }}</li>
{% endfor %}
</pre></div>
</div>
<p>will produce output with too much whitespace:</p>
<div class="highlight-html"><div class="highlight"><pre><span></span><span class="p"><</span><span class="nt">li</span><span class="p">></span>pigs<span class="p"></</span><span class="nt">li</span><span class="p">></span>
<span class="p"><</span><span class="nt">li</span><span class="p">></span>cows<span class="p"></</span><span class="nt">li</span><span class="p">></span>
</pre></div>
</div>
<p>But adding the dashes will collapse that whitespace completely:</p>
<div class="highlight-none"><div class="highlight"><pre><span></span>{% for entry in entries -%}
<li>{{ entry }}</li>
{%- endfor %}
</pre></div>
</div>
<p>yields</p>
<div class="highlight-html"><div class="highlight"><pre><span></span><span class="p"><</span><span class="nt">li</span><span class="p">></span>pigs<span class="p"></</span><span class="nt">li</span><span class="p">><</span><span class="nt">li</span><span class="p">></span>cows<span class="p"></</span><span class="nt">li</span><span class="p">></span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="web-authorization-framework">
<span id="id2"></span><h2>Web Authorization Framework<a class="headerlink" href="#web-authorization-framework" title="Permalink to this headline">¶</a></h2>
<p>Whenever any part of the web framework wants to perform some action on the
buildmaster, it should check the user's authorization first.</p>
<p>Always check authorization twice: once to decide whether to show the option to
the user (link, button, form, whatever); and once before actually performing
the action.</p>
<p>To check whether to display the option, you'll usually want to pass an authz
object to the Jinja template in your <code class="xref py py-class docutils literal"><span class="pre">HtmlResource</span></code> subclass:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">content</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">req</span><span class="p">,</span> <span class="n">cxt</span><span class="p">):</span>
<span class="c1"># ...</span>
<span class="n">cxt</span><span class="p">[</span><span class="s1">'authz'</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">getAuthz</span><span class="p">(</span><span class="n">req</span><span class="p">)</span>
<span class="n">template</span> <span class="o">=</span> <span class="o">...</span>
<span class="k">return</span> <span class="n">template</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="o">**</span><span class="n">cxt</span><span class="p">)</span>
</pre></div>
</div>
<p>and then determine whether to advertise the action in the template:</p>
<div class="highlight-none"><div class="highlight"><pre><span></span>{{ if authz.advertiseAction('myNewTrick') }}
<form action="{{ myNewTrick_url }}"> ...
{{ endif }}
</pre></div>
</div>
<p>Actions can optionally require authentication, so use <code class="docutils literal"><span class="pre">needAuthForm</span></code> to
determine whether to require a 'username' and 'passwd' field in the generated
form. These fields are usually generated by <code class="xref py py-meth docutils literal"><span class="pre">authFormIfNeeded</span></code>:</p>
<div class="highlight-none"><div class="highlight"><pre><span></span>{{ authFormIfNeeded(authz, 'myNewTrick') }}
</pre></div>
</div>
<p>Once the POST request comes in, it's time to check authorization again.
This usually looks something like</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">res</span> <span class="o">=</span> <span class="k">yield</span> <span class="bp">self</span><span class="o">.</span><span class="n">getAuthz</span><span class="p">(</span><span class="n">req</span><span class="p">)</span><span class="o">.</span><span class="n">actionAllowed</span><span class="p">(</span><span class="s1">'myNewTrick'</span><span class="p">,</span> <span class="n">req</span><span class="p">,</span> <span class="n">someExtraArg</span><span class="p">)</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">res</span><span class="p">:</span>
<span class="n">defer</span><span class="o">.</span><span class="n">returnValue</span><span class="p">(</span><span class="n">Redirect</span><span class="p">(</span><span class="n">path_to_authfail</span><span class="p">(</span><span class="n">req</span><span class="p">)))</span>
<span class="k">return</span>
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">someExtraArg</span></code> is optional (it's handled with <code class="docutils literal"><span class="pre">*args</span></code>, so you can
have several if you want), and is given to the user's authorization function.
For example, a build-related action should pass the build status, so that the
user's authorization function could ensure that devs can only operate on their
own builds.</p>
<p>Note that <code class="docutils literal"><span class="pre">actionAllowed</span></code> returns a <code class="docutils literal"><span class="pre">Deferred</span></code> instance, so you must wait
for the <code class="docutils literal"><span class="pre">Deferred</span></code> and yield the <code class="docutils literal"><span class="pre">Redirect</span></code> instead of returning it.</p>
<p>The available actions are described in <a class="reference internal" href="../manual/cfg-statustargets.html#status-WebStatus" title="WebStatus"><code class="xref bb bb-status docutils literal"><span class="pre">WebStatus</span></code></a>.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sidebar">
<h3>Table Of Contents</h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Buildbot Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="../manual/index.html">Buildbot Manual</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Buildbot Development</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="master-overview.html">Master Organization</a></li>
<li class="toctree-l2"><a class="reference internal" href="definitions.html">Definitions</a></li>
<li class="toctree-l2"><a class="reference internal" href="style.html">Buildbot Coding Style</a></li>
<li class="toctree-l2"><a class="reference internal" href="tests.html">Buildbot's Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="config.html">Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="utils.html">Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="database.html">Database</a></li>
<li class="toctree-l2"><a class="reference internal" href="results.html">Build Result Codes</a></li>
<li class="toctree-l2"><a class="reference internal" href="formats.html">File Formats</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Web Status</a><ul class="simple">
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="master-slave.html">Master-Slave API</a></li>
<li class="toctree-l2"><a class="reference internal" href="encodings.html">String Encodings</a></li>
<li class="toctree-l2"><a class="reference internal" href="metrics.html">Metrics</a></li>
<li class="toctree-l2"><a class="reference internal" href="plugins-publish.html">How to package Buildbot plugins</a></li>
<li class="toctree-l2"><a class="reference internal" href="classes.html">Classes</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../relnotes/index.html">Release Notes for Buildbot 0.8.12</a></li>
</ul>
<div role="search">
<h3 style="margin-top: 1.5em;">Search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
<div class="footer-wrapper">
<div class="footer">
<div class="left">
<div role="navigation" aria-label="related navigaton">
<a href="formats.html" title="File Formats"
>previous</a> |
<a href="master-slave.html" title="Master-Slave API"
>next</a> |
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |
<a href="../genindex.html" title="General Index"
>index</a>
</div>
<div role="note" aria-label="source link">
<br/>
<a href="../_sources/developer/webstatus.txt"
rel="nofollow">Show Source</a>
</div>
</div>
<div class="right">
<div class="footer" role="contentinfo">
© Copyright Buildbot Team Members.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.1.
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</body>
</html>
