formio-sfds
Version:
The Form.io theme for sf.gov
167 lines (150 loc) • 6.8 kB
HTML
<html lang="en">
<head>
<title>Docs | 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> /
Docs
</h1>
<main>
<h2 id="user-content-formio-sfds"><a href="#formio-sfds" aria-hidden="true" tabindex="-1"><span>#</span></a>formio-sfds</h2>
<p>This is the <a href="https://form.io">Form.io</a> theme for <a href="https://sf.gov">sf.gov</a>.</p>
<h3 id="user-content-documentation"><a href="#documentation" aria-hidden="true" tabindex="-1"><span>#</span></a>Documentation</h3>
<ul>
<li><a href="#usage">Usage</a>
<ul>
<li><a href="#browser">Browser</a></li>
<li><a href="#css">CSS</a></li>
<li><a href="#formio-portal">Form.io portal</a></li>
</ul>
</li>
<li><a href="components/">Custom components</a></li>
<li><a href="patches/">Formio patches</a>
<ul>
<li><a href="patches/#form-options">Form options</a></li>
<li><a href="patches/#form-upgrades">Form upgrades</a></li>
<li><a href="autocomplete/">Autocomplete components</a></li>
<li><a href="patches/#icons">Icons</a></li>
<li><a href="patches/#declarative-actions">Declarative actions</a></li>
</ul>
</li>
<li><a href="localization/">Localization</a></li>
<li><a href="develop/">Development</a></li>
</ul>
<h3 id="user-content-usage"><a href="#usage" aria-hidden="true" tabindex="-1"><span>#</span></a>Usage</h3>
<h4 id="user-content-browser"><a href="#browser" aria-hidden="true" tabindex="-1"><span>#</span></a>Browser</h4>
<p>The "standalone" JavaScript bundle is intended to be used in a browser (or
browser-like environment) via <code><script></code> tags. You'll need to include the
formiojs library in your document <em>before</em> formio-sfds, like so:</p>
<pre><code><span><<span>script</span> <span>src</span>=<span>"https://unpkg.com/formiojs@4.11.2/dist/formio.full.min.js"</span>></span><span></<span>script</span>></span>
<span><<span>script</span> <span>src</span>=<span>"https://unpkg.com/formio-sfds@7.x/dist/formio-sfds.standalone.js"</span>></span><span></<span>script</span>></span></code></pre>
<h4 id="user-content-css"><a href="#css" aria-hidden="true" tabindex="-1"><span>#</span></a>CSS</h4>
<p>The CSS in this package provides a suite of styles that target a mix of
Form.io-generated selectors and classes used in the custom theme templates, as
well as a collection of general-purpose utility classes for tweaking individual
elements.</p>
<p><strong>Note:</strong> The <code>formio-sfds.standalone.js</code> bundle injects the CSS into the
<code><head></code> of the host document at runtime, so there's no need for a separate
<code><link></code> tag.</p>
<h5 id="user-content-scoped-css"><a href="#scoped-css" aria-hidden="true" tabindex="-1"><span>#</span></a>Scoped CSS</h5>
<p>All of the selectors in the packaged CSS are scoped to (nested in) a
<code>.formio-sfds</code> class selector, which effectively prevents them from leaking
into the page where the form is embedded.</p>
<p>Unless you're using the <a href="#standalone-bundle">standalone bundle</a> (which wraps
the form elements automatically), you'll need to wrap all of your the elements
targeted by <code>Formio.createForm()</code> with a <code><div class="formio-sfds"></code>.</p>
<h4 id="user-content-formio-portal"><a href="#formio-portal" aria-hidden="true" tabindex="-1"><span>#</span></a>Form.io portal</h4>
<p>The "portal" bundle is intended for use <em>inside</em> the form.io admin UI, and
customizes the palette of available components with <a href="components/">this theme's
components</a>. To use it, visit your form.io project Settings
page, and paste the URL below into the "Custom Javascript" (sic) field:</p>
<pre><code>https://unpkg.com/formio-sfds@7.x/dist/portal.js
</code></pre>
<p><img src="https://user-images.githubusercontent.com/113896/90575355-0d109a00-e170-11ea-9593-8be0afe88c70.png" alt=""></p>
<hr>
<p>License: <a href="./LICENSE">MIT</a></p>
<h4 id="user-content-creating-new-versions"><a href="#creating-new-versions" aria-hidden="true" tabindex="-1"><span>#</span></a>Creating new versions</h4>
<ol>
<li>
<p>Open a PR in the formio-sfds repo (may need to add you as a collaborator so that you can open PRs directly and GitHub Actions will publish your changes to npm automatically)</p>
</li>
<li>
<p>In the PR checks, when you click “Show all checks”, you can copy the published version from the “publish formio-sfds” check:</p>
</li>
<li>
<p>Pop that 0.0.0- value into the "Form.io SFDS version" field on /admin/config/services/sfgov_formio in your local and multidev environments (not in the committed settings YAML — we only want to commit published versions)</p>
</li>
<li>
<p>Test your changes and get them reviewed in your multidev</p>
</li>
<li>
<p>Get the changes to formio-sfds approved and released</p>
</li>
<li>
<p>Update config/sfgov_formio.settings.yml by setting formio_sfds_version to the newly published release version (i.e. 9.2.3)</p>
</li>
<li>
<p>Re-test after deploying again to make sure it still works</p>
</li>
</ol>
</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/README.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>