From f7a54c92845d9dbb247770049368e22830522c77 Mon Sep 17 00:00:00 2001 From: Matthew Jones Date: Wed, 3 Jul 2024 18:39:45 -0700 Subject: [PATCH] INT-268 Update documentation to include parent/child api --- package.json | 2 +- tests/dummy/app/controllers/docs/advanced.js | 26 +++++++++++ tests/dummy/app/router.js | 1 + tests/dummy/app/templates/docs.hbs | 1 + tests/dummy/app/templates/docs/advanced.md | 46 ++++++++++++++++++++ tests/dummy/app/templates/docs/controls.md | 31 +++++++------ tests/dummy/app/templates/docs/fields.md | 6 +-- tests/dummy/app/templates/docs/forms.md | 25 +++-------- tests/dummy/app/templates/docs/index.md | 38 +++++++++++++--- tests/dummy/app/templates/docs/usage.md | 6 +-- 10 files changed, 133 insertions(+), 49 deletions(-) create mode 100644 tests/dummy/app/controllers/docs/advanced.js create mode 100644 tests/dummy/app/templates/docs/advanced.md diff --git a/package.json b/package.json index 89a2e79d..85b95f38 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "ember-foxy-forms", "version": "2.46.2", - "description": "An addon for building forms that work with ember data", + "description": "An Ember form library that makes the everyday use cases trivial, while providing the flexibility to handle highly unique requirements", "keywords": [ "ember-addon" ], diff --git a/tests/dummy/app/controllers/docs/advanced.js b/tests/dummy/app/controllers/docs/advanced.js new file mode 100644 index 00000000..ae6fbde3 --- /dev/null +++ b/tests/dummy/app/controllers/docs/advanced.js @@ -0,0 +1,26 @@ +import Controller from '@ember/controller'; +import { tracked } from '@glimmer/tracking'; +import { action } from '@ember/object'; + +class User { + @tracked name = 'user-1234'; +} + +class Avatar { + @tracked name = 'default'; +} + +export default class AdvancedController extends Controller { + @tracked user = new User(); + @tracked avatar = new Avatar(); + + @action + async handleSubmit() { + alert(`Creating new user with username ${this.user.name}... user created!`); + } + + @action + async handleChildSubmit() { + alert(`Updating avatar description to ${this.user.name}-${this.avatar.name}-avatar.jpeg... avatar description updated!`); + } +} diff --git a/tests/dummy/app/router.js b/tests/dummy/app/router.js index 7127273d..6fab022f 100644 --- a/tests/dummy/app/router.js +++ b/tests/dummy/app/router.js @@ -13,6 +13,7 @@ Router.map(function () { this.route('forms'); this.route('fields'); this.route('controls'); + this.route('advanced'); }); this.route('not-found', { path: '/*path' }); diff --git a/tests/dummy/app/templates/docs.hbs b/tests/dummy/app/templates/docs.hbs index db014b3e..1f93b331 100644 --- a/tests/dummy/app/templates/docs.hbs +++ b/tests/dummy/app/templates/docs.hbs @@ -5,6 +5,7 @@ {{nav.item "Forms" "docs.forms"}} {{nav.item "Fields" "docs.fields"}} {{nav.item "Controls" "docs.controls"}} + {{nav.item "Advanced" "docs.advanced"}} diff --git a/tests/dummy/app/templates/docs/advanced.md b/tests/dummy/app/templates/docs/advanced.md new file mode 100644 index 00000000..2f0c5275 --- /dev/null +++ b/tests/dummy/app/templates/docs/advanced.md @@ -0,0 +1,46 @@ +# Advanced Use Cases + +## Child Forms + +Foxy Forms supports parent/child relationships to better separate concerns for more verbose scenarios. Calling submit on the parent will submit itself, and then call submit any children, breadth-first, afterward. + +**NOTE**: the parent form will only call submit on children with dirty fields. + +**Example: product onboarding** + +Let's say we want to collect a new user's information during an onboarding flow, and then optionally allow the 'default' part of the avatar name to be updated. We could have two forms: one responsible for collecting general account information, and another specific to handling avatar logic. + +{{#docs-demo as |demo|}} + {{#demo.example name="advanced-usage.hbs"}} +
+ +
+ Optional: change avatar description? + +
+ {{this.user.name}}- + + -avatar.jpeg +
+ +
+ + + {{/demo.example}} + {{demo.snippet "advanced-usage.hbs"}} +{{/docs-demo}} diff --git a/tests/dummy/app/templates/docs/controls.md b/tests/dummy/app/templates/docs/controls.md index 56e4198d..5af46faa 100644 --- a/tests/dummy/app/templates/docs/controls.md +++ b/tests/dummy/app/templates/docs/controls.md @@ -1,7 +1,7 @@ # Controls -Ember foxy forms comes packed with support with the default set of html5 controls, as well as a few 'emberized' ones that -make interacting with ember-data / ember-objects a little more straight forward. They can be selected using the 'using' +`ember-foxy-form` comes packed with support with the default set of html5 controls, as well as a few 'emberized' ones that +make interacting with ember-data / Ember objects a little more straight forward. They can be selected using the '@using' attribute. If you provide no ```@using``` or ```@control``` attribute the form will default to using the text type. ## Text Input Variants @@ -85,10 +85,10 @@ A checkbox can take an optional label attribute. ## Select -FoxyForms comes with two select controls out of the box that work with both primitive arrays (numbers and strings) or -ember objects. When working with objects you can specify an identifier key `@idKey` and a label key `@labelKey` -these will be used to identify your object and to label the drop down. -Also you can disable an option by setting `disabled: true` in your value object in values array. +`ember-foxy-form` comes with two select controls out of the box that work with both primitive arrays (numbers and strings) or +Ember objects. When working with objects you can specify an identifier key `@idKey` and a label key `@labelKey` +these will be used to identify your object and to label the drop down. Also you can disable an option by setting `disabled: true` +in your value object in values array. {{#docs-demo as |demo|}} {{#demo.example name="select-control.hbs"}} @@ -162,9 +162,8 @@ Also you can disable an option by setting `disabled: true` in your value object ## Custom Controls -You can extend form for to provide custom controls, your component must simply conform to the control interface: - -A form control is any component which implements the following interface. +You can extend your form to provide your own custom controls, your component must simply conform to the +control interface: {{#docs-snippet name="custom-controls.js"}} interface FormControl { @@ -185,16 +184,16 @@ A form control is any component which implements the following interface. } {{/docs-snippet}} -If you follow this convention values will be seamlessly managed by the field / form layers. Some examples of custom controls -we have built are: +If you follow this convention, values will be seamlessly managed by the field / form layers. Some examples of +custom controls we have built are: -- Image Select Control -- Map Editor Control -- Price Range Select -- Rich Text editor +- Image select Control +- Map editor Control +- Price range Select +- Rich text editor - JSON editor -By default Foxy Forms looks for your custom controls in the component directory form-controls of your application, +By default, Foxy Forms looks for your custom controls in the `components/form-controls` directory of your application, but you can also specify the full path to the control. {{#docs-demo as |demo|}} diff --git a/tests/dummy/app/templates/docs/fields.md b/tests/dummy/app/templates/docs/fields.md index 8b8cb3a0..57ee53a3 100644 --- a/tests/dummy/app/templates/docs/fields.md +++ b/tests/dummy/app/templates/docs/fields.md @@ -1,6 +1,6 @@ # Fields -Fields are responsible for connecting form-controls to fields. +Fields are responsible for connecting form controls to model/object values. ## Standard and Composite Values @@ -22,7 +22,7 @@ controlling a date range. This can be done by simply passing an array of keys to ## Specifying the control FieldFor accepts a @using parameter, which instructs it to use a particular form control for the field. It uses the following -rubric to lookup your component based on that name.FieldFor +rubric to lookup your component based on that name: 1. It looks for a custom control in your application with a path matching ```form-controls/<@using>``` 2. It looks for a custom control in your application with a path matching ```form-controls/<@using>-control``` this affordance is for legacy projects and will be removed in version 3.0.0 @@ -183,4 +183,4 @@ fully qualified path a component that respects the display value component inter {{/demo.example}} {{demo.snippet "custom-display-component.hbs"}} -{{/docs-demo}} \ No newline at end of file +{{/docs-demo}} diff --git a/tests/dummy/app/templates/docs/forms.md b/tests/dummy/app/templates/docs/forms.md index 639aa7e3..dbf06e43 100644 --- a/tests/dummy/app/templates/docs/forms.md +++ b/tests/dummy/app/templates/docs/forms.md @@ -1,12 +1,9 @@ # Form Features in detail -FoxyForms is a fully featured form framework, mostly designed for dealing with ember-data models. It comes with a number -of features that make composing UIs very simple. +## Error Mapping -## Value & Error Mapping - -The primary role of FoxyForms is to map errors / values from a model to various form controls. The assume structure of -the model looks something like this: +`ember-foxy-forms` will automatically map error (messages) from a model to form controls. It assumes the structure of +the model is the following: {{#docs-snippet name="model.js"}} { @@ -20,11 +17,11 @@ the model looks something like this: } {{/docs-snippet}} - This schema is consistent with ember-data, JSON:API spec, and ember-model-validator. -When an error is present ember foxy-forms will add error classes to the forms / fields. +### scrollToFirstVisibleError +You can configure a form to scroll its first field with an error into view on failed submission. Using the scrollToFirstVisibleError options. ## Automatic Submission Mode When in automatic submission mode, the form will automatically trigger the submission action when a change is committed @@ -85,7 +82,7 @@ the confirm button. If you click the reject button the changes will be rolled ba {{demo.snippet "inline.hbs"}} {{/docs-demo}} -## Notification +## Notifications Forms can be configured to notify the user when a form either succeeds or fails. This behaviour is configurable as follows: @@ -127,14 +124,6 @@ Forms can be configured to notify the user when a form either succeeds or fails. The form-for service can be extended to provide custom popups, or messages by injecting it into your application. -## Errors - -By default ember-foxy-forms wires errors from ember-data models. - - -### scrollToFirstVisibleError - -You can configure a form to scroll its first field with an error into view on failed submission. Using the scrollToFirstVisibleError options. ## Navigation Guards @@ -273,7 +262,7 @@ buttons: ```form-for-model-name__button-type-button``` {{/docs-snippet}} -Form for will automatically generate [grid-areas](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-area) defined +Form will automatically generate [grid-areas](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-area) defined as inline styles on its elements. This feature can be turned on either by setting `useGridTemplate` to `true` in the config or passing it as an arg. This allows you to define your form layout using the [grid-template](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template) syntax. diff --git a/tests/dummy/app/templates/docs/index.md b/tests/dummy/app/templates/docs/index.md index 28d621a7..60bcb0b5 100644 --- a/tests/dummy/app/templates/docs/index.md +++ b/tests/dummy/app/templates/docs/index.md @@ -1,8 +1,27 @@ # Introduction -Hey, welcome to the docs for ember-foxy-forms, this addon was built to do away with a lot of the needless plumbing when -building forms over data in ember. Common use cases like displaying validation errors, notifying the user on successful -submission, can all be very tedious in a typical ember application, with ember foxy forms this is trivial! +Forms can get *tedious*. Common use cases like displaying validation errors, or notifying the user on a successful submission +start to not not only feel repetitive, but also error prone. + +At [Food.ee](https://food.ee), we decided to get sly about this problem with `ember-foxy-forms`, an Ember form library that makes the +everyday use cases trivial, while providing the flexibility to handle highly unique user requirements. + +*💡 `ember-foxy-forms` was built with `ember-data` and `ember-model-validator` in mind, but it is not intrinsically tied to either of +these libraries. You can use `ember-foxy-forms` with any data store that conforms to the JSON:API spec, or without any data store at all.* + + +## Overview + +Generally speaking, using `ember-foxy-forms` is a quick, three-step process: + +Supply an model or object to the form. + +Then, specify to the fields which values they represent. + +Finally, choose which form control to use for each field. + + +## Basic Example ```js class MyRoute extends Route { @@ -14,7 +33,7 @@ class MyRoute extends Route { ```hbs
@@ -22,11 +41,16 @@ class MyRoute extends Route {
``` -## Custom Configurations -## Site-wide `environment.js` overrides +## Getting Started + +```bash +yarn add -D ember-foxy-forms +``` + +## Global Settings -You can customize the way foxy forms handles various options by adding your override to your environment file. +You can customize the way `ember-foxy-forms` handles various options by adding your override to your environment file. ```javascript //environment.js diff --git a/tests/dummy/app/templates/docs/usage.md b/tests/dummy/app/templates/docs/usage.md index 8c93c439..8099f8a5 100644 --- a/tests/dummy/app/templates/docs/usage.md +++ b/tests/dummy/app/templates/docs/usage.md @@ -1,9 +1,7 @@ # Usage -Below is a configurable example of the basic usage of ember-foxy-forms, it showcases all of the html5 input controls -that can be mounted to your data model. - -The various features can be toggled on / off below. +Below is an interactive demo of `ember-foxy-forms`, it showcases the kitchen sink of form controls +that we provide for you out of the box. {{#docs-demo as |demo|}} {{#demo.example name="basic-usage.hbs"}}