incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r818667 [4/18] - in /websites/staging/sling/trunk/content: ./ authentication/ documentation/ documentation/bundles/ documentation/development/ documentation/getting-started/ documentation/the-sling-engine/ documentation/the-sling-engine/aut...
Date Tue, 22 May 2012 09:41:27 GMT
Added: websites/staging/sling/trunk/content/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html (added)
+++ websites/staging/sling/trunk/content/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html Tue May 22 09:41:22 2012
@@ -0,0 +1,1018 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE- 2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+  <head>
+    <title>Apache Sling - Manipulating Content - The SlingPostServlet (servlets.post)</title>
+    <link rel="stylesheet" href="/css/site.css" type="text/css" media="all">
+    <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+  </head>
+  <body>
+    <div class="title">
+      <div class="logo">
+        <a href="http://sling.apache.org/site/index.html">
+          <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+        </a>
+      </div>
+      <div class="header">
+        <a href="http://www.apache.org/">
+          <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+        </a>
+      </div>
+    </div>
+    
+    <div class="menu"> 
+      <p><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials &amp; How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong>  <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</p>
+<iframe 
+    src="http://www.apache.org/ads/button.html"
+    style="border-width:0; float: left" frameborder="0" 
+    scrolling="no"
+    width="135" 
+    height="135">
+</iframe>
+    </div>
+    
+    <div class="main">
+      <div class="breadcrump" style="font-size: 80%;">
+        <a href="/">Home</a>&nbsp;&raquo&nbsp;<a href="/documentation.html">Documentation</a>&nbsp;&raquo&nbsp;<a href="/documentation/bundles.html">Bundles</a>
+      </div>
+      <h1>Manipulating Content - The SlingPostServlet (servlets.post)</h1>
+      <div class="toc">
+<ul>
+<li><a href="#multiple-ways-to-modify-content">Multiple Ways to Modify Content</a></li>
+<li><a href="#quickstart-creating-content">Quickstart: Creating Content</a></li>
+<li><a href="#preface-multipartform-data-posts">Preface: multipart/form-data POSTs</a></li>
+<li><a href="#slingpostservlet-operations">SlingPostServlet Operations</a><ul>
+<li><a href="#content-creation-or-modification">Content Creation or Modification</a><ul>
+<li><a href="#setting-property-values">Setting Property Values</a><ul>
+<li><a href="#controlling-content-updates-with-suffixes">Controlling Content Updates with @ Suffixes</a><ul>
+<li><a href="#typehint">@TypeHint</a></li>
+<li><a href="#usedefaultwhenmissing">@UseDefaultWhenMissing</a></li>
+<li><a href="#valuefrom">@ValueFrom</a></li>
+<li><a href="#movefrom">@MoveFrom</a></li>
+</ul>
+</li>
+<li><a href="#algorithm-for-node-name-creation">Algorithm for Node Name Creation</a></li>
+<li><a href="#response-status">Response Status</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="#content-removal">Content Removal</a><ul>
+<li><a href="#response-status_1">Response Status</a><ul>
+<li><a href="#deleting-multiple-items">Deleting Multiple Items</a><ul>
+<li><a href="#response-status_2">Response Status</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="#copying-content">Copying Content</a><ul>
+<li><a href="#response-status_3">Response Status</a><ul>
+<li><a href="#copying-multiple-items">Copying Multiple Items</a><ul>
+<li><a href="#response-status_4">Response Status</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="#moving-content">Moving Content</a><ul>
+<li><a href="#response-status_5">Response Status</a><ul>
+<li><a href="#moving-multiple-items">Moving Multiple Items</a><ul>
+<li><a href="#response-status_6">Response Status</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="#importing-content-structures">Importing Content Structures</a><ul>
+<li><a href="#response-status_7">Response Status</a></li>
+</ul>
+</li>
+<li><a href="#null-operation">Null Operation</a><ul>
+<li><a href="#response-status_8">Response Status</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="#special-parameters">Special Parameters</a><ul>
+<li><a href="#order">:order</a></li>
+<li><a href="#redirect">:redirect</a></li>
+<li><a href="#status">:status</a></li>
+</ul>
+</li>
+<li><a href="#response-format">Response format</a></li>
+<li><a href="#versionable-node-support">Versionable Node Support</a></li>
+<li><a href="#extending-the-slingpostservlet">Extending the SlingPostServlet</a><ul>
+<li><a href="#additional-post-operations">Additional POST operations</a></li>
+<li><a href="#slingpostprocessor">SlingPostProcessor</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<h2 id="multiple-ways-to-modify-content">Multiple Ways to Modify Content</h2>
+<p>As always in life there is more than one way to do it. So to modify content in a JCR repository underlying Sling, you have multiple options, two of which are WebDAV and the Sling default POST Servlet also called the <em>SlingPostServlet</em>. This page is about how you can modify - create, modify, copy, move, delete, import - content through the <em>SlingPostServlet</em>. In addition it also explains how to extend the SlingPostServlet with new operations.</p>
+<p>What is Content anyway ? In the following discussion, I use the terms <em>Content</em> and <em>Item</em> interchangeably. With <em>Content</em> I just mean some data to be stored in the JCR repository to be later used as the basis for some presentation. In this sense <em>Content</em> is a rather conceptual term. <em>Item</em> is the name of the parent interface of the JCR <em>Node</em> and <em>Property</em> interfaces. When speaking of <em>Items</em> we mean some actual data stored in the repository ignoring whether the data is actually stored as a <em>Node</em> with child nodes and properties or just a single <em>Property</em>.</p>
+<h2 id="quickstart-creating-content">Quickstart: Creating Content</h2>
+<p>To create content you simply send an HTTP POST request using the path of the node to store the content in and include the actual content as request parameters. So one possibility to do just that is by having an HTML Form like the following:</p>
+<div class="codehilite"><pre><span class="nt">&lt;form</span> <span class="na">method=</span><span class="s">&quot;POST&quot;</span> <span class="na">action=</span><span class="s">&quot;http://host/some/new/content&quot;</span> <span class="na">enctype=</span><span class="s">&quot;multipart/form-data&quot;</span><span class="nt">&gt;</span>
+   <span class="nt">&lt;input</span> <span class="na">type=</span><span class="s">&quot;text&quot;</span> <span class="na">name=</span><span class="s">&quot;title&quot;</span> <span class="na">value=</span><span class="s">&quot;&quot;</span> <span class="nt">/&gt;</span>
+   <span class="nt">&lt;input</span> <span class="na">type=</span><span class="s">&quot;text&quot;</span> <span class="na">name=</span><span class="s">&quot;text&quot;</span> <span class="na">value=</span><span class="s">&quot;&quot;</span> <span class="nt">/&gt;</span>
+<span class="nt">&lt;/form&gt;</span>
+</pre></div>
+
+
+<p>This simple form will set the <code>title</code> and <code>text</code> properties on a node at <code>/some/new/content</code>. If this node does not exist it is just created otherwise the existing content would be modified.</p>
+<p>Similarly you can do this using the <code>curl</code> command line tool:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">curl</span> <span class="o">-</span><span class="n">Ftitle</span><span class="o">=</span><span class="s">&quot;some title text&quot;</span> <span class="o">-</span><span class="n">Ftext</span><span class="o">=</span><span class="s">&quot;some body text content&quot;</span> <span class="n">http:</span><span class="sr">//</span><span class="n">host</span><span class="sr">/some/</span><span class="k">new</span><span class="o">/</span><span class="n">content</span>
+</pre></div>
+
+
+<p>You might want to use a specific JCR node type for a newly created node. This is possibly by simply setting a <code>jcr:primaryType</code> property on the request, e.g.</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">curl</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;jcr:primaryType=nt:unstructured&quot;</span> <span class="o">-</span><span class="n">Ftitle</span><span class="o">=</span><span class="s">&quot;some title text&quot;</span> <span class="o">-</span><span class="n">Ftext</span><span class="o">=</span><span class="s">&quot;some body text content&quot;</span> <span class="n">http:</span><span class="sr">//</span><span class="n">host</span><span class="sr">/some/</span><span class="k">new</span><span class="o">/</span><span class="n">content</span>
+</pre></div>
+
+
+<p>Similary you may assing JCR mixin node types using the <code>jcr:mixinTypes</code> property and a Sling resource type using the <code>sling:resourceType</code> property. For example:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">curl</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;sling:resourceType=sling:sample&quot;</span> <span class="o">-</span><span class="n">Ftitle</span><span class="o">=</span><span class="s">&quot;some title text&quot;</span> <span class="o">-</span><span class="n">Ftext</span><span class="o">=</span><span class="s">&quot;some body text content&quot;</span> <span class="n">http:</span><span class="sr">//</span><span class="n">host</span><span class="sr">/some/</span><span class="k">new</span><span class="o">/</span><span class="n">content</span>
+</pre></div>
+
+
+<h2 id="preface-multipartform-data-posts">Preface: multipart/form-data POSTs</h2>
+<p>Sometimes you might want to have the content modifications applied in a certain order. This is particularly interesting if you use fields to create child nodes and if you want to stipulate a certain child node order based on the form fields.</p>
+<p>In this case ensure you are submitting the POST request using <code>multipart/form-data</code> encoding. This preserves the order of parameter application according to the original HTML form. To this avail ensure to always include the <code>enctype="multipart/form-data"</code> attribute with the <code>&lt;form&gt;</code> tag.</p>
+<p>This support requires Sling Engine 2.1.0 and the Sling Default Post Servlet 2.0.6.</p>
+<h2 id="slingpostservlet-operations">SlingPostServlet Operations</h2>
+<p>The SlingPostServlet is actually just a frontend to the actual operations. To select the actual operation to execute, the <code>:operation</code> request parameter is used. Out of the box, the SlingPostServlet supports the following operations:</p>
+<ul>
+<li>property not set or empty -- Create new content or modify existing content</li>
+<li><code>delete</code> -- Remove existing content</li>
+<li><code>move</code> -- Move existing content to a new location</li>
+<li><code>copy</code> -- Copy existing content to a new location</li>
+<li><code>import</code> -- Import content structures from JSON/XML/Zip</li>
+<li><code>nop</code> -- Explicitly requests to do nothing and just sets the response status</li>
+<li><code>checkin</code> - Check in a versionable node</li>
+<li><code>checkout</code> - Check out a versionable node</li>
+</ul>
+<p>All these operations always operate on the resource of the request as returned by <code>SlingHttpServletRequest.getResource()</code>. Some operations require additional parameters to be set to operate completely.</p>
+<p>Please note that operations are mutually exclusive. For a single POST request only one operation may be executed. Operations also only consume the request parameters as described below. Any excess parameters are silently ignored.</p>
+<p>{note:title=Automated Tests}
+Note that the <code>launchpad/testing</code> module contains a number of <a href="">integration tests</a> for the SlingPostServlet. Most of these tests are fairly readable, and can be used to find out more details about the servlet's behavior.
+{note}</p>
+<p>{note:title=Trailing star in the :applyTo parameter}
+This applies to operations that use this parameter, since version 2.1.2 of the <em>org.apache.sling.servlets.post</em> bundle: If the last segment of the <code>:applyTo</code> value is '*' then the operation applies to all the children of the resolved parent resource. This can be used to act on all the children 
+of a resource without having to specify the path of each individual child resource.
+{note}</p>
+<h3 id="content-creation-or-modification">Content Creation or Modification</h3>
+<p>The simplest and most common use case, probably, is content creation and modification. We already saw an example above in the quickstart section. In this section we elaborate more on the concrete stuff.</p>
+<p>First, the request URL indicates the actual repository node to be handled. If the URL addresses an existing node, the request parameters just provide values for the properties to be set on the existing node.</p>
+<p>If the resource of the request is a synthetic resource, e.g. <code>NonExistingResource</code> or <code>StarResource</code>, a new item is created. The path (including name) of the item to be created is derived from the resource path:</p>
+<ul>
+<li>If the resource path ends with a <code>/*</code> or <code>/</code> the name of the item is automatically created using a name creation algorithm taking into account various request parameters.</li>
+<li>Otherwise the resource path is used as the path and name of the new item.</li>
+</ul>
+<p>In both cases the path may still include selectors and extensions, which are cut off the path before finding out, what to do.</p>
+<p>To illustrate this algorithm, lets look at some examples (and check the <code>[PostServletCreateTest]()</code> in case of doubt):</p>
+<table>
+<thead>
+<tr>
+<th>Resource Path</th>
+<th>Item path</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>/content/new</code></td>
+<td><code>/content/new</code></td>
+</tr>
+<tr>
+<td><code>/content/new.html</code></td>
+<td><code>/content/new</code></td>
+</tr>
+<tr>
+<td><code>/content/new.print.a4.html</code></td>
+<td><code>/content/new</code></td>
+</tr>
+<tr>
+<td><code>/content/</code></td>
+<td><code>/content/xxx</code> where <code>xxx</code> is a generated name</td>
+</tr>
+<tr>
+<td><code>/content/*</code></td>
+<td><code>/content/xxx</code> where <code>xxx</code> is a generated name</td>
+</tr>
+<tr>
+<td><code>/content/*.html</code></td>
+<td><code>/content/xxx</code> where <code>xxx</code> is a generated name</td>
+</tr>
+<tr>
+<td><code>/content/*.print.a4.html</code></td>
+<td><code>/content/xxx</code> where <code>xxx</code> is a generated name</td>
+</tr>
+</tbody>
+</table>
+<h5 id="setting-property-values">Setting Property Values</h5>
+<p>Setting property values is as simple as just adding a request parameter whose name is the name of the property to be set and whose value is the value to be assigned to the property. We already saw how to do this in the quick start examples above.</p>
+<p>Here is another example show a simple HTML form to create a new node with an automatically created name:</p>
+<p>{code:html}
+<form method="POST" action="/content/page/first" enctype="multipart/form-data">
+    <input type="text" name="title" />
+    <input type="text" name="text" />
+    <input type="Submit" />
+</form></p>
+<div class="codehilite"><pre><span class="n">If</span> <span class="n">this</span> <span class="n">form</span> <span class="n">is</span> <span class="n">submitted</span> <span class="n">with</span> <span class="n">_title_</span> <span class="ow">and</span> <span class="n">_This</span> <span class="n">is</span> <span class="n">some</span> <span class="n">Text_</span> <span class="n">as</span> <span class="nb">values</span> <span class="k">for</span> <span class="n">the</span>  <span class="ow">and</span>  <span class="n">fields</span><span class="p">,</span> <span class="n">resp</span><span class="o">.</span><span class="p">,</span> <span class="n">a</span> <span class="k">new</span> <span class="n">node</span> <span class="n">is</span> <span class="n">created</span> <span class="n">at</span> <span class="n">the</span> <span class="n">path</span>  <span class="ow">and</span> <span class="n">the</span>  <span class="ow">and</span>  <span class="n">properties</span> <span class
 ="n">set</span> <span class="n">to</span> <span class="n">the</span> <span class="n">respective</span> <span class="n">field</span> <span class="nb">values</span><span class="o">.</span> <span class="n">If</span> <span class="n">a</span> <span class="n">node</span> <span class="n">at</span>  <span class="n">already</span> <span class="n">existed</span> <span class="n">before</span> <span class="n">submitting</span> <span class="n">the</span> <span class="n">form</span><span class="p">,</span> <span class="n">the</span>  <span class="ow">and</span>  <span class="n">properties</span> <span class="n">are</span> <span class="n">just</span> <span class="n">updated</span> <span class="n">to</span> <span class="n">the</span> <span class="k">new</span> <span class="nb">values</span> <span class="n">from</span> <span class="n">the</span> <span class="n">form</span> <span class="n">fields</span><span class="o">.</span>
+
+<span class="n">If</span> <span class="n">a</span> <span class="n">parameter</span> <span class="n">has</span> <span class="n">multiple</span> <span class="nb">values</span><span class="p">,</span> <span class="n">the</span> <span class="n">respective</span> <span class="n">property</span> <span class="n">will</span> <span class="n">be</span> <span class="n">created</span> <span class="n">as</span> <span class="n">a</span> <span class="n">multi</span><span class="o">-</span><span class="n">value</span> <span class="n">property</span><span class="o">.</span> <span class="n">So</span> <span class="k">for</span> <span class="n">example</span> <span class="n">the</span> <span class="n">command</span> <span class="n">line:</span>
+
+<span class="p">{</span><span class="n">noformat</span><span class="p">}</span>
+<span class="nv">$</span> <span class="nv">curl</span> <span class="o">-</span><span class="n">Fmulti</span><span class="o">=</span><span class="n">one</span> <span class="o">-</span><span class="n">Fmulti</span><span class="o">=</span><span class="n">two</span> <span class="n">http:</span><span class="sr">//</span><span class="n">host</span><span class="sr">/content/</span><span class="n">page</span>
+<span class="p">{</span><span class="n">noformat</span><span class="p">}</span>
+
+<span class="n">Would</span> <span class="n">assign</span> <span class="n">the</span>  <span class="n">property</span> <span class="n">the</span> <span class="n">value</span> <span class="n">_</span><span class="p">[</span> <span class="s">&quot;one&quot;</span><span class="p">,</span> <span class="s">&quot;two&quot;</span> <span class="p">]</span><span class="n">_</span><span class="o">.</span>
+
+<span class="n">This</span> <span class="n">is</span> <span class="n">pretty</span> <span class="n">much</span> <span class="n">all</span> <span class="n">there</span> <span class="n">is</span> <span class="n">to</span> <span class="n">know</span> <span class="n">about</span> <span class="n">creating</span> <span class="ow">and</span> <span class="n">modifying</span> <span class="n">content</span><span class="o">.</span> <span class="n">The</span> <span class="n">following</span> <span class="n">sections</span> <span class="n">will</span> <span class="n">now</span> <span class="n">introduce</span> <span class="n">more</span> <span class="n">functionality</span> <span class="n">which</span> <span class="n">help</span> <span class="n">you</span> <span class="n">with</span> <span class="n">more</span> <span class="n">fine</span><span class="o">-</span><span class="n">grained</span> <span class="n">control</span> <span class="n">in</span> <span class="n">your</span> <span class=
 "n">content</span> <span class="n">management</span> <span class="n">application</span><span class="o">.</span>
+
+<span class="n">h5</span><span class="o">.</span> <span class="n">File</span> <span class="n">Uploads</span>
+
+<span class="n">File</span> <span class="n">uploads</span> <span class="n">are</span> <span class="n">typically</span> <span class="n">done</span> <span class="n">using</span> <span class="n">the</span>  <span class="n">element</span> <span class="n">of</span> <span class="n">an</span> <span class="n">HTML</span> <span class="n">form</span> <span class="ow">and</span> <span class="n">ensuring</span> <span class="n">the</span> <span class="n">correct</span> <span class="n">form</span> <span class="n">encoding</span><span class="o">.</span> <span class="n">The</span> <span class="n">SlingPostServlet</span> <span class="n">handles</span> <span class="n">uploaded</span> <span class="n">files</span> <span class="n">specially</span><span class="p">,</span> <span class="n">in</span> <span class="n">that</span> <span class="n">the</span> <span class="n">file</span> <span class="n">data</span> <span class="n">is</span> <span class="ow">not</span> <span class="n">simply</span> <span c
 lass="n">written</span> <span class="n">into</span> <span class="n">a</span> <span class="n">property</span><span class="p">,</span> <span class="n">but</span> <span class="n">a</span> <span class="n">node</span> <span class="n">is</span> <span class="n">actually</span> <span class="n">created</span> <span class="n">with</span> <span class="n">three</span> <span class="n">properties:</span>
+
+   <span class="o">*</span>  <span class="o">--</span> <span class="n">The</span> <span class="n">actual</span> <span class="n">file</span> <span class="n">contents</span>
+   <span class="o">*</span>  <span class="o">--</span> <span class="n">The</span> <span class="nb">time</span> <span class="n">stamp</span> <span class="n">of</span> <span class="n">processing</span> <span class="n">the</span> <span class="n">uploaded</span> <span class="n">file</span>
+   <span class="o">*</span>  <span class="o">--</span> <span class="n">The</span> <span class="n">MIME</span> <span class="n">type</span> <span class="n">from</span> <span class="n">the</span> <span class="n">original</span> <span class="n">file</span> <span class="n">submission</span> <span class="p">(</span><span class="k">if</span> <span class="n">contained</span> <span class="n">in</span> <span class="n">the</span> <span class="n">file</span> <span class="n">body</span> <span class="n">part</span><span class="p">)</span> <span class="ow">or</span> <span class="n">derived</span> <span class="n">from</span> <span class="n">the</span> <span class="n">original</span> <span class="n">file</span> <span class="n">name</span>
+
+<span class="n">The</span> <span class="n">name</span> <span class="n">of</span> <span class="n">the</span> <span class="n">node</span> <span class="n">is</span> <span class="n">either</span> <span class="n">taken</span> <span class="n">from</span> <span class="n">the</span> <span class="n">parameter</span> <span class="n">name</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">the</span> <span class="n">name</span> <span class="n">is</span>  <span class="n">from</span> <span class="n">the</span> <span class="n">name</span> <span class="n">of</span> <span class="n">the</span> <span class="n">uploaded</span> <span class="n">file</span><span class="o">.</span>
+
+<span class="n">The</span> <span class="n">primary</span> <span class="n">node</span> <span class="n">type</span> <span class="n">of</span> <span class="n">the</span> <span class="n">uploaded</span> <span class="n">file</span> <span class="n">is</span> <span class="n">selected</span> <span class="n">using</span> <span class="n">the</span> <span class="n">following</span> <span class="n">algorithm:</span>
+
+   <span class="c1"># If a  suffixed parameter (see below for a description) is present check whether the value is a known non-mixin node type. If so, the node is created with this primary node type.</span>
+   <span class="c1"># If a  suffixed parameter is not present or the value does not denote an existing non-mixin node type, the node will be created as an  node if the parent node is of type . Otherwise the node will be created with primary node type .</span>
+
+<span class="n">If</span> <span class="n">the</span> <span class="n">node</span> <span class="n">to</span> <span class="n">be</span> <span class="n">created</span> <span class="n">is</span> <span class="p">,</span> <span class="n">the</span> <span class="n">actual</span> <span class="n">file</span> <span class="n">data</span> <span class="n">will</span> <span class="n">really</span> <span class="n">be</span> <span class="n">stored</span> <span class="n">in</span> <span class="n">the</span>  <span class="n">child</span> <span class="n">node</span> <span class="n">of</span> <span class="n">the</span> <span class="k">new</span>  <span class="n">node</span> <span class="n">whose</span> <span class="n">primary</span> <span class="n">node</span> <span class="n">type</span> <span class="n">is</span> <span class="k">then</span> <span class="n">set</span> <span class="n">as</span> <span class="o">.</span>
+
+<span class="n">Example</span> <span class="mi">1</span><span class="p">:</span> <span class="n">Upload</span> <span class="n">an</span> <span class="n">image</span> <span class="n">to</span> <span class="n">a</span> <span class="n">node</span> <span class="n">named</span>  <span class="n">below</span> <span class="p">:</span>
+
+<span class="p">{</span><span class="n">code:html</span><span class="p">}</span>
+<span class="o">&lt;</span><span class="n">form</span> <span class="n">method</span><span class="o">=</span><span class="s">&quot;POST&quot;</span> <span class="n">action</span><span class="o">=</span><span class="s">&quot;/content/page&quot;</span> <span class="n">enctype</span><span class="o">=</span><span class="s">&quot;multipart/form-data&quot;</span><span class="o">&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;file&quot;</span> <span class="n">name</span><span class="o">=</span><span class="s">&quot;image&quot;</span> <span class="o">/&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;Submit&quot;</span> <span class="o">/&gt;</span>
+<span class="sr">&lt;/form&gt;</span>
+</pre></div>
+
+
+<p>Example 2: Upload a file as a node of type <code>nt:file</code> below <code>/content/folder</code>:</p>
+<p>{code:html}
+<form method="POST" action="/content/page" enctype="multipart/form-data">
+    <input type="file" name="*" />
+    <input type="hidden" name="*@TypeHint" value="nt:file" />
+    <input type="Submit" />
+</form></p>
+<div class="codehilite"><pre><span class="n">Assuming</span> <span class="n">the</span> <span class="n">user</span> <span class="n">selected</span> <span class="n">a</span> <span class="n">file</span> <span class="n">named</span>  <span class="n">the</span> <span class="n">uploaded</span> <span class="n">file</span> <span class="n">would</span> <span class="n">be</span> <span class="n">stored</span> <span class="n">in</span> <span class="n">an</span>  <span class="n">node</span> <span class="n">at</span> <span class="o">.</span>
+
+<span class="n">h5</span><span class="o">.</span> <span class="n">Date</span> <span class="n">properties</span>
+
+<span class="n">Parameters</span> <span class="n">providing</span> <span class="n">date</span><span class="sr">/time values to be stored in JCR properties of type _Date_ require special handling. The problem is that there are a number of formats to represent such date/</span><span class="nb">time</span> <span class="nb">values</span><span class="o">.</span> <span class="n">To</span> <span class="n">account</span> <span class="k">for</span> <span class="n">this</span> <span class="nb">open</span><span class="o">-</span><span class="n">ended</span> <span class="n">list</span> <span class="n">of</span> <span class="n">formats</span><span class="p">,</span> <span class="n">the</span> <span class="n">Sling</span> <span class="n">Post</span> <span class="n">Servlet</span> <span class="n">supports</span> <span class="n">configurability</span> <span class="n">of</span> <span class="n">the</span> <span class="n">process</span> <span class="n">of</span> <span class="n">parsing</span> 
 <span class="n">strings</span> <span class="n">into</span>  <span class="n">objects</span><span class="o">.</span>
+
+<span class="n">The</span> <span class="n">Sling</span> <span class="n">Post</span> <span class="n">Servlet</span> <span class="n">configuration</span> <span class="n">property</span>  <span class="n">takes</span> <span class="n">a</span> <span class="n">list</span> <span class="n">of</span> <span class="nb">format</span> <span class="n">strings</span> <span class="n">which</span> <span class="n">are</span> <span class="n">used</span> <span class="n">to</span> <span class="n">setup</span>  <span class="n">instances</span> <span class="k">for</span> <span class="n">parsing</span> <span class="n">date</span><span class="o">/</span><span class="nb">time</span> <span class="n">string</span> <span class="n">representations</span><span class="o">.</span> <span class="n">A</span> <span class="n">special</span> <span class="nb">format</span> <span class="n">string</span>  <span class="n">is</span> <span class="n">supported</span> <span class="n">to</span> <span class="n">indicate</s
 pan> <span class="n">the</span> <span class="n">string</span> <span class="n">to</span> <span class="n">be</span> <span class="n">parsed</span> <span class="n">as</span> <span class="n">a</span> <span class="n">JCR</span> <span class="n">standard</span> <span class="n">string</span> <span class="n">representation</span> <span class="n">of</span> <span class="n">a</span> <span class="n">_Date_</span> <span class="n">property</span><span class="o">.</span>
+
+<span class="n">The</span> <span class="n">default</span> <span class="n">list</span> <span class="n">of</span> <span class="n">configured</span> <span class="n">date</span><span class="o">/</span><span class="nb">time</span> <span class="n">parse</span> <span class="n">pattern</span> <span class="n">is</span> <span class="p">:</span>
+
+  <span class="o">*</span> <span class="n">EEE</span> <span class="n">MMM</span> <span class="n">dd</span> <span class="n">yyyy</span> <span class="n">HH:mm:ss</span> <span class="s">&#39;GMT&#39;</span><span class="n">Z</span>
+  <span class="o">*</span> <span class="n">ISO8601</span>
+  <span class="o">*</span> <span class="n">yyyy</span><span class="o">-</span><span class="n">MM</span><span class="o">-</span><span class="n">dd</span><span class="s">&#39;T&#39;</span><span class="n">HH:mm:ss</span><span class="o">.</span><span class="n">SSSZ</span>
+  <span class="o">*</span> <span class="n">yyyy</span><span class="o">-</span><span class="n">MM</span><span class="o">-</span><span class="n">dd</span><span class="s">&#39;T&#39;</span><span class="n">HH:mm:ss</span>
+  <span class="o">*</span> <span class="n">yyyy</span><span class="o">-</span><span class="n">MM</span><span class="o">-</span><span class="n">dd</span>
+  <span class="o">*</span> <span class="n">dd</span><span class="o">.</span><span class="n">MM</span><span class="o">.</span><span class="n">yyyy</span> <span class="n">HH:mm:ss</span>
+  <span class="o">*</span> <span class="n">dd</span><span class="o">.</span><span class="n">MM</span><span class="o">.</span><span class="n">yyyy</span>
+
+<span class="n">Any</span> <span class="n">date</span><span class="o">/</span><span class="nb">time</span> <span class="n">string</span> <span class="n">parameter</span> <span class="n">supplied</span> <span class="n">is</span> <span class="n">subject</span> <span class="n">to</span> <span class="n">the</span> <span class="n">patterns</span> <span class="n">in</span> <span class="n">the</span> <span class="n">configured</span> <span class="n">order</span><span class="o">.</span> <span class="n">The</span> <span class="n">first</span> <span class="n">pattern</span> <span class="n">accepting</span> <span class="n">the</span> <span class="n">string</span> <span class="ow">and</span> <span class="n">parsing</span> <span class="n">it</span> <span class="n">into</span> <span class="n">a</span>  <span class="o">--</span> <span class="ow">and</span> <span class="n">thus</span> <span class="n">a</span>  <span class="o">--</span> <span class="n">object</span> <span class="n">is</span>
  <span class="n">used</span><span class="o">.</span> <span class="n">Therefore</span> <span class="n">this</span> <span class="n">list</span> <span class="n">is</span> <span class="n">best</span> <span class="n">ordered</span> <span class="n">in</span> <span class="n">a</span> <span class="n">most</span><span class="o">-</span><span class="n">stringent</span> <span class="n">to</span> <span class="n">least</span><span class="o">-</span><span class="n">stringent</span> <span class="n">order</span><span class="o">.</span>
+
+<span class="n">h5</span><span class="o">.</span> <span class="n">Omitting</span> <span class="n">Some</span> <span class="n">Parameters</span>
+
+<span class="n">There</span> <span class="n">may</span> <span class="n">be</span> <span class="nb">times</span><span class="p">,</span> <span class="n">that</span> <span class="n">you</span> <span class="n">have</span> <span class="n">forms</span> <span class="n">which</span> <span class="n">contain</span> <span class="n">a</span> <span class="n">lot</span> <span class="n">of</span> <span class="n">fields</span><span class="p">,</span> <span class="n">which</span> <span class="n">you</span> <span class="k">do</span> <span class="ow">not</span> <span class="n">want</span> <span class="n">to</span> <span class="n">actually</span> <span class="n">store</span> <span class="n">in</span> <span class="n">content</span><span class="o">.</span> <span class="n">Such</span> <span class="n">forms</span> <span class="n">usually</span> <span class="n">are</span> <span class="n">created</span> <span class="n">using</span> <span class="n">some</span> <span class="n">client</span><span class
 ="o">-</span><span class="n">side</span> <span class="n">GUI</span> <span class="n">library</span> <span class="n">which</span> <span class="n">uses</span> <span class="n">the</span> <span class="n">fields</span> <span class="k">for</span> <span class="n">its</span> <span class="n">own</span> <span class="n">purposes</span><span class="o">.</span> <span class="n">To</span> <span class="n">be</span> <span class="n">able</span> <span class="n">to</span> <span class="n">easily</span> <span class="n">differentiate</span> <span class="n">between</span> <span class="n">real</span> <span class="n">content</span> <span class="n">to</span> <span class="n">be</span> <span class="n">actually</span> <span class="n">stored</span> <span class="ow">and</span> <span class="n">such</span> <span class="n">control</span> <span class="n">parameters</span><span class="p">,</span> <span class="n">you</span> <span class="n">may</span> <span class="n">prefix</span> <span class="n">the</span> <span 
 class="n">names</span> <span class="n">of</span> <span class="n">the</span> <span class="n">fields</span> <span class="n">destined</span> <span class="k">for</span> <span class="n">content</span> <span class="n">with</span> <span class="n">a</span> <span class="n">dot</span><span class="o">-</span><span class="n">slash</span> <span class="p">()</span><span class="o">.</span>
+
+<span class="n">As</span> <span class="n">soon</span> <span class="n">as</span> <span class="n">the</span> <span class="n">SlingPostServlet</span> <span class="n">encounters</span> <span class="n">parameters</span> <span class="n">prefixed</span> <span class="n">with</span> <span class="n">dot</span><span class="o">-</span><span class="n">slash</span><span class="p">,</span> <span class="n">only</span> <span class="n">those</span> <span class="n">parameters</span> <span class="n">are</span> <span class="n">considered</span> <span class="k">for</span> <span class="n">content</span> <span class="n">updates</span> <span class="k">while</span> <span class="n">all</span> <span class="n">other</span> <span class="n">parameters</span> <span class="ow">not</span> <span class="n">prefixed</span> <span class="n">are</span> <span class="n">just</span> <span class="n">ignored</span><span class="o">.</span> <span class="n">In</span> <span class="n">addition</span> <span class="n">to</spa
 n> <span class="n">dot</span><span class="o">-</span><span class="n">slash</span> <span class="n">prefixed</span> <span class="n">parameters</span><span class="p">,</span> <span class="n">also</span> <span class="n">parameters</span> <span class="n">prefixed</span> <span class="n">with</span> <span class="n">dot</span><span class="o">-</span><span class="n">dot</span><span class="o">-</span><span class="n">slash</span> <span class="p">()</span> <span class="ow">and</span> <span class="n">slash</span> <span class="p">()</span> <span class="n">are</span> <span class="n">considered</span> <span class="n">in</span> <span class="n">this</span> <span class="n">situation</span><span class="o">.</span>
+
+<span class="n">For</span> <span class="n">example</span><span class="p">,</span> <span class="n">the</span> <span class="n">following</span> <span class="n">form</span> <span class="n">only</span> <span class="n">uses</span> <span class="n">the</span> <span class="n">first</span> <span class="n">two</span> <span class="n">fields</span> <span class="k">for</span> <span class="n">content</span> <span class="n">update</span> <span class="ow">and</span> <span class="n">ignores</span> <span class="n">the</span> <span class="n">rest:</span>
+
+<span class="p">{</span><span class="n">code:html</span><span class="p">}</span>
+<span class="o">&lt;</span><span class="n">form</span> <span class="n">method</span><span class="o">=</span><span class="s">&quot;POST&quot;</span> <span class="n">action</span><span class="o">=</span><span class="s">&quot;/content/page/first&quot;</span> <span class="n">enctype</span><span class="o">=</span><span class="s">&quot;multipart/form-data&quot;</span><span class="o">&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;text&quot;</span> <span class="n">name</span><span class="o">=</span><span class="s">&quot;./title&quot;</span> <span class="o">/&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;text&quot;</span> <span class="n">name</span><span class="o">=</span><span class="s">&quot;../first/text&quot;</span> <span class="o">/&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;hidden&quot;</span> <span class="n">name</span><span class="o">=</span><span class="s">&quot;control0&quot;</span> <span class="o">/&gt;&lt;!--</span> <span class="n">ignored</span> <span class="o">--&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;hidden&quot;</span> <span class="n">name</span><span class="o">=</span><span class="s">&quot;control1&quot;</span> <span class="o">/&gt;&lt;!--</span> <span class="n">ignored</span> <span class="o">--&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;Submit&quot;</span> <span class="o">/&gt;</span>
+<span class="sr">&lt;/form&gt;</span>
+</pre></div>
+
+
+<p>Because the SlingPostServlet encounters the <code>./title</code> parameter, only parameters prefixed with dot-slash, dot-dot-slash and slash are considered for content update. In this case this would <code>./title</code> and <code>../first/text</code> while <code>control0</code> and <code>control1</code> are not prefixed and thus ignored.</p>
+<p>Background: The name of the parameters used for content update are actually intended to be relative path names of the properties to modify. So in effect using the field name <code>text</code> is equivalent to <code>./text</code> -- dot-slash meaning relative to the current node identified by the <code>action</code> attribute value for <code>form</code> tag -- or <code>../first/text</code> if <code>first</code> is the name of the node to modify -- dot-dot-slash meaning relative to the parent node of the node identified by the <code>action</code> attribute value of the <code>form</code> tag.</p>
+<p>In addition to the mechanism explained here, the following parameters are also ignored:</p>
+<ul>
+<li>Parameters whose name start with a colon (<code>:</code>) are always ignored by the SlingPostServlet with respect to content update. The reason is that the prefixing colon is intended as a marker for SlingPostServlet control parameters.</li>
+<li>The <code>\*charset\*</code> request parameter is also never written back because this parameter is used to convey the character encoding used to transport the request parameters.</li>
+<li>Request parameters matching a regular expression supplied with the <code>servlet.post.ignorePattern</code> configuration parameter are also ignored. By default this pattern is <code>j*.*</code> thus ignoring any request parameters with the prefix <code>j*</code> such as <code>j_username</code>. Those request parameters are generally used for authentication purposes and may hit the Sling POST Servlet in some situations.</li>
+</ul>
+<h5 id="controlling-content-updates-with-suffixes">Controlling Content Updates with <code>@</code> Suffixes</h5>
+<p>Generally just creating forms with parameters and their values suffices it completely. Sometimes, though, you want to have more control on how the parameter values are actually stored in the properties. For example, you want to set a property to a default value if the user did provide an actual value. Or you might want to store a parameter explicitly with a given data type, such as numeric, boolean etc.</p>
+<p>The SlingPostServlet provides such property control in the form of <code>@</code> suffixed parameters, which are now presented.</p>
+<p>The <code>@</code> suffixed parameters are not used on their own but always in conjunction with a plain parameter. The part of the parameter name before the <code>@</code> suffix is used in this case for correlation and must match exactly the name of the parameter to which the <code>@</code> suffixed parameter belongs.</p>
+<p>For example, the parameter <code>width@TypeHint</code> applies to the <code>width</code> parameter and the <code>./height@TypeHint</code> parameter applies to the <code>./height</code> parameter. As can be seen, the correlation between the parameters is a simple case-sensitive string comparison. That is the <code>widht@TypeHint</code> parameter would not apply to the <code>./width</code> even though both parameters address the same property but they do not have a string match.</p>
+<h6 id="typehint"><code>@TypeHint</code></h6>
+<p>Parameters with the <code>@TypeHint</code> suffix may be used to force storing the named parameter in a property with the given type. The value of the <code>@TypeHint</code> parameter, if applied to a parameter for a property, is the JCR property type name. If the <code>@TypeHint</code> parameter is applied to a field upload parameter, the value is used to indicate the JCR primary node type for the node into which the uploaded file is stored.</p>
+<p>If the <code>@TypeHint</code> ends with "<a href=""></a>", it indicates a multi-value property. A multi-value property is usually auto-detected if there are mutliple values for the property (ie. request parameter). But if only a single value is present in the request, the desired property type needs to be explicitly defined as multi-value by stating <code>@TypeHint=&lt;type&gt;[]</code>.</p>
+<p>Example: The following form sets the numeric <code>width</code>, the boolean <code>checked</code>, and the multi-valued <code>hobbys</code> (with 3 values to enter) properties:</p>
+<p>{code:html}
+<form method="POST" action="/content/page/first" enctype="multipart/form-data">
+    <input type="text" name="width" />
+    <input type="hidden" name="width@TypeHint" value="Long" />
+    <input type="checkbox" name="checked" />
+    <input type="hidden" name="checked@TypeHint" value="Boolean" />
+    <input type="text" name="hobbys"/>
+    <input type="text" name="hobbys"/>
+    <input type="text" name="hobbys"/>
+    <input type="hidden" name="hobbys@TypeHint" value="String<a href=""></a>" />
+    <input type="Submit" />
+</form></p>
+<div class="codehilite"><pre><span class="n">In</span> <span class="n">real</span> <span class="n">applications</span> <span class="n">you</span> <span class="n">would</span> <span class="n">need</span> <span class="n">some</span> <span class="n">javascript</span> <span class="n">that</span> <span class="n">allows</span> <span class="n">to</span> <span class="n">add</span><span class="sr">/remove values, ie. add/</span><span class="n">remove</span> <span class="n">inputs</span> <span class="n">with</span> <span class="n">the</span> <span class="n">name</span> <span class="s">&quot;hobbys&quot;</span><span class="o">.</span> <span class="n">Or</span> <span class="n">a</span> <span class="n">pure</span> <span class="n">javascript</span> <span class="n">based</span> <span class="n">form</span> <span class="n">post</span> <span class="n">would</span> <span class="n">be</span> <span class="n">used</span><span class="p">,</span> <span class="n">that</span> <span class="n">gathers<
 /span> <span class="n">the</span> <span class="n">properties</span> <span class="n">to</span> <span class="n">update</span> <span class="n">programmatically</span><span class="p">,</span> <span class="n">but</span> <span class="n">the</span> <span class="n">additional</span> <span class="n">parameter</span>  <span class="n">would</span> <span class="n">be</span> <span class="n">the</span> <span class="n">same</span><span class="o">.</span>
+
+<span class="n">The</span>  <span class="n">suffixed</span> <span class="n">parameter</span> <span class="n">is</span> <span class="n">assumed</span> <span class="n">to</span> <span class="n">be</span> <span class="n">single</span><span class="o">-</span><span class="n">valued</span><span class="o">.</span> <span class="n">If</span> <span class="n">the</span> <span class="n">parameter</span> <span class="n">has</span> <span class="n">multiple</span> <span class="nb">values</span><span class="p">,</span> <span class="n">only</span> <span class="n">the</span> <span class="n">first</span> <span class="n">is</span> <span class="n">actually</span> <span class="n">used</span><span class="o">.</span>
+
+<span class="n">For</span> <span class="n">more</span> <span class="n">information</span> <span class="n">on</span> <span class="n">applying</span>  <span class="n">to</span> <span class="n">a</span> <span class="n">file</span> <span class="n">upload</span> <span class="n">parameter</span> <span class="n">see</span> <span class="n">the</span> <span class="n">section</span> <span class="n">on</span> <span class="n">File</span> <span class="n">Uploads</span> <span class="n">above</span><span class="o">.</span>
+
+<span class="n">h6</span><span class="o">.</span>
+
+<span class="n">The</span>  <span class="n">suffixed</span> <span class="n">parameter</span> <span class="n">may</span> <span class="n">be</span> <span class="n">provided</span> <span class="n">to</span> <span class="n">set</span> <span class="n">a</span> <span class="n">property</span> <span class="n">to</span> <span class="n">a</span> <span class="n">default</span> <span class="n">value</span> <span class="n">should</span> <span class="nb">no</span> <span class="n">value</span> <span class="n">be</span> <span class="n">provided</span> <span class="n">in</span> <span class="n">the</span> <span class="n">actual</span> <span class="n">parameters</span><span class="o">.</span> <span class="n">Same</span> <span class="n">as</span> <span class="k">for</span> <span class="n">normal</span> <span class="n">parameters</span><span class="p">,</span> <span class="n">the</span>  <span class="n">parameter</span> <span class="n">may</span> <span class="n">have</span> <span class="n">mult
 iple</span> <span class="nb">values</span> <span class="n">to</span> <span class="n">create</span> <span class="n">multi</span><span class="o">-</span><span class="n">valued</span> <span class="n">properties</span><span class="o">.</span>
+
+<span class="n">Example:</span> <span class="n">Set</span> <span class="n">the</span>  <span class="n">property</span> <span class="n">to</span> <span class="n">a</span> <span class="n">default</span> <span class="n">value</span> <span class="k">if</span> <span class="n">the</span> <span class="n">user</span> <span class="n">does</span> <span class="ow">not</span> <span class="n">provide</span> <span class="n">one:</span>
+
+<span class="p">{</span><span class="n">code:html</span><span class="p">}</span>
+<span class="o">&lt;</span><span class="n">form</span> <span class="n">method</span><span class="o">=</span><span class="s">&quot;POST&quot;</span> <span class="n">action</span><span class="o">=</span><span class="s">&quot;/content/page/first&quot;</span> <span class="n">enctype</span><span class="o">=</span><span class="s">&quot;multipart/form-data&quot;</span><span class="o">&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;text&quot;</span> <span class="n">name</span><span class="o">=</span><span class="s">&quot;text&quot;</span> <span class="o">/&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;hidden&quot;</span> <span class="n">name</span><span class="o">=</span><span class="s">&quot;text@DefaultValue&quot;</span> <span class="n">value</span><span class="o">=</span><span class="s">&quot;--- Default Value ---&quot;</span> <span class="o">/&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;Submit&quot;</span> <span class="o">/&gt;</span>
+<span class="sr">&lt;/form&gt;</span>
+</pre></div>
+
+
+<h6 id="usedefaultwhenmissing"><code>@UseDefaultWhenMissing</code></h6>
+<p>As described above, <code>@DefaultValue</code> only takes effect if no value is provided for a particular parameter. However, in some cases, such as HTML checkboxes, this isn't sufficient because the parameter isn't submitted at all. To handle this scenario, you can use the <code>@UseDefaultWhenMissing</code> suffixed parameter.</p>
+<p>{code:html}
+<form method="POST" action="/content/page/first" enctype="multipart/form-data">
+    <input name="queryIgnoreNoise" class="input" type="checkbox" value="true"/>
+    <input type="hidden" name="queryIgnoreNoise@DefaultValue" value="false"/> 
+    <input type="hidden" name="queryIgnoreNoise@UseDefaultWhenMissing" value="true"/>
+</form></p>
+<div class="codehilite"><pre>h6.
+
+Sometimes a form client will supply empty parameter values resulting in content being created or modified. For example submitting this form:
+
+{code:html}
+<span class="nt">&lt;form</span> <span class="na">method=</span><span class="s">&quot;POST&quot;</span> <span class="na">action=</span><span class="s">&quot;/content/page/first&quot;</span> <span class="na">enctype=</span><span class="s">&quot;multipart/form-data&quot;</span><span class="nt">&gt;</span>
+    <span class="nt">&lt;input</span> <span class="na">type=</span><span class="s">&quot;hidden&quot;</span> <span class="na">name=</span><span class="s">&quot;stringProperty@TypeHint&quot;</span> <span class="na">value=</span><span class="s">&quot;String[]&quot;</span><span class="nt">/&gt;</span>
+    <span class="nt">&lt;input</span> <span class="na">type=</span><span class="s">&quot;text&quot;</span> <span class="na">name=</span><span class="s">&quot;stringProperty&quot;</span> <span class="na">value=</span><span class="s">&quot;foo&quot;</span><span class="nt">/&gt;</span>
+    <span class="nt">&lt;input</span> <span class="na">type=</span><span class="s">&quot;text&quot;</span> <span class="na">name=</span><span class="s">&quot;stringProperty&quot;</span> <span class="na">value=</span><span class="s">&quot;bar&quot;</span><span class="nt">/&gt;</span>
+    <span class="nt">&lt;input</span> <span class="na">type=</span><span class="s">&quot;text&quot;</span> <span class="na">name=</span><span class="s">&quot;stringProperty&quot;</span> <span class="na">value=</span><span class="s">&quot;&quot;</span><span class="nt">/&gt;</span>
+<span class="nt">&lt;/form&gt;</span>
+</pre></div>
+
+
+<p>will result in multi-value String property being set to <a href=""> "foo", "bar", "" </a>. Notice the blank value.</p>
+<p>Likewise submitting this form without a value entered:</p>
+<p>{code:html}
+<form method="POST" action="/content/page/first" enctype="multipart/form-data">
+    <input type="hidden" name="stringProperty@TypeHint" value="String"/>
+    <input type="text" name="stringProperty" value=""/>
+</form></p>
+<div class="codehilite"><pre><span class="n">will</span> <span class="n">result</span> <span class="n">in</span> <span class="n">the</span> <span class="n">single</span><span class="o">-</span><span class="n">value</span> <span class="n">String</span> <span class="n">property</span> <span class="n">being</span> <span class="n">set</span> <span class="n">to</span> <span class="n">an</span> <span class="n">empty</span> <span class="n">string</span><span class="o">.</span>
+
+<span class="n">To</span> <span class="n">overcome</span> <span class="n">this</span> <span class="n">situation</span> <span class="n">the</span>  <span class="n">suffix</span> <span class="n">may</span> <span class="n">be</span> <span class="n">used</span> <span class="n">to</span> <span class="n">consider</span> <span class="n">parameters</span> <span class="n">with</span> <span class="n">an</span> <span class="n">empty</span> <span class="n">string</span> <span class="n">value</span> <span class="n">to</span> <span class="n">be</span> <span class="n">ignored</span> <span class="n">during</span> <span class="n">processing</span><span class="o">.</span> <span class="n">That</span> <span class="n">is</span> <span class="n">such</span> <span class="n">parameter</span> <span class="nb">values</span> <span class="n">would</span> <span class="n">be</span> <span class="n">treated</span> <span class="n">as</span> <span class="k">if</span> <span class="n">they</span> <span class="n
 ">would</span> <span class="ow">not</span> <span class="n">be</span> <span class="n">supplied</span><span class="o">.</span>
+
+<span class="n">Adding</span>
+
+<span class="p">{</span><span class="n">code:html</span><span class="p">}</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;hidden&quot;</span> <span class="n">name</span><span class="o">=</span><span class="s">&quot;stringProperty@IgnoreBlanks&quot;</span> <span class="n">value</span><span class="o">=</span><span class="s">&quot;true&quot;</span><span class="o">/&gt;</span>
+</pre></div>
+
+
+<p>to the above forms will cause the multi-value property be set to the two-element value <a href=""> "foo", "bar" </a> and to not modify the property at all in the second single-value example.</p>
+<h6 id="valuefrom"><code>@ValueFrom</code></h6>
+<p>In some situations, an HTML form with parameters may be reused to update content. But one or more form parameters may not comply with the names expected to be used for properties. In this case a parameter suffixed with <code>@ValueFrom</code> may be set containing the name of the parameter providing the actual data to be used.</p>
+<p>Example: To set the property <code>text</code> from a form element <code>supplied_text</code>, you might use the following form:</p>
+<p>{code:html}
+<form method="POST" action="/content/page/first" enctype="multipart/form-data">
+    <input type="text" name="supplied_text" />
+    <input type="hidden" name="./text@ValueFrom" value="supplied_text" />
+    <input type="Submit" />
+</form></p>
+<div class="codehilite"><pre><span class="n">To</span> <span class="n">prevent</span> <span class="n">storing</span> <span class="n">the</span> <span class="n">additional</span> <span class="n">paramaters</span> <span class="n">in</span> <span class="n">the</span> <span class="n">repository</span> <span class="n">you</span> <span class="n">might</span> <span class="n">want</span> <span class="n">to</span> <span class="k">use</span> <span class="n">the</span> <span class="n">prefixing</span> <span class="n">mechanism</span> <span class="n">as</span> <span class="n">shown</span> <span class="n">in</span> <span class="n">the</span> <span class="n">example</span> <span class="n">above</span><span class="p">,</span> <span class="n">where</span> <span class="n">the</span>  <span class="n">parameter</span> <span class="n">is</span> <span class="n">prefixed</span> <span class="ow">and</span> <span class="n">thus</span> <span class="n">the</span>  <span class="n">parameter</span> <sp
 an class="n">is</span> <span class="ow">not</span> <span class="n">used</span> <span class="k">for</span> <span class="n">property</span> <span class="n">setting</span><span class="o">.</span>
+
+<span class="n">The</span>  <span class="n">suffixed</span> <span class="n">parameter</span> <span class="n">is</span> <span class="n">assumed</span> <span class="n">to</span> <span class="n">be</span> <span class="n">single</span><span class="o">-</span><span class="n">valued</span><span class="o">.</span> <span class="n">If</span> <span class="n">the</span> <span class="n">parameter</span> <span class="n">has</span> <span class="n">multiple</span> <span class="nb">values</span> <span class="n">it</span> <span class="n">is</span> <span class="n">ignored</span> <span class="n">completely</span><span class="o">.</span>
+
+<span class="n">The</span>  <span class="n">suffixed</span> <span class="n">parameter</span> <span class="n">is</span> <span class="n">also</span> <span class="n">special</span> <span class="n">in</span> <span class="n">that</span> <span class="n">there</span> <span class="n">must</span> <span class="ow">not</span> <span class="n">be</span> <span class="n">a</span> <span class="n">correlated</span> <span class="n">parameter</span> <span class="n">without</span> <span class="n">a</span> <span class="n">suffix</span><span class="o">.</span> <span class="n">Thus</span> <span class="n">have</span> <span class="n">parameters</span>  <span class="ow">and</span>  <span class="n">may</span> <span class="n">have</span> <span class="n">unexpected</span> <span class="n">results</span><span class="o">.</span>
+
+<span class="n">h6</span><span class="o">.</span>
+
+<span class="n">Sometimes</span> <span class="n">it</span> <span class="n">may</span> <span class="n">be</span> <span class="n">required</span> <span class="n">to</span> <span class="ow">not</span> <span class="n">set</span> <span class="n">a</span> <span class="n">property</span> <span class="n">to</span> <span class="n">a</span> <span class="n">specific</span> <span class="n">value</span> <span class="n">but</span> <span class="n">to</span> <span class="n">just</span> <span class="n">remove</span> <span class="n">it</span> <span class="k">while</span> <span class="n">processing</span> <span class="n">the</span> <span class="n">content</span> <span class="n">update</span> <span class="n">request</span><span class="o">.</span> <span class="n">One</span> <span class="n">such</span> <span class="n">situation</span> <span class="n">is</span> <span class="n">a</span> <span class="n">property</span> <span class="n">filled</span> <span class="n">from</span> <span class="n">one</sp
 an> <span class="ow">or</span> <span class="n">more</span> <span class="n">checkboxes</span> <span class="n">in</span> <span class="n">an</span> <span class="n">HTML</span> <span class="n">form</span><span class="o">.</span> <span class="n">If</span> <span class="n">none</span> <span class="n">of</span> <span class="n">the</span> <span class="n">checkboxes</span> <span class="n">are</span> <span class="n">checked</span><span class="p">,</span> <span class="nb">no</span> <span class="n">parameter</span> <span class="n">is</span> <span class="n">actually</span> <span class="n">submitted</span> <span class="k">for</span> <span class="n">these</span> <span class="n">checkboxes</span><span class="o">.</span> <span class="n">Hence</span> <span class="n">the</span> <span class="n">SlingPostServlet</span> <span class="n">will</span> <span class="ow">not</span> <span class="n">touch</span> <span class="n">this</span> <span class="n">property</span> <span class="ow">and</span> <span c
 lass="n">effectively</span> <span class="n">leave</span> <span class="n">it</span> <span class="n">untouched</span><span class="p">,</span> <span class="k">while</span> <span class="n">the</span> <span class="n">natural</span> <span class="n">reaction</span> <span class="n">would</span> <span class="n">have</span> <span class="n">been</span> <span class="n">to</span> <span class="n">remove</span> <span class="n">the</span> <span class="n">property</span><span class="o">.</span>
+
+<span class="n">Here</span> <span class="n">comes</span> <span class="n">the</span>  <span class="n">suffixed</span> <span class="n">parameter</span><span class="o">.</span> <span class="n">This</span> <span class="n">simply</span> <span class="n">causes</span> <span class="n">the</span> <span class="n">indicated</span> <span class="n">property</span> <span class="n">be</span> <span class="n">removed</span> <span class="k">if</span> <span class="n">it</span> <span class="nb">exists</span><span class="o">.</span> <span class="n">If</span> <span class="n">the</span> <span class="n">property</span> <span class="n">does</span> <span class="ow">not</span> <span class="n">exist</span><span class="p">,</span> <span class="n">nothing</span> <span class="n">more</span> <span class="n">happens</span><span class="o">.</span> <span class="n">The</span> <span class="n">actual</span> <span class="n">value</span> <span class="n">of</span> <span class="n">the</span>  <span class="n">suffixe
 d</span> <span class="n">parameter</span> <span class="n">does</span> <span class="ow">not</span> <span class="n">care</span> <span class="n">as</span> <span class="n">long</span> <span class="n">as</span> <span class="n">the</span> <span class="n">parameter</span> <span class="n">is</span> <span class="n">submitted</span><span class="o">.</span>
+
+<span class="n">Example:</span> <span class="n">To</span> <span class="n">ensure</span> <span class="n">the</span>  <span class="n">property</span> <span class="n">is</span> <span class="n">actually</span> <span class="n">removed</span> <span class="k">if</span> <span class="nb">no</span> <span class="n">color</span> <span class="n">has</span> <span class="n">been</span> <span class="n">selected</span><span class="p">,</span> <span class="n">you</span> <span class="n">might</span> <span class="k">use</span> <span class="n">the</span> <span class="n">following</span> <span class="n">form:</span>
+
+<span class="p">{</span><span class="n">code:html</span><span class="p">}</span>
+<span class="o">&lt;</span><span class="n">form</span> <span class="n">method</span><span class="o">=</span><span class="s">&quot;POST&quot;</span> <span class="n">action</span><span class="o">=</span><span class="s">&quot;/content/page/first&quot;</span> <span class="n">enctype</span><span class="o">=</span><span class="s">&quot;multipart/form-data&quot;</span><span class="o">&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;checkbox&quot;</span> <span class="n">name</span><span class="o">=</span><span class="s">&quot;color&quot;</span> <span class="n">value</span><span class="o">=</span><span class="s">&quot;red&quot;</span> <span class="o">/&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;checkbox&quot;</span> <span class="n">name</span><span class="o">=</span><span class="s">&quot;color&quot;</span> <span class="n">value</span><span class="o">=</span><span class="s">&quot;green&quot;</span> <span class="o">/&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;checkbox&quot;</span> <span class="n">name</span><span class="o">=</span><span class="s">&quot;color&quot;</span> <span class="n">value</span><span class="o">=</span><span class="s">&quot;blue&quot;</span> <span class="o">/&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;hidden&quot;</span> <span class="n">name</span><span class="o">=</span><span class="s">&quot;color@Delete&quot;</span> <span class="n">value</span><span class="o">=</span><span class="s">&quot;delete text&quot;</span> <span class="o">/&gt;&lt;!--</span> <span class="n">actual</span> <span class="n">value</span> <span class="n">is</span> <span class="n">ignored</span> <span class="o">--&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;Submit&quot;</span> <span class="o">/&gt;</span>
+<span class="sr">&lt;/form&gt;</span>
+</pre></div>
+
+
+<p>The <code>@Delete</code> suffixed parameter is also special in that there need not be a correlated parameter without a suffix. If both -- a parameters <code>text</code> and <code>text@Delete</code> are set, the <code>text</code> property is first deleted and then filled with the new content.</p>
+<p>The <code>@Delete</code> suffixed parameter in fact calls for a sub-operation, which is executed after the node addressed by the request URL is created (if needed) but before any other tasks of content creattion and modification are done. Any item -- this may be a property or a node, actually -- addressed by the <code>@Delete</code> suffixed parameter is just removed if it exists. If the item does not exist, nothing happens.</p>
+<h6 id="movefrom"><code>@MoveFrom</code></h6>
+<p>Now, that your bright and shiny content management application has great Flash-based file upload feature you will want to be able to use the pre-uploaded files for your content with the same request as when you upload other content. For example you might have a node storing some text and an illustration you uploaded as an image file.</p>
+<p>To support this kind of functionality, the <code>@MoveFrom</code> suffixed parameter may be set to the repository path of the node to where you uploaded the image file.</p>
+<p>Example: Your Flash-based file upload stored the file on the server at <code>/tmp/upload/123</code>. You now want to store this file along with a title and a text in a newly created node. The following form will be your friend:</p>
+<p>{code:html}
+<!-- trailing slash generates a name for the new node -->
+<form method="POST" action="/content/page/" enctype="multipart/form-data">
+    <input type="hidden" name="image@MoveFrom" value="/tmp/upload/123" />
+    <input type="text" name="title" />
+    <input type="text" name="text" />
+    <input type="Submit" />
+</form></p>
+<div class="codehilite"><pre><span class="n">If</span> <span class="n">there</span> <span class="nb">exists</span> <span class="nb">no</span> <span class="n">repository</span> <span class="n">item</span> <span class="n">at</span> <span class="n">the</span> <span class="n">indicated</span> <span class="n">path</span><span class="p">,</span> <span class="n">nothing</span> <span class="n">is</span> <span class="n">done</span><span class="o">.</span> <span class="n">If</span> <span class="n">the</span> <span class="n">item</span> <span class="n">indicated</span> <span class="n">by</span> <span class="n">the</span>  <span class="n">suffixed</span> <span class="n">parameter</span> <span class="n">already</span> <span class="nb">exists</span><span class="p">,</span> <span class="n">it</span> <span class="n">is</span> <span class="n">replaced</span> <span class="n">by</span> <span class="n">the</span> <span class="n">item</span> <span class="n">addressed</span> <span class="n">by</s
 pan> <span class="n">the</span> <span class="n">parameter</span> <span class="n">value</span> <span class="o">--</span> <span class="k">unless</span> <span class="n">of</span> <span class="n">course</span> <span class="n">there</span> <span class="n">is</span> <span class="nb">no</span> <span class="n">item</span> <span class="n">at</span> <span class="n">the</span> <span class="n">named</span> <span class="n">location</span><span class="o">.</span>
+
+<span class="n">The</span>  <span class="n">suffixed</span> <span class="n">parameter</span> <span class="n">is</span> <span class="n">assumed</span> <span class="n">to</span> <span class="n">be</span> <span class="n">single</span><span class="o">-</span><span class="n">valued</span><span class="o">.</span> <span class="n">If</span> <span class="n">the</span> <span class="n">parameter</span> <span class="n">has</span> <span class="n">multiple</span> <span class="nb">values</span> <span class="n">it</span> <span class="n">is</span> <span class="n">ignored</span> <span class="n">completely</span><span class="o">.</span>
+
+<span class="n">The</span>  <span class="n">suffixed</span> <span class="n">parameter</span> <span class="n">is</span> <span class="n">also</span> <span class="n">special</span> <span class="n">in</span> <span class="n">that</span> <span class="n">there</span> <span class="n">must</span> <span class="ow">not</span> <span class="n">be</span> <span class="n">a</span> <span class="n">correlated</span> <span class="n">parameter</span> <span class="n">without</span> <span class="n">a</span> <span class="n">suffix</span><span class="o">.</span> <span class="n">Thus</span> <span class="n">have</span> <span class="n">parameters</span>  <span class="ow">and</span>  <span class="n">may</span> <span class="n">have</span> <span class="n">unexpected</span> <span class="n">results</span><span class="o">.</span>
+
+<span class="n">The</span>  <span class="n">suffixed</span> <span class="n">parameter</span> <span class="n">in</span> <span class="n">fact</span> <span class="n">calls</span> <span class="k">for</span> <span class="n">a</span> <span class="n">sub</span><span class="o">-</span><span class="n">operation</span><span class="p">,</span> <span class="n">which</span> <span class="n">is</span> <span class="n">executed</span> <span class="n">after</span> <span class="n">the</span>  <span class="k">sub </span><span class="nf">operation</span> <span class="nf">but</span> <span class="nf">before</span> <span class="nf">any</span> <span class="nf">other</span> <span class="nf">tasks</span> <span class="nf">of</span> <span class="nf">content</span> <span class="nf">creattion</span> <span class="nf">and</span> <span class="nf">modification</span> <span class="nf">are</span> <span class="nf">done</span><span class="p">.</span>
+
+<span class="p">h6.</span>
+
+<span class="p">Similar to the  suffix exists a  suffix. The latter works exactly the same as the former except that the item addressed by the parameter value is not moved but just copied.</span>
+
+<span class="p">Example: Your Flash-based file upload stored the file on the server at . You now want to store this file along with a title and a text in a newly created node. The following form may be your friend:</span>
+
+<span class="p">{</span><span class="n">code:html</span><span class="p">}</span>
+<span class="o">&lt;!--</span> <span class="n">trailing</span> <span class="n">slash</span> <span class="n">generates</span> <span class="n">a</span> <span class="n">name</span> <span class="k">for</span> <span class="n">the</span> <span class="k">new</span> <span class="n">node</span> <span class="o">--&gt;</span>
+<span class="o">&lt;</span><span class="n">form</span> <span class="n">method</span><span class="o">=</span><span class="s">&quot;POST&quot;</span> <span class="n">action</span><span class="o">=</span><span class="s">&quot;/content/page/&quot;</span> <span class="n">enctype</span><span class="o">=</span><span class="s">&quot;multipart/form-data&quot;</span><span class="o">&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;hidden&quot;</span> <span class="n">name</span><span class="o">=</span><span class="s">&quot;image@CopyFrom&quot;</span> <span class="n">value</span><span class="o">=</span><span class="s">&quot;/tmp/upload/123&quot;</span> <span class="o">/&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;text&quot;</span> <span class="n">name</span><span class="o">=</span><span class="s">&quot;title&quot;</span> <span class="o">/&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;text&quot;</span> <span class="n">name</span><span class="o">=</span><span class="s">&quot;text&quot;</span> <span class="o">/&gt;</span>
+    <span class="o">&lt;</span><span class="n">input</span> <span class="n">type</span><span class="o">=</span><span class="s">&quot;Submit&quot;</span> <span class="o">/&gt;</span>
+<span class="sr">&lt;/form&gt;</span>
+</pre></div>
+
+
+<p>If there exists no repository item at the indicated path, nothing is done. If the item indicated by the <code>@CopyFrom</code> suffixed parameter already exists, it is replaced by the item addressed by the parameter value -- unless of course there is no item at the named location.</p>
+<p>The <code>@CopyFrom</code> suffixed parameter is assumed to be single-valued. If the parameter has multiple values it is ignored completely.</p>
+<p>The <code>@CopyFrom</code> suffixed parameter is also special in that there must not be a correlated parameter without a suffix. Thus have parameters <code>text</code> and <code>text@CopyFrom</code> may have unexpected results.</p>
+<p>The <code>@CopyFrom</code> suffixed parameter in fact calls for a sub-operation, which is executed after the <code>@MoveFrom</code> sub operation but before any other tasks of content creattion and modification are done.</p>
+<h5 id="algorithm-for-node-name-creation">Algorithm for Node Name Creation</h5>
+<p>If request is posted with an URL ending in slash <code>/</code> or slash-star <code>/*</code>, the SlingPostServlet derives a name for the node to be created upon the request applying the following algorithm:</p>
+<ol>
+<li>If a <code>:name</code> parameter is supplied, the (first) value of this parameter is used unmodified as the name for the new node. If the name is illegally formed with respect to JCR name requirements, an exception will be thrown when trying to create the node. The assumption with the <code>:name</code> parameter is, that the caller knows what he (or she) is supplying and should get the exact result if possible.</li>
+<li>Otherwise if a <code>:nameHint</code> parameter is supplied, the (first) value of this parameter is used to generate the node name. A name filtering is applied to this hint to ensure a valid JCR node name.</li>
+<li>Otherwise a series of request paramaters supplied to set content is inspected for a possible name. The list of the names of these parameter is configurable with the SlingPostServlet and defaults ot <code>[ title, jcr:title, name, description, jcr:description, abstract ]()</code>. The first request parameter with a non-empty value is used and filtered to get the valid JCR name.</li>
+<li>Otherwise an ever increasing auto generated number is used. Filtering is also applied to this numeric name.</li>
+</ol>
+<p>The filtering algorithm to create a valid name of the hints from above steps (except the first) works as follows:</p>
+<ul>
+<li>Convert the proposed name to all lower case.</li>
+<li>Replace all characters not in the range [0..9a..z*]() by a single underscore <code>\*</code>.</li>
+<li>If the name starts with a digit prepend an underscore. Technically names with leading digits are valid, but they present major issues when using such names in JCR XPath expressions. The algorithm takes care to not create names with two or more consecutive underscore characters.</li>
+<li>Finally the name is cut to a configurable maximum length (default is 20 characters).</li>
+</ul>
+<p>For example the <code>:nameHint</code> value <em>A quick brown Fox ...</em> is filtered to become <em>a*quick*brown*fox*</em></p>
+<p>After generating and filtering the name it is further guaranteed that the name is unique: If a node of the same name as just generated from the algorithm already exists below the same parent node a numeric index is appended to the new node name to make it unique.</p>
+<h5 id="response-status">Response Status</h5>
+<p>The modification operation has the following status responses:</p>
+<table>
+<thead>
+<tr>
+<th>Status</th>
+<th>Explanation</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>200/OK</td>
+<td>An existing node has been updated with content</td>
+</tr>
+<tr>
+<td>201/CREATED</td>
+<td>A new node has been created and filled with content</td>
+</tr>
+<tr>
+<td>500/INTERNAL SERVER ERROR</td>
+<td>Some exception, for example a <code>RepositoryException</code>, occurred while processing the request</td>
+</tr>
+</tbody>
+</table>
+<h3 id="content-removal">Content Removal</h3>
+<p>To remove existing content just address the item to be removed and set the <code>:operation</code> parameter to <code>delete</code>. For example the following command line removes the <code>/content/sample</code> page:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">curl</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;:operation=delete&quot;</span> <span class="n">http:</span><span class="sr">//</span><span class="n">host</span><span class="sr">/content/s</span><span class="n">ample</span>
+</pre></div>
+
+
+<h5 id="response-status_1">Response Status</h5>
+<p>The delete operation has the following status responses:</p>
+<table>
+<thead>
+<tr>
+<th>Status</th>
+<th>Explanation</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>200/OK</td>
+<td>The resource (and all its descendents) has been removed</td>
+</tr>
+<tr>
+<td>404/NOT FOUND</td>
+<td>The request URL does not address an existing repository item</td>
+</tr>
+<tr>
+<td>500/INTERNAL SERVER ERROR</td>
+<td>Some exception, for example a <code>RepositoryException</code>, occurred while processing the request</td>
+</tr>
+</tbody>
+</table>
+<h5 id="deleting-multiple-items">Deleting Multiple Items</h5>
+<p>By using the <code>:applyTo</code> request parameter it is possible to remove multiple items in one single request. Deleting items in this way leaves you with less control, though. In addition, if a single item removal fails, no item at all is removed.</p>
+<p>When specifying the item(s) to be removed with the <code>:applyTo</code> parameter, the request resource is left untouched (unless of course if listed in the <code>:applyTo</code> parameter) and only used to resolve any relative paths in the <code>:applyTo</code> parameter.</p>
+<p>To remove the <code>/content/page1</code> and <code>/content/page2</code> nodes, for example, you might use the following command line:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">curl</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;:operation=delete&quot;</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;:applyTo=/content/page1&quot;</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;:applyTo=/content/page2&quot;</span> <span class="n">http:</span><span class="sr">//</span><span class="n">host</span><span class="sr">/content/s</span><span class="n">ample</span>
+</pre></div>
+
+
+<p>Using a trailing star in the :applyTo parameter (as mentioned before), you can remove all the children of the <code>/content</code> node, for example, as follows:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">curl</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;:operation=delete&quot;</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;:applyTo=/content/*&quot;</span> <span class="n">http:</span><span class="sr">//</span><span class="n">host</span><span class="sr">/content/s</span><span class="n">ample</span>
+</pre></div>
+
+
+<p>If any resource listed in the <code>:applyTo</code> parameter does not exist, it is silently ignored.</p>
+<h6 id="response-status_2">Response Status</h6>
+<p>The delete operation applied to multiple resources has the following status responses:</p>
+<table>
+<thead>
+<tr>
+<th>Status</th>
+<th>Explanation</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>200/OK</td>
+<td>All requested and existing resources have been removed</td>
+</tr>
+<tr>
+<td>500/INTERNAL SERVER ERROR</td>
+<td>Some exception, for example a <code>RepositoryException</code>, occurred while processing the request</td>
+</tr>
+</tbody>
+</table>
+<h3 id="copying-content">Copying Content</h3>
+<p>To copy existing content to a new location, the <code>copy</code> operation is specified. This operation copies the item addressed by the request URL to a new location indicated by the <code>:dest</code> parameter. The <code>:dest</code> parameter is the absolute or relative path to which the resource is copied. If the path is relative it is assumed to be below the same parent as the request resource. If it is terminated with a <code>/</code> character the request resource is copied to an item of the same name under the destination path.</p>
+<p>To illustrate the <code>:dest</code> parameter handling, lets look at a few examples. All examples are based on addressing the <code>/content/sample</code> item:</p>
+<table>
+<thead>
+<tr>
+<th><code>:dest</code> Parameter</th>
+<th>Destination Absolute Path</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>/content/newSample</code></td>
+<td><code>/content/newSample</code></td>
+</tr>
+<tr>
+<td><code>different/newSample</code></td>
+<td><code>/content/different/newSample</code></td>
+</tr>
+<tr>
+<td><code>/content/different/</code></td>
+<td><code>/content/different/sample</code></td>
+</tr>
+<tr>
+<td><code>different/</code></td>
+<td><code>/content/different/sample</code></td>
+</tr>
+</tbody>
+</table>
+<p>If an item already exists at the location derived from the <code>:dest</code> parameter, the copy operation fails unless the <code>:replace</code> parameter is set to <code>true</code> (case is ignored when checking the parameter value).</p>
+<h5 id="response-status_3">Response Status</h5>
+<p>The copy operation has the following status responses:</p>
+<table>
+<thead>
+<tr>
+<th>Status</th>
+<th>Explanation</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>200/OK</td>
+<td>The node has been copied to the new location replacing an existing item at the destination</td>
+</tr>
+<tr>
+<td>201/CREATED</td>
+<td>The node has been copied to the new location creating a new item at the destination</td>
+</tr>
+<tr>
+<td>404/NOT FOUND</td>
+<td>The request URL does not address an existing repository item</td>
+</tr>
+<tr>
+<td>412/PRECONDITION FAILED</td>
+<td>An item already exists at the destination and the <code>:replace</code> parameter is not set to <code>true</code></td>
+</tr>
+<tr>
+<td>500/INTERNAL SERVER ERROR</td>
+<td>Some exception, for example a <code>RepositoryException</code>, occurred while processing the request</td>
+</tr>
+</tbody>
+</table>
+<h5 id="copying-multiple-items">Copying Multiple Items</h5>
+<p>By using the <code>:applyTo</code> request parameter it is possible to copy multiple items in one single request. Copying items in this way leaves you with less control, though. In addition, if a single item copy fails, no item at all is copied.</p>
+<p>When specifying the item(s) to be copied with the <code>:applyTo</code> parameter, the request resource is left untouched (unless of course if listed in the <code>:applyTo</code> parameter) and only used to resolve any relative paths in the <code>:applyTo</code> parameter.</p>
+<p>To copy the <code>/content/page1</code> and <code>/content/page2</code> nodes to <code>/content/target</code>, for example, use:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">curl</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;:operation=copy&quot;</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;:applyTo=/content/page1&quot;</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;:applyTo=/content/page2&quot;</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;:dest=/content/target/&quot;</span> <span class="n">http:</span><span class="sr">//</span><span class="n">host</span><span class="sr">/content/s</span><span class="n">ample</span>
+</pre></div>
+
+
+<p>Please note the trailing slash character (<code>/</code>) in the value of the <code>:dest</code> parameter. This is required for multi-item copy operations using the <code>:applyTo</code> parameter. The copied items are created below the node indicated by the <code>:dest</code>.</p>
+<p>Using a trailing star in the :applyTo parameter (as mentioned before), you can copy all the children of the <code>/content</code> node, for example, as follows:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">curl</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;:operation=copy&quot;</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;:applyTo=/content/*&quot;</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;:dest=/content/target/&quot;</span> <span class="n">http:</span><span class="sr">//</span><span class="n">host</span><span class="sr">/content/s</span><span class="n">ample</span>
+</pre></div>
+
+

[... 315 lines stripped ...]


Mime
View raw message