formio-sfds
Version:
The Form.io theme for sf.gov
150 lines (133 loc) • 6.06 kB
HTML
<html lang="en">
<head>
<title>Autocomplete components | formio-sfds documentation</title>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<meta name="viewport" content="width=device-width">
<link rel="stylesheet" href="/sfgov/forms.css">
<link rel="stylesheet" href="https://unpkg.com/highlight.js/styles/github.css">
<style type="text/css">
.h-1em { height: 1em ; }
h2,
h3,
h4,
h5,
h6 {
position: relative;
}
main p {
margin: 0;
}
main p + p {
margin-top: 20px;
}
li + li {
margin-top: 5px;
}
table {
margin: 20px 0;
}
th,
td {
padding: 5px;
}
a[aria-hidden="true"] {
position: absolute;
right: 100%;
font-weight: normal;
text-decoration: none;
}
</style>
</head>
<body>
<div class="formio-sfds">
<div class="container p-2">
<h1 class="h3 mb-4">
<a href="/">formio-sfds@10.0.0</a> /
<a href="/docs/">Docs</a> /
Autocomplete components
</h1>
<main>
<p>This theme <em>disables</em> the default autocomplete functionality of formio.js's
built-in <a href="https://help.form.io/userguide/form-components/#select">select component</a> and only enables it if the component has an
<code>autocomplete</code> tag in the "Field tags" input of the "API" tab on the form.io portal:</p>
<p><img src="https://help.form.io/assets/img/api1.png" alt=""></p>
<h3 id="user-content-translation"><a href="#translation" aria-hidden="true" tabindex="-1"><span>#</span></a>Translation</h3>
<p>We patch the <code>customOptions</code> of every autocomplete component at runtime to
include translated (or, at least, translatable) UI strings with predictable
keys that can be customized either globally (all autocomplete components in a
single form) or for each instance. These are the options that <a href="https://github.com/jshjohnson/Choices#readme">Choices.js</a> lets
us localize:</p>
<table>
<thead>
<tr>
<th align="left">Option</th>
<th align="left">English</th>
<th align="left">Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left"><a href="https://github.com/jshjohnson/Choices#searchplaceholdervalue"><code>searchPlaceholderValue</code></a></td>
<td align="left">"Type to search"</td>
<td align="left">The placeholder text of the search input</td>
</tr>
<tr>
<td align="left"><a href="https://github.com/jshjohnson/Choices#noresultstext"><code>noResultsText</code></a></td>
<td align="left">"No results found"</td>
<td align="left"></td>
</tr>
<tr>
<td align="left"><a href="https://github.com/jshjohnson/Choices#itemselecttext"><code>itemSelectText</code></a></td>
<td align="left"><em>none</em></td>
<td align="left">Displayed on the right side of the dropdown alongside the currently highlighted option</td>
</tr>
<tr>
<td align="left"><a href="https://github.com/jshjohnson/Choices#maxitemtext"><code>maxItemText</code></a></td>
<td align="left">"Only {{count}} values can be added"</td>
<td align="left">The <code>{{count}}</code> placeholder is substituted with the <a href="https://github.com/jshjohnson/Choices#maxitemcount">maxItemCount</a> option.</td>
</tr>
<tr>
<td align="left"><a href="https://github.com/jshjohnson/Choices#nochoicestext"><code>noChoicesText</code></a></td>
<td align="left">"No choices to choose from"</td>
<td align="left">This should only show up if we haven't provided any static options or have a dynamic select driven by an API that doesn't return any results.</td>
</tr>
<tr>
<td align="left"><a href="https://github.com/jshjohnson/Choices#additemtext"><code>addItemText</code></a></td>
<td align="left"><em>none</em></td>
<td align="left">⚠️ I <strong>think</strong> that this option is only applicable when freeform values are allowed. If so, this shows up when you've typed a search string as a prompt, e.g. "Press Enter to add <strong>{{value}}</strong>", where <code>{{value}}</code> is substituted with the "backend" value of the option.</td>
</tr>
</tbody>
</table>
<p>To translate these for all autocomplete components in your form, you'll need to
prefix each option with the <code>autocomplete.</code> prefix. So, to translate the text
that shows up when no items match the typed value, you would add translations
for the <code>autocomplete.noResultsText</code> Phrase key.</p>
<p>You can also translate these strings for individual components by prefixing
<code>autcomplete.{option}</code> with the component's key and a <code>.</code>. For instance, if you
had an autocomplete component with the key <code>yourJob</code> and wanted to translate
the placeholder text, you would add translations for the
<code>yourJob.autocomplete.searchPlaceholderValue</code> Phrase key.</p>
<p>The default translations for the <code>autocomplete.*</code> keys live in this repo's
<a href="https://github.com/SFDigitalServices/formio-sfds/tree/main/src/i18n">i18n directory</a> and can be updated from the <a href="https://app.phrase.com/accounts/city-county-of-san-francisco/projects/form-io-generic-strings">generic strings Phrase project</a>.</p>
</main>
<div class="bg-grey-1 p-2 round-1 mt-4 d-flex flex-justify-between">
<div class="mr-2">
<a href="https://github.com/SFDigitalServices/formio-sfds/edit/main/docs/autocomplete.md">
Edit this page on GitHub
</a>
</div>
</div>
</div>
</div>
<script src="https://unpkg.com/formiojs@4.14.8/dist/formio.full.min.js"></script>
<script src="/dist/formio-sfds.standalone.js"></script>
<script>
// fix images with height attributes that get
// `height: auto` from drupal.css
for (const img of document.querySelectorAll('img[height]')) {
img.setAttribute('style', `height: ${img.getAttribute('height')}px;`)
}
</script>
</body>
</html>