UrlFormJS

Sitcky URL Forms forms with sharable links. Supports query parameters and fragment query parameters.

Demo

Query Parameters, Fragment Anchors, and Fragment Query Parameters

UrlFormJS supports normal URL query parameters for stickiness.

It also supports fragment query parameters. Unlike query parameters, fragments are not sent to the server from the browser, which makes fragments ideal for sensitive information. We recommend applications use fragment query parameters over query parameters when possible.

https://example.com:8042/over/there?name=ferret#nose?name=bob
\_____________________________________________/\____________/
           |                                          |
   Sent to the server                            Kept local

For example, if a browser is given the URL https://example.com#test the browser makes a request only to https://example.com and does not include #test in the request. Example.com would be unaware of #test.

Fragment query parameters are located after the first #, then after the next ?. It is ended by the end of the URL, by the next ?, or other fragment scheme like the delimiter :~:.

If query parameter and fragment query parameter are set to the same key name, the fragment query parameter takes precedence.

Parts of the URL:

foo://example.com:8042/over/there?name=ferret#nose?name=bob
\_/   \______________/\_________/ \_________/ \___________/
 |           |            |            |            |
scheme    authority      path         query      fragment

Where nose?name=bob is the fragment, nose is the fragment anchor, and ?name=bob is the fragment query.

In this example, since the query parameter and the fragment query parameter have the same key name of "name", the value of "bob" will take precedence over "ferret".

See RFC 3986 for query parameters and Wikipedia.

Fragment query parameters are "non-standard", but we hope if enough people find it useful to standardize them through an RFC or other means.

Install

URLFormJS can be added into a project as a submodule with the following command:

git submodule add git@github.com:Cyphrme/URLFormJS.git urlformjs

To update the submodule:

git submodule update --remote

Alternatively, download urlform.js.

If not importing urlform.js as a module, the file can be loaded in HTML using:

<script defer src="./urlformjs/urlform.js"></script>

urlform.js is in 'UMD' format and can be accessed in Javascript with the following:

window.urlformjs

See example.js for an example of initializing URLFormJS for a given form.

Development

Issue submissions and pull requests are welcome. Before submitting pull request, please ensure tests are passing and that the test form behavior is correct.

We have a single page test that's useful. Since it uses js modules it needs an http server. Use server.go for this.

go run server.go

To generate the minified file, use esbuild to run the following:

esbuild urlform.js --minify --outfile=urlform.min.js

'UMD' format is being interpreted as CommonJS (for node) instead of 'UMD', and minifying the file wrong. See: evanw/esbuild#507 (comment)

Tests

Testing uses BrowserTestJS:

cd /urlformjs/browsertestjs/
go run server.go

Then go to localhost:8082 for the results.

Demonstration that fragment is not sent off.

The test server logs requests and can be used to demonstrated that fragment is not sent to the server by the browser by visiting https://localhost:8082?name=bob#test or using curl:

curl -k https://localhost:8082?name=bob#test

Note that ?name=bob appears in the log but #test does not.

Fragment Directive/Text Fragment Chrome bugs

Chrome and potentially other browsers are removing anything after fragment directives from the URL when using 'window.location'. This library gracefully handles this bug except when the protocol is file://. See notes on getFragment and stack overflow.

Note that fragment directives, including text fragments, should have the '?' character URL escaped.

Demonstrates of Firefox working and Chrome breaking

Quag

We found it useful to name a super set of query and fragment, dubbed quag. The quag includes ? and #.

foo://example.com:8042/over/there?name=ferret#nose?name=bob
\_/   \______________/\_________/ \_________/ \___________/
 |           |            |            |            |
scheme    authority      path         query       fragment
                                 \_________________________/
                                              | 
                                             quag

Probably out of scope for this library:

• JSON Schema validation.
• Form validation.
• Field requirements/limitations.

Logo license

"you are free to use your logo for promotional purposes"

---

Attribution, Trademark notice, and License

URLFormJS is released under The 3-Clause BSD License.

"Cyphr.me" is a trademark of Cypherpunk, LLC. The Cyphr.me logo is all rights reserved Cypherpunk, LLC and may not be used without permission.