Skip to content

Latest commit

 

History

History
163 lines (128 loc) · 7.08 KB

develop.md

File metadata and controls

163 lines (128 loc) · 7.08 KB
title
Development

Development

Workflow

  1. Set up your local development environment
  2. Make some changes and push to a new branch
  3. Open a pull request
  4. Test your form
  5. Wait for status checks to pass and use the published version in your form on sf.gov
  6. Get your pull request reviewed and bump the package version by either:
    • running script/version <version|patch|minor|major> and pushing the commit(s), or
    • merging your pull request into a release branch

Local development

Setup

  1. Clone this repo, e.g. 
    git clone https://github.com/SFDigitalServices/formio-sfds
  2. Run npm install to install all of the dependencies
  3. Run npm run develop to build all of the browser-ready JS and CSS, rebuild whenever changes are made to the source, and start the development server.

Running npm run without any additional arguments will list all of the available scripts, most notably:

  • npm run lint to lint the JS and SCSS source files
  • npm run build to do a one-time build (without watching), or NODE_ENV=production npm run build to build minified assets

Local testing

Running npm run develop (or npm watch-server for just the server) starts the web app on any old available port and prints out its local address, which you can paste into your web browser:

[nodemon] starting `node server.js`
server listening at localhost:50613

There are a collection of HTML documents that power "views" in the web app, and which you can use to test the theme against different form.io data and scenarios:

  • index.html is the home page of the web deployment, and renders each example defined in examples.yml.

    The schema is an array of example objects, each of which should conform to the form.io form schema and provide an additional, unique id property that allows you to deep-link to it on the page.

  • standalone.html is for testing the "standalone" JS bundle against the latest version of formiojs and a snapshot of CSS from sf.gov. It respects the following query string parameters:

    • res overrides the default resource or form URL so that you can test it with live forms. E.g. ?res=https://sfds.form.io/some-other-form

    • lang overrides the form's language, for testing localization. E.g. ?lang=zh for Chinese.

  • portal.html is where you can test the "portal" bundle, which we add as a custom script on form.io to modify the form builder UI.

  • example.htm is used to render an isolated test case for each example in examples.yml. These are linked to in the heading of each example rendered on the home page.

Proxy testing

The deployed app includes an API endpoint that proxies sf.gov, modifies the HTML, then returns it to the browser, effectively "injecting" whatever version of formio-sfds you want into sf.gov (or the Pantheon test environment). Here's how it works:

  1. Visit /api/preview. By default, this will fetch sf.gov/feedback and replace whatever version of formio-sfds it's running with the bundle built with your deployment. (On the production app, this is the latest release.)

  2. Change the query string parameters to modify the preview by appending a ? and one or more of the following, separated with &:

    • form=<url> sets the form.io data source URL of the rendered form
    • options=<json> sets the formio.js render options JSON
    • version=<semver> changes the published version of formio-sfds, rather than using the bundle built by the web app
    • env=<env> changes the name of the sf.gov environment from the default (sf.gov). env=test will set the hostname to the test environment.
    • path=<path> changes the request path from /feedback, so that you can test other pages on sf.gov that might have forms embedded on them.

    Some examples:

    • /api/preview (without any query string parameters) renders the sf.gov feedback form with the local build of formio-sfds.

    • /api/preview?version=6.0.0&path=/node/1061 fetches sf.gov/node/1061 and renders it with [email protected]

    • /api/preview?form=https://sfds-test.form.io/shawntest1 renders a test form on sf.gov with the local build of formio-sfds.

    • /api/preview?options={"i18n":"..."} can be used to render the feedback form with a different set of translations.

Publishing

This repo uses primer/publish to publish new releases of the formio-sfds npm package for every push that passes the CI workflow. The name of the branch determines the "type" of release:

  • Merges to the default branch (main) will release new versions to the latest (default) dist-tag if the version field in package.json has been incremented.
  • Pushes to release-<version> will publish npm releases to the next dist-tag with versions in the form <version>-rc.<sha>, where <sha> is the 7-character commit SHA.
  • Pushes to any other branch will publish releases to the canary dist-tag with versions in the form 0.0.0-<sha>.

You can find the release version for a given branch by navigating to either an open pull request or the "tree" view of that branch on github.com, and clicking on the status icon of the most recent commit:

Where What it looks like
Commit status icon image
Merge box image
Branch tree view image

unpkg

We use unpkg as our CDN. You can access every release published on npm via the version's unique URL:

https://unpkg.com/formio-sfds@<version>/

The trailing slash allows you to browse the published package file hierarchy. Previously, our example and test pages were "hosted" as raw HTML from these URLs, but you should view them on the web app instead.

Note: unpkg.com will strip the query string from any URL you give it, but query string parameters can be passed to those URLs (once, on load) via the hash. In other words, just replace the ? in your query string with #. Remember: You'll need to refresh the page after changing the hash!