-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathmodel.5.html
246 lines (244 loc) · 14 KB
/
model.5.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
<!DOCTYPE html>
<html>
<head>
<title>Dataset Project</title>
<link href='https://fonts.googleapis.com/css?family=Open+Sans' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="https://caltechlibrary.github.io/css/site.css">
</head>
<body>
<header>
<a href="http://library.caltech.edu" title="link to Caltech Library Homepage"><img src="https://caltechlibrary.github.io/assets/liblogo.gif" alt="Caltech Library logo"></a>
</header>
<nav>
<ul>
<li><a href="/">Home</a></li>
<li><a href="index.html">README</a></li>
<li><a href="LICENSE">LICENSE</a></li>
<li><a href="INSTALL.html">INSTALL</a></li>
<li><a href="user_manual.html">User Manual</a></li>
<li><a href="about.html">About</a></li>
<li><a href="search.html">Search</a></li>
<li><a href="https://github.com/caltechlibrary/models">GitHub</a></li>
</ul>
</nav>
<section>
<h1 id="name">NAME</h1>
<p>models</p>
<h1 id="synopsis">SYNOPSIS</h1>
<pre><code>import "github.com/caltechlibrary/models"</code></pre>
<h1 id="description">DESCRIPTION</h1>
<p><strong>models</strong> is a Go package. A model is expressed in
YAML. They are used by <code>modelgen</code> to render HTML web forms or
SQLite3 schema.</p>
<h2 id="model">Model</h2>
<dl>
<dt>id</dt>
<dd>
The identifier for the model. Is the “id” given to the generated HTML
web form.
</dd>
<dt>title</dt>
<dd>
If provided it will be used to insert a title above your web form.
</dd>
<dt>attributes</dt>
<dd>
These map to the HTML attributes in a web form. Typical you would
include method (e.g. GET, POST) and action (e.g. a URL to the form
page). Attributes are a key/value map of form attributes.
</dd>
<dt>description</dt>
<dd>
This is simple description of the model. It will be included as a
comment in the SQLite3 SQL. This is a text string or block.
</dd>
<dt>elements</dt>
<dd>
This is a list of elements that describe the data attributes of your
model.
</dd>
</dl>
<h2 id="elements">Elements</h2>
<p>The elements attribute holds a list of elements. You can think of
these as HTML5 form elements described in YAML. They will also be used
to infer SQLite 3 column types.</p>
<p>Each element is made from the following properties.</p>
<dl>
<dt>type</dt>
<dd>
(required) This is a string and maps to the input element types
available in HTML5<a href="#fn1" class="footnote-ref" id="fnref1"
role="doc-noteref"><sup>1</sup></a>.
</dd>
<dt>id</dt>
<dd>
(optional) This is the element’s identifier. It should be unique with in
the model. While optional it is used to retrieve an element from a
model. If is also required when rendering column definitions in SQLite
3. A model that includes a submit or reset button would examples of when
to leave it blank.
</dd>
<dt>attributes</dt>
<dd>
(optional) This is a list of key/value pairs that map to HTML5 input
elements. Boolean HTML element attributes like “required” and “checked”
you are expressed as <code>required: true</code> and
<code>checked: true</code> in YAML. NOTE: attributes value’s are
resolved to quoted strings when rendered as HTML.
</dd>
<dt>pattern</dt>
<dd>
(optional) This is a regular expression pattern that is used to validate
the input of the element<a href="#fn2" class="footnote-ref" id="fnref2"
role="doc-noteref"><sup>2</sup></a>.
</dd>
<dt>options</dt>
<dd>
(optional) Are a list of key/value maps used to expression HTML5 select
elements. They can be be used in validation of a model’s content as well
as in render HTML selection elements.
</dd>
<dt>is_primary_id</dt>
<dd>
(optional) If set to true it indicates a given element holds the model’s
primary identifier. If you are store model content in a SQLite 3
database or Dataset collection this would be the unique identifier used
to retrieve the modeled object.
</dd>
<dt>label</dt>
<dd>
(optional) If set it is used as the text content of the label when
rendering a web form.
</dd>
</dl>
<h2 id="data-type-support-in-models-package">Data type support in models
package</h2>
<p>The models package starts from the premise of supporting a YAML
description of a web form that then can be used to render HTML and SQL
Schema. It also needs to be able to be a thin layer in a Go API that can
validate the elements of a model just like they are validated browser
side by the <a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input">HTML5
input types</a>. The following are all implemented by the models package
using a naive validation approach<a href="#fn3" class="footnote-ref"
id="fnref3" role="doc-noteref"><sup>3</sup></a>.</p>
<ul>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/button">button</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox">checkbox</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/color">color</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date">date</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/datetime-local">datetime-local</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/email">email</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/hidden">hidden</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/image">image</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/month">month</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number">number</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/password">password</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/radio">radio</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/range">range</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/reset">reset</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/search">search</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/submit">submit</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/tel">tel</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/text">text</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/time">time</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/url">url</a></li>
<li><a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/week">week</a></li>
</ul>
<p>Additional data types<a href="#fn4" class="footnote-ref" id="fnref4"
role="doc-noteref"><sup>4</sup></a> can be defined by using the
<code>Model.Define</code> function provided in this package. You need to
provide a name for the new type as well as the func’s name. The
“defined” data types are applied before the default types. This allows
for improvements to the defaults while retaining a fallback. Hopefully
this mechanism can prove useful to expanding the data types supported by
models.</p>
<p>NOTE: As the models package evolves the validation methods provided
out of the box will evolve too. Some may even be dropped if they prove
problematic<a href="#fn5" class="footnote-ref" id="fnref5"
role="doc-noteref"><sup>5</sup></a>.</p>
<h1 id="example">Example</h1>
<p>This is an example model of a guest book entry used in a Dataset base
guest book web application.</p>
<div class="sourceCode" id="cb2"><pre
class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="fu">id</span><span class="kw">:</span><span class="at"> test_model</span></span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="fu">attributes</span><span class="kw">:</span></span>
<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">method</span><span class="kw">:</span><span class="at"> GET</span></span>
<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">action</span><span class="kw">:</span><span class="at"> ./</span></span>
<span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">x-success</span><span class="kw">:</span><span class="at"> http://localhost:8000/success.html</span></span>
<span id="cb2-6"><a href="#cb2-6" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">x-fail</span><span class="kw">:</span><span class="at"> http://localhost:8000/failed.html</span></span>
<span id="cb2-7"><a href="#cb2-7" aria-hidden="true" tabindex="-1"></a><span class="fu">elements</span><span class="kw">:</span></span>
<span id="cb2-8"><a href="#cb2-8" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="kw">-</span><span class="at"> </span><span class="fu">id</span><span class="kw">:</span><span class="at"> id</span></span>
<span id="cb2-9"><a href="#cb2-9" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">type</span><span class="kw">:</span><span class="at"> text</span></span>
<span id="cb2-10"><a href="#cb2-10" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">attributes</span><span class="kw">:</span></span>
<span id="cb2-11"><a href="#cb2-11" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">name</span><span class="kw">:</span><span class="at"> id</span></span>
<span id="cb2-12"><a href="#cb2-12" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">placeholder</span><span class="kw">:</span><span class="at"> Enter a unique string</span></span>
<span id="cb2-13"><a href="#cb2-13" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">required</span><span class="kw">:</span><span class="at"> </span><span class="ch">true</span></span>
<span id="cb2-14"><a href="#cb2-14" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">is_primary_id</span><span class="kw">:</span><span class="at"> </span><span class="ch">true</span></span>
<span id="cb2-15"><a href="#cb2-15" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="kw">-</span><span class="at"> </span><span class="fu">id</span><span class="kw">:</span><span class="at"> name</span></span>
<span id="cb2-16"><a href="#cb2-16" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">type</span><span class="kw">:</span><span class="at"> text</span></span>
<span id="cb2-17"><a href="#cb2-17" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">attributes</span><span class="kw">:</span></span>
<span id="cb2-18"><a href="#cb2-18" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">name</span><span class="kw">:</span><span class="at"> name</span></span>
<span id="cb2-19"><a href="#cb2-19" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">placeholdertext</span><span class="kw">:</span><span class="at"> Enter your name</span></span>
<span id="cb2-20"><a href="#cb2-20" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">required</span><span class="kw">:</span><span class="at"> </span><span class="ch">true</span></span>
<span id="cb2-21"><a href="#cb2-21" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="kw">-</span><span class="at"> </span><span class="fu">id</span><span class="kw">:</span><span class="at"> msg</span></span>
<span id="cb2-22"><a href="#cb2-22" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">type</span><span class="kw">:</span><span class="at"> textarea</span></span>
<span id="cb2-23"><a href="#cb2-23" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">attributes</span><span class="kw">:</span></span>
<span id="cb2-24"><a href="#cb2-24" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">name</span><span class="kw">:</span><span class="at"> msg</span></span>
<span id="cb2-25"><a href="#cb2-25" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">placehodertext</span><span class="kw">:</span><span class="at"> Enter a short message or comment</span></span></code></pre></div>
<section id="footnotes" class="footnotes footnotes-end-of-document"
role="doc-endnotes">
<hr />
<ol>
<li id="fn1"><p>See <a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input"
class="uri">https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input</a>
for details.<a href="#fnref1" class="footnote-back"
role="doc-backlink">↩︎</a></p></li>
<li id="fn2"><p>See <a
href="https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern"
class="uri">https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern</a>
for details of how patterns are used in validation.<a href="#fnref2"
class="footnote-back" role="doc-backlink">↩︎</a></p></li>
<li id="fn3"><p>“naive” in this case means overly simplistic validation,
e.g. min max ranges don’t validate against step attributes.<a
href="#fnref3" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
<li id="fn4"><p>The validation function is used server side only because
it is written in Go. E.g. by Dataset’s JSON API.<a href="#fnref4"
class="footnote-back" role="doc-backlink">↩︎</a></p></li>
<li id="fn5"><p>E.g. “week” input type is not widely used and is poorly
supported by browsers in 2024. “image” doesn’t make a whole lot of
sense.<a href="#fnref5" class="footnote-back"
role="doc-backlink">↩︎</a></p></li>
</ol>
</section>
</section>
<footer>
<span>© 2024 <a href="https://www.library.caltech.edu/copyright">Caltech Library</a></span>
<address>1200 E California Blvd, Mail Code 1-32, Pasadena, CA 91125-3200</address>
<span><a href="mailto:library@caltech.edu">Email Us</a></span>
<span>Phone: <a href="tel:+1-626-395-3405">(626)395-3405</a></span>
</footer>
</body>
</html>