Extract and set form values through the DOM—no frameworks required! https://github.com/TheoryOfNekomata/formxtra
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

README.md 2.7 KiB

3 years ago
3 years ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110
  1. <header style="text-align: center; line-height: 1">
  2. <h1 style="margin: 0">
  3. <img src="./docs/assets/formxtra.svg" alt="formxtra"/>
  4. </h1>
  5. <h2 style="margin: 0">
  6. The companion for Web forms!
  7. </h2>
  8. <p style="font-size: 125%">
  9. Extract and set form values through the DOM&mdash;no frameworks required!
  10. </p>
  11. <p>
  12. Lightweight. Simple. It Just Works.
  13. </p>
  14. </header>
  15. ## Installation
  16. The package can be found on:
  17. - [Modal Pack](https://js.pack.modal.sh)
  18. - [npm](https://npmjs.com/package/@theoryofnekomata/formxtra)
  19. - [GitHub Package Registry](https://github.com/TheoryOfNekomata/formxtra/packages/793279)
  20. ## Usage
  21. For an example form:
  22. ```html
  23. <button id="autofill" type="button">
  24. Autofill login form
  25. </button>
  26. <form id="loginForm">
  27. <input type="text" name="username" />
  28. <input type="password" name="password" />
  29. <button type="submit" name="type" value="client">
  30. Log In As Client
  31. </button>
  32. <button type="submit" name="type" value="admin">
  33. Log In As Admin
  34. </button>
  35. </form>
  36. <label>
  37. <input type="checkbox" name="remember" form="loginForm" />
  38. Remember my login credentials
  39. </label>
  40. ```
  41. Use the library as follows (code is in TypeScript, but can work with JavaScript as well):
  42. ```typescript
  43. import { getFormValues, setFormValues } from '@theoryofnekomata/formxtra';
  44. // This is the only query we need. On libraries like React, we can easily get form elements when we
  45. // attach submit event listeners.
  46. const form: HTMLFormElement = document.getElementById('form');
  47. const processResponse = async (response: Response) => {
  48. const result = await response.json();
  49. alert(`Welcome ${result.user}!`);
  50. };
  51. // Best use case is with event handlers
  52. form.addEventListener('submit', async e => {
  53. const {
  54. currentTarget: thisForm,
  55. submitter,
  56. } = e;
  57. e.preventDefault();
  58. const values = getFormValues(thisForm, { submitter });
  59. // Get the form values and send as request to some API
  60. const response = await fetch(
  61. 'https://example.com/api/log-in',
  62. {
  63. method: 'POST',
  64. body: JSON.stringify(values),
  65. headers: {
  66. 'Content-Type': 'application/json',
  67. },
  68. },
  69. );
  70. if (response.ok) {
  71. processResponse(response);
  72. }
  73. });
  74. const autofillButton = document.getElementById('autofill');
  75. autofillButton.addEventListener('click', e => {
  76. setFormValues(form, { username: 'admin', remember: true });
  77. });
  78. ```
  79. There are utility functions exported alongside `getFormValues()` and `setFormValues()`. You may want to use namespace
  80. import with this library, i.e. `import * as formxtra from '@theoryofnekomata/formxtra'`.
  81. See the [documentation folder](./docs) for more details.
  82. ## Tests
  83. The library has been tested on the static DOM using JSDOM, and the real dynamic DOM using Cypress.
  84. ## License
  85. [MIT](./LICENSE)