From 51f245d72f77ad759f6f223febbf1d5962c7f017 Mon Sep 17 00:00:00 2001
From: Jim Fulton <jim@jimfulton.info>
Date: Thu, 8 Jun 2017 14:48:27 -0400
Subject: [PATCH] provide some explanation on defining dialogs

---
 client/ui/dialog.jsx | 90 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 88 insertions(+), 2 deletions(-)

diff --git a/client/ui/dialog.jsx b/client/ui/dialog.jsx
index c1fa9f3..611048b 100644
--- a/client/ui/dialog.jsx
+++ b/client/ui/dialog.jsx
@@ -1,3 +1,89 @@
+/*
+
+Dialog helpers
+
+The react-toolbox Dialog component and input compnents (input and
+dropdown) are pretty good at displaying dialogs and inputs, but they
+don't manage data very well.  The components defined here help with
+that.  There's also an Editor input that wraps the RichTextEditor
+component from react-rte.
+
+I suggest looking at some examples as you read this.
+
+To create a data-input (or edit) dialog you:
+
+- Subclass DialogBase.
+
+  In your render method, you return a Dialog (the one defined here)
+  component around some input components (and whatever other
+  components you want).
+
+  The Dialog component must be given properties:
+
+  - ref="dialog"
+
+    You must supply this prop and it must have this value.  This is
+    needed to make automation for displaying dislogs work.  Hopefully,
+    there's a way around this that I just haven't found yet.
+
+  - title="YOUR TITLE"
+
+  - action="YOUR OK ACTION"
+
+    This is what's displayed on the OK button. It defaults to "Ok".
+
+  - finish()
+
+    A callback function that's called when user clicks OK and there
+    aren't validation errors.  This function isn't called with
+    data. The input data is in ``this.state``.
+
+  - type (see react-toolbox docs)
+
+- On your input components, supply an ``onChange`` property that is
+  the result of calling ``this.val('NAME')``. 
+
+  For example:
+
+     <Select label='Size' source={[1, 2, 3, 5, 8, 13]}
+             onChange={this.val("size", 1)} />
+
+  The val method is a little magical. It returns an onChange handler
+  that updates your dialog's state with the value set, using the name
+  given. The components provided here call the onChange handler
+  without a value to get the current value, so you don't have to
+  provide a value explicitly.
+
+  The ``val`` method takes up to 3 arguments:
+
+  - the name of the state propery to be used as input and provided as
+    output.
+
+  - A default value to use if the state value is undefined.
+
+  - A validation function.  The validation function is passed: the
+    value to be validated, the state name, and your custom dialog
+    instance.  Is the value is invalid, the validation function should
+    return an error message, otherwise, if the value is valid, it
+    should return any false value.
+
+  Instead of ``val``, you can use ``required('NAME')``, which in turn
+  calls ``val`` with a validation function that checks for a true
+  value (typically a non-empty string).
+
+  For example:
+
+    <Input label='Title' required={true} onChange={this.required("title")} />
+
+
+- Render an instance of your custom dialog component somewhere.  Give
+  it a ``ref`` ref you can use to fetch it when you want to display
+  the dialog (e.g. in an onClick handler).  To display the dialog,
+  call it's ``show()`` method.  You may pass an object containing
+  initial state.
+
+*/
+
 import React from 'react';
 import {Dialog, Input} from 'react-toolbox';
 import RichTextEditor from 'react-rte';
@@ -114,11 +200,11 @@ class DialogBase extends React.Component {
         return this.setState(state);
       }
     };
-    
+
     onChange.error = () => {
       return this.errors[name];
     };
-    
+
     if (validate) {
       onChange.validate = (v) => {
         this.validated(); // force render