Merge pull request #459 from solid/post-talk

Post talk changes to slides

Author: timbl

Documentation/forms-intro.html

@@ -93,9 +93,11 @@
       }
       table.parameters {
         background-color: #dddddd;
+        margin-left: 4em;
       } /*  background-color: #ddddff; */
       table.properties {
         background-color: #ddddff;
+        margin-left: 4em;
       } /*  background-color: #ddddff; */
       td {
         padding: 0.5em;
@@ -240,20 +242,17 @@ <h2>Form field types</h2>
     <table class="properties">
       <tr>
         <td>label</td>
-
         <td>String</td>
-
         <td>
           A label for the form field. This is the prompt for the user, e.g.,
-          "Name", "Employer".
+          "Name", "Employer".  If the label is not given in the form, the
+          system will make one from a label of the property in the ontology.
         </td>
       </tr>
 
       <tr>
         <td>property</td>
-
         <td>rdf:Property</td>
-
         <td>
           When the user enters the data, it is stored in the web as a triple
           with this property as its predicate.
@@ -262,16 +261,25 @@ <h2>Form field types</h2>
 
       <tr>
         <td>default</td>
-
         <td>[according to field type] Optional</td>
-
         <td>
           The input control is set to this value by default. It is easiest for
           the user to enter this value. (This value is <b>not</b> automatically
           stored by the form system if the user does not select or enter it in
           some way.
         </td>
       </tr>
+
+      <tr>
+        <td>suppressEmptyUneditable</td>
+        <td>Boolean</td>
+        <td>
+          Setting this flag (on a single form field not a structure) means that when the user is just reading the data, not
+          editing it, the fields with blank data will be removed completely.
+          This avoid things like a blank field for a region in an address when there isn't one given.
+          This can make the UX much cleaner.  Defaults to false.
+        </td>
+      </tr>
     </table>
 
     <p>
@@ -399,6 +407,24 @@ <h4 class="class">Group</h4>
       the same as for Form.
     </p>
 
+    <table class="properties">
+      <tr>
+        <td>weight</td>
+
+        <td>xsd:integer</td>
+        <td>0:lighter than normal, 1: Normal, 2,3: heavier than normal</td>
+      </tr>
+      <tr>
+        <td>parts</td>
+        <td>rdf:Collection</td>
+        <td>
+          The form fields, forms, in the group
+        </td>
+      </tr>
+    </table>
+
+
+
     <h4 class="class">Choice</h4>
 
     <p>The user choses an item from a class.</p>
@@ -425,18 +451,16 @@ <h4 class="class">Choice</h4>
 
       <tr>
         <td>canMintNew</td>
-
         <td>xsd:Boolean</td>
-
         <td>
           If the user doesn't find the thing they want, can they introduce an
           item of that class by filling in a form about it? [Boolean]
         </td>
       </tr>
     </table>
 
-    If a new thing is minted, that will be done with a form which is a
-    <tt>ui:creationForm</tt> for the class.
+    <p>If a new thing is minted, that will be done with a form which is a
+    <tt>ui:creationForm</tt> for the class.</p>
 
     <h4 class="class">Multiple</h4>
 
@@ -454,6 +478,37 @@ <h4 class="class">Multiple</h4>
       form. It is the field, or the address, and so on.
     </p>
 
+
+    <table class="properties">
+      <tr>
+        <td>ordered</td>
+        <td>Boolean</td>
+        <td>If true, the user has an ordered array of things, and the data is in an RDF collection.
+          If false, the UI is irrelevant and the data is a series of arcs.</td>
+      </tr>
+      <tr>
+        <td>property</td>
+        <td>rdf:Property</td>
+        <td>The API details or query endpoint and query details to be used to search the item in
+          the databasse.</td>
+      </tr>
+      <tr>
+        <td>reverse</td>
+        <td>Boolean</td>
+        <td>If set, the form will write data triple like <tt>X P S</tt> instead of the normal <tt>S P X</tt>.
+         </td>
+      </tr>
+      <tr>
+        <td>part</td>
+        <td>Form</td>
+        <td>The form to be used for each one.
+         </td>
+      </tr>
+    </table>
+
+
+
+
     <h4 class="class">Classifier</h4>
 
     <table class="properties">
@@ -468,7 +523,7 @@ <h4 class="class">Classifier</h4>
         </td>
       </tr>
     </table>
-
+    <p>
     This form field leverages the ontology heavily. It pulls the subclasses of
     the given class, and makes a pop-up menu for the user to chose one. If and
     only if the ontology says that the class is a disjoint union
@@ -477,7 +532,7 @@ <h4 class="class">Classifier</h4>
     shows that that subclass has its own subclasses, then the user will be
     prompted to pick one of those, to (if they like) further refine the
     selection. And so on.
-
+  </p>
     <p>
       The classifier pops a menu to allow the user to select a set of values to
       classify the subject.
@@ -517,7 +572,7 @@ <h4 class="class">Options</h4>
       </tr>
     </table>
 
-    and for each case:
+    <p>and for each case:</p>
 
     <table class="properties">
       <tr>
@@ -565,24 +620,21 @@ <h4 class="class" id="Autocomplete">Autocomplete</h4>
 
     <tr>
       <td>labelProperty</td>
-      <td>String</td>
+      <td>rdf:Property</td>
       <td>The property which will be used to store the name of the selected thing as a separate triple</td>
     </tr>
-
     <tr>
       <td>dataSource</td>
-
       <td>DataSource</td>
-
       <td>The API details or query endpint and query details to be usde to search of the itemn in
         the databasse.</td>
     </tr>
     <tr>
       <td>targetClass</td>
       <td>rdfs:Class</td>
-      <td>Is tyhis is specified, it be used to replace any occuurences of
+      <td>Is tyhis is specified, it be used to replace any occurrences of
          "$(targetClass)" in the query template.  this allows different instances
-         of AutocompleteField to share the same DatSource, by specifying different values for <tt>targetClass</tt>.</td>
+         of AutocompleteField to share the same DataSource, by specifying different values for <tt>targetClass</tt>.</td>
     </tr>
 
   </table>
@@ -604,8 +656,17 @@ <h4 class="class">Heading</h4>
 
         <td>The text content of the heading</td>
       </tr>
+      <tr>
+        <td>suppressIfUneditable</td>
+        <td>Boolean</td>
+        <td>If data is uneditable,ie read-only mode, hide this comment</td>
+      </tr>
     </table>
 
+<p>The <tt>suppressIfUneditable</tt> flag allow you to make a form which
+  is much cleaner and simpler when the user is just reading information,
+  not editing it.</p>
+
     <h4 class="class">Comment</h4>
 
     <p>
@@ -618,11 +679,16 @@ <h4 class="class">Comment</h4>
         <td>contents</td>
 
         <td>String</td>
-
         <td>
           The text content of the comment. (This should be displayed by form
           systems as <tt>pre-wrap</tt> mode.)
         </td>
+        <tr>
+          <td>suppressIfUneditable</td>
+          <td>Boolean</td>
+          <td>If data is uneditable,ie read-only mode, hide this comment</td>
+        </tr>
+
       </tr>
     </table>
 
@@ -634,9 +700,11 @@ <h2>Conclusion</h2>
       daily life at home and at work. It can be vary efficient as developers can
       reuse material between forms. Users can even generate their own forms.
     </p>
+    <p>
     Future directions include separate implementations of the form UI code in
     for various platforms, and using various UI frameworks. There may also be
     extensions of the system with new field types, more options for setting style
     from various sources, etc.
+  </p>
   </body>
 </html>

Documentation/talks/FormsTalk.html

@@ -165,10 +165,10 @@ <h1>Single Line Text field</h1>
 <h1>Examples of other form fields</h1>
 
 <ol>
-  <li><a target="demo" href="../form-examples/demo.html">Examples of individual Form Fields</a></li>
-  <li><a target="demo" href="../form-examples/structures.html">Examples of structures in forms: Groups</a></li>
-  <li><a target="demo" href="../form-examples/structures3.html">Selection, Options, Autocomplete</a></li>
-  <li><a target="demo" href="../form-examples/profile-demo.html">Examples of a Solid profile editing form</a></li>
+  <li><a target="demo1" href="../form-examples/demo.html">Examples of individual Form Fields</a></li>
+  <li><a target="demo2" href="../form-examples/structures.html">Examples of structures in forms: Groups</a></li>
+  <li><a target="demo3" href="../form-examples/structures3.html">Selection, Options, Autocomplete</a></li>
+  <li><a target="demo4" href="../form-examples/profile-demo.html">Examples of a Solid profile editing form</a></li>
   <!--
   <li><a target="demo" href="../form-examples/edit-form.html">Editing a simple form using the Form Form</a></li>
   <li><a target="demo" href="../form-examples/edit-form-form.html">Editing the Form Form</a></li>
@@ -178,10 +178,65 @@ <h1>Examples of other form fields</h1>
 </div>
 
 
+<div class="slide">
+  <h1>Common properties of form fields</h1>
+
+  <table class="properties">
+    <tr>
+      <td>label</td>
+      <td>String</td>
+      <td>
+        A label for the form field, prompt for the user.
+      </td>
+    </tr>
+
+    <tr>
+      <td>property</td>
+      <td>rdf:Property</td>
+      <td>
+        Data it is stored in the web as a triple
+        with this property as its predicate.
+      </td>
+    </tr>
+
+    <tr>
+      <td>default</td>
+      <td>[according to field type] Optional</td>
+      <td>
+        The input control is set to this value by default. It is easiest for
+        the user to enter this value. (This value is <b>not</b> automatically
+        stored by the form system if the user does not select or enter it in
+        some way.
+      </td>
+    </tr>
+
+    <tr>
+      <td>suppressEmptyUneditable</td>
+      <td>Boolean</td>
+      <td>
+        When the user is just reading the data, not
+        editing it, the fields with blank data will be hidden.
+      </td>
+    </tr>
+  </table>
+
+</div>
+
+
+<div class="slide">
+<h1>The Autocomplete field</h1>
+<p>This form field allows users to select things from lists in public databases, things like Languages, Organizations, Occupations, and Skills</p>
+<p>This is not covered in detail in this talk.</p>
+<p>(There is a blog <a href="https://solidos.solidcommunity.net/public/2021/01%20Building%20Solid%20Apps%20which%20use%20Public%20Data.html">
+</i>Building Solid Apps which use Public Data</i></a>,
+  about this which I could run though for those interested)</p>
+  <img src="../diagrams/PersonalPublicDataLinks.svg" />
+</div>
+
 <div class="slide">
 <h1>Code: Render a form</h1>
 <p>To put a form in your UI</p>
-<pre>UI.widgets.appendForm(dom, container, {}, subject, form, doc, callback)
+<pre>const element = UI.widgets.appendForm(dom, null, {}, subject, form, doc, callback)
   </pre>
 
   <table class="parameters">
@@ -192,9 +247,10 @@ <h1>Code: Render a form</h1>
   </tr>
 
   <tr>
-    <td>container</td>
+    <td>null</td>
 
-    <td>is a DOM element to contain the form</td>
+    <td>used to be the is a DOM element to contain the form. If given, the form will be
+    appended to it. This use is deprecated.</td>
   </tr>
 
   <tr>
@@ -222,7 +278,7 @@ <h1>Code: Render a form</h1>
     <td>callback</td>
     <td>
       is a function taking an error flag and a message (if the error flag is
-      true)
+      true). Called when the form field has been set to a new value.
     </td>
   </tr>
 </table>
@@ -241,15 +297,18 @@ <h1>Going meta -- designing forms using the form of forms 1</h1>
 <h1>Going meta -- Editing forms using the form of forms 2</h1>
 <p>Here we are editing the really small form we started with.</p>
 <ul>
-  <li><a target="demo" href="../form-examples/edit-form.html">Editing a simple form using the Form Form</a></li>
+  <li><a target="demo8" href="../form-examples/edit-form.html">Editing a simple form using the Form Form</a></li>
 </ul>
 <p>Here we edit the FormForm with itself.</p>
 <ul>
-  <li><a target="demo" href="../form-examples/edit-form-form.html">Editing the Form Form</a></li>
+  <li><a target="demo9" href="../form-examples/edit-form-form.html">Editing the Form Form</a></li>
 </ul>
 
 </div>
 
+
+
+
 <div class="slide">
 <h1>Forms and Classes</h1>
 <pre>
@@ -349,17 +408,14 @@ <h1>Future</h1>
 </ul>
 </div>
 
-
-
 <div class="slide">
 <h1>Questions?</h1>
+<ul>
+  <p>Reference</p>
+  <li><a target="doc" href="../form-ecosystem.html">Manual: The Form Ecosystem</a></li>
+  <li><a target="doc" href="../forms-intro.html">Manual: Intro to forms</a></li>
+  <li><a target="doc" href="https://www.w3.org/ns/ui.n3">The UI ontology (source)</a></li>
+</ul>
 </div>
-<div class="slide">
-<h1>The Autocomplete field</h1>
-<p>This form field allows users to select things from lists in public databases, things like Languages, Organizations, Occupations, and Skills</p>
-<p>This is not covered in this talk.</p>
-<p>(There is a blog <a href="https://solidos.solidcommunity.net/public/2021/01%20Building%20Solid%20Apps%20which%20use%20Public%20Data.html">
-</i>Building Solid Apps which use Public Data</i></a>,
-  about this which I could run though for those interested)</p>
-  <img src="../diagrams/PersonalPublicDataLinks.svg" />
+
 </div>