hg.stevelosh.com > docs.stevelosh.com

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8"/>
        <title>Result Maps / Red Tape</title>
        <link rel="stylesheet" href="../_dmedia/tango.css"/>
        <link rel="stylesheet/less" type="text/css" href="../_dmedia/style.less"/>
        <script src="../_dmedia/less.js" type="text/javascript">
        </script>
    </head>
    <body class="content">
        <div class="wrap">
            <header><h1><a href="..">Red Tape</a></h1></header>
                <div class="markdown">
<h1 id="result-maps"><a href="">Result Maps</a></h1><p>After you pass data through a form (or call a form without data) you'll get
a result map back.</p>
<p>This map contains a number of entries that describe the results of running the
cleaners on that data (or some placeholders when you run a form without data).
Let's look at each of the entries in detail.</p>
<p>Once you're done here, move on to the <a href="../initial-data/">initial data</a> guide.</p>
<div class="toc">
<ul>
<li><a href="#fresh">:fresh</a></li>
<li><a href="#valid">:valid</a></li>
<li><a href="#errors">:errors</a></li>
<li><a href="#data">:data</a></li>
<li><a href="#results">:results</a></li>
<li><a href="#arguments">:arguments</a></li>
</ul></div>
<h2 id="fresh">:fresh</h2>
<p>This will be <code>true</code> if this is a fresh form (i.e.: it was called without data),
and <code>false</code> otherwise.</p>
<h2 id="valid">:valid</h2>
<p>If the form was called without data, this will be <code>nil</code>.</p>
<p>Otherwise, if the form was called with data, and the data passed through all
cleaners without anything being thrown, this will be <code>true</code>.</p>
<p>Otherwise it will be <code>false.</code></p>
<p>This should be used to determine whether to trust the data from the form, or
whether to re-render it for the user (and display the errors).</p>
<h2 id="errors">:errors</h2>
<p>If the form was called with data and a cleaner threw an exception (or anything
else with Slingshot's <code>throw+</code>) then <code>:errors</code> will be a map of field keys to
whatever was thrown.  For example:</p>
<div class="codehilite"><pre><span class="p">(</span><span class="kd">defn </span><span class="nv">always-fail</span> <span class="p">[</span><span class="nv">x</span><span class="p">]</span>
  <span class="p">(</span><span class="nf">throw+</span> <span class="s">"Error!"</span><span class="p">))</span>

<span class="p">(</span><span class="nf">defform</span> <span class="nv">failing-form</span> <span class="p">{}</span>
  <span class="ss">:foo</span> <span class="p">[</span><span class="nv">always-fail</span><span class="p">]</span>
  <span class="ss">:bar</span> <span class="p">[])</span>

<span class="p">(</span><span class="nf">failing-form</span> <span class="p">{</span><span class="s">"foo"</span> <span class="s">"aaa"</span>
               <span class="s">"bar"</span> <span class="s">"bbb"</span><span class="p">})</span>
<span class="c1">; =&gt;</span>
<span class="p">{</span><span class="ss">:errors</span> <span class="p">{</span><span class="ss">:foo</span> <span class="s">"Error!"</span><span class="p">}</span>
 <span class="nv">...</span><span class="p">}</span>
</pre></div>


<p>Only fields that actually threw errors will have entries in the <code>:errors</code> map.</p>
<p>If any form-level cleaners threw an error, <code>:errors</code> will contain an entry for
<code>:red-tape/form</code>.  This will be a set of form-level errors (for the reasons
described in the previous section).</p>
<p>If no errors were thrown anywhere, <code>:errors</code> will be <code>nil</code>.</p>
<h2 id="data">:data</h2>
<p>The <code>:data</code> entry in the result map will contain the raw data that was passed
into the form, <em>before</em> it was run through the cleaners.</p>
<p>This is useful for re-rendering the form when there are errors.</p>
<p>TODO: give a full example here.</p>
<p>If this is the result map of a fresh form (a form that has been called without
form data), every entry in <code>:data</code> will be an empty string (or initial data,
which we'll discuss in the next chapter).</p>
<h2 id="results">:results</h2>
<p>The <code>:results</code> entry is a map of field keys to the values <em>after</em> they've been
passed through all the cleaners.  After you've checked that the form is valid by
looking at <code>:valid</code>, you should use the data in <code>:results</code> to do whatever you
need to do.</p>
<p>If this is a fresh form, or if any cleaners threw errors, <code>:results</code> will be
<code>nil</code>.</p>
<h2 id="arguments">:arguments</h2>
<p>The <code>:arguments</code> entry is a mapping of keywords to form arguments, which will be
discussed in a later chapter.</p>
                </div>
            <footer><p>Made and <a href="http://sjl.bitbucket.org/d/">documented</a> with love by <a href="http://stevelosh.com">Steve
Losh</a>.</p>
<p><br/><a id="rochester-made" href="http://rochestermade.com" title="Rochester Made"><img src="http://rochestermade.com/media/images/rochester-made-dark-on-light.png" alt="Rochester Made" title="Rochester Made"/></a></p></footer>
        </div>
    </body>
</html>
author	Steve Losh <steve@stevelosh.com>
date	Wed, 21 Jun 2023 15:21:12 -0400
parents	69831b3947d7
children	(none)