docs: FetchIt docs in english (#750)

modx-pro · Nov 11, 2023 · 3d1eef3 · 3d1eef3
1 parent 73d3fcf
commit 3d1eef3
Show file tree

Hide file tree

Showing 43 changed files with 2,427 additions and 21 deletions.
diff --git a/docs/components/fetchit/introduction.md b/docs/components/fetchit/introduction.md
diff --git a/docs/en/components/fetchit/examples/form/bootstrap.md b/docs/en/components/fetchit/examples/form/bootstrap.md
@@ -0,0 +1,52 @@
+# Bootstrap
+
+Suppose your form looks like this:
+
+```html
+<form class="row g-3">
+  <div class="col-md-4">
+    <label for="name" class="form-label">First name</label>
+    <input type="text" class="form-control" id="name" value="">
+    <div class="invalid-feedback"></div>
+  </div>
+  <div class="col-md-4">
+    <label for="email" class="form-label">Last name</label>
+    <input type="email" class="form-control" id="email" value="">
+    <div class="invalid-feedback"></div>
+  </div>
+  <div class="col-12">
+    <button class="btn btn-primary" type="submit">Submit form</button>
+  </div>
+</form>
+```
+
+To prepare, you will need to do the following:
+
+1. Add `data-error="*"` attributes for elements that will be displayed with the error text.
+2. For FormIt compatibility, placeholders with values and errors must be specified.
+3. Since Bootstrap needs to add `is-invalid` class when invalid status, you need to specify `is-invalid` in the `fetchit.frontend.input.invalid.class` system setting, but in this case this value is the default.
+
+<!--@include: ../../parts/action.info.md-->
+
+```modx
+<form class="row g-3"> // [!code --]
+<form action="[[~[[*id]]]]" class="row g-3"> // [!code ++]
+  <div class="col-md-4">
+    <label for="name" class="form-label">First name</label>
+    <input type="text" class="form-control" id="name" name="name" value=""> // [!code --]
+    <input type="text" class="form-control" id="name" name="name" value="[[+fi.name]]"> // [!code ++]
+    <div class="invalid-feedback"></div> // [!code --]
+    <div class="invalid-feedback" data-error="name">[[+fi.error.name]]</div> // [!code ++]
+  </div>
+  <div class="col-md-4">
+    <label for="email" class="form-label">Last name</label>
+    <input type="email" class="form-control" id="email" name="email" value=""> // [!code --]
+    <input type="email" class="form-control" id="email" name="email" value="[[+fi.email]]"> // [!code ++]
+    <div class="invalid-feedback"></div> // [!code --]
+    <div class="invalid-feedback" data-error="email">[[+fi.error.email]]</div> // [!code ++]
+  </div>
+  <div class="col-12">
+    <button class="btn btn-primary" type="submit">Submit form</button>
+  </div>
+</form>
+```
diff --git a/docs/en/components/fetchit/examples/form/bulma.md b/docs/en/components/fetchit/examples/form/bulma.md
@@ -0,0 +1,74 @@
+# Bulma
+
+If your layout is implemented on the [Bulma](https://bulma.io/) framework, the markup most likely looks like this:
+
+```html
+<form>
+  <div class="field">
+    <label class="label">Username</label>
+    <div class="control">
+      <input class="input" type="text" name="name" value="">
+    </div>
+    <p class="help is-danger"></p>
+  </div>
+
+  <div class="field">
+    <label class="label">Email</label>
+    <div class="control">
+      <input class="input" type="email" name="email" value="">
+    </div>
+    <p class="help is-danger"></p>
+  </div>
+
+  <div class="field is-grouped">
+    <div class="control">
+      <button type="submit" class="button is-link">Submit</button>
+    </div>
+    <div class="control">
+      <button type="reset" class="button is-link is-light">Cancel</button>
+    </div>
+  </div>
+</form>
+```
+
+To prepare, you will need to do the following:
+
+1. Add `data-error="*"` attributes for elements that will be displayed with the error text.
+2. For FormIt compatibility, placeholders with values and errors must be specified.
+3. In Bulma, invalid status is specified by the `is-danger` css class, so you need to specify it in the `fetchit.frontend.input.invalid.class` system setting.
+
+<!--@include: ../../parts/action.info.md-->
+
+```modx
+<form> // [!code --]
+<form action="[[~[[*id]]]]" method="post"> // [!code ++]
+  <div class="field">
+    <label class="label">Username</label>
+    <div class="control">
+      <input class="input" type="text" name="name" value=""> // [!code --]
+      <input class="input" type="text" name="name" value="[[+fi.name]]"> // [!code ++]
+    </div>
+    <p class="help is-danger"></p> // [!code --]
+    <p class="help is-danger" data-error="name">[[+fi.error.name]]</p> // [!code ++]
+  </div>
+
+  <div class="field">
+    <label class="label">Email</label>
+    <div class="control">
+      <input class="input" type="email" name="email" value=""> // [!code --]
+      <input class="input" type="email" name="email" value="[[+fi.email]]"> // [!code ++]
+    </div>
+    <p class="help is-danger"></p> // [!code --]
+    <p class="help is-danger" data-error="email">[[+fi.error.email]]</p> // [!code ++]
+  </div>
+
+  <div class="field is-grouped">
+    <div class="control">
+      <button type="submit" class="button is-link">Submit</button>
+    </div>
+    <div class="control">
+      <button type="reset" class="button is-link is-light">Cancel</button>
+    </div>
+  </div>
+</form>
+```
diff --git a/docs/en/components/fetchit/examples/form/cirrus.md b/docs/en/components/fetchit/examples/form/cirrus.md
@@ -0,0 +1,66 @@
+# Cirrus CSS
+
+In [Cirrus CSS](https://cirrus-ui.netlify.app/) invalid state should be specified with two classes: `input-error` and `text-danger`, FetchIt takes such cases into account as well.
+
+```html
+<form>
+  <div class="row">
+    <div class="col-12">
+      <label>Name</label>
+      <input type="text" name="name" value="">
+      <small class="text-danger"></small>
+    </div>
+  </div>
+  <div class="row">
+    <div class="col-12">
+      <label>Email</label>
+      <input type="email" name="email" value="">
+      <small class="text-danger"></small>
+    </div>
+  </div>
+  <div class="row">
+    <div class="col-12">
+      <input type="submit" class="btn-primary">
+      <input type="reset" class="btn-default">
+    </div>
+  </div>
+</form>
+```
+
+To prepare, you will need to do the following:
+
+1. Add `data-error="*"` attributes for elements that will be displayed with the error text.
+2. For FormIt compatibility, placeholders with values and errors must be specified.
+3. In Cirrus CSS, invalid status is specified by two classes `input-error` and `text-danger`, so specify them in the `fetchit.frontend.input.invalid.class` system setting separated by a space.
+
+<!--@include: ../../parts/action.info.md-->
+
+```modx
+<form> // [!code --]
+<form action="[[~[[*id]]]]" method="post"> // [!code ++]
+  <div class="row">
+    <div class="col-12">
+      <label>Name</label>
+      <input type="text" name="name" value=""> // [!code --]
+      <input type="text" name="name" value="[[+fi.name]]"> // [!code ++]
+      <small class="text-danger"></small> // [!code --]
+      <small class="text-danger" data-error="name">[[+fi.error.name]]</small> // [!code ++]
+    </div>
+  </div>
+  <div class="row">
+    <div class="col-12">
+      <label>Email</label>
+      <input type="email" name="email" value=""> // [!code --]
+      <input type="email" name="email" value="[[+fi.email]]"> // [!code ++]
+      <small class="text-danger"></small> // [!code --]
+      <small class="text-danger" data-error="email">[[+fi.error.email]]</small> // [!code ++]
+    </div>
+  </div>
+  <div class="row">
+    <div class="col-12">
+      <input type="submit" class="btn-primary">
+      <input type="reset" class="btn-default">
+    </div>
+  </div>
+</form>
+```
diff --git a/docs/en/components/fetchit/examples/form/fomantic.md b/docs/en/components/fetchit/examples/form/fomantic.md
@@ -0,0 +1,73 @@
+# Fomantic-UI
+
+The example with the CSS framework [Fomantic-UI](https://fomantic-ui.com/) is more interesting, because the CSS invalid class should be added to the parent element, not the input field. There is a `frontend.custom.invalid.class` setting just for such cases:
+
+```html
+<form class="ui form">
+  <div class="field"> // [!code warning]
+    <label>Name</label>
+    <input type="text" name="name">
+    <span class="ui error text"></span>
+  </div>
+  <div class="field"> // [!code warning]
+    <label>Email</label>
+    <input type="text" name="email">
+    <span class="ui error text"></span>
+  </div>
+  <button class="ui button" type="submit">Submit</button>
+  <button class="ui button" type="reset">Reset</button>
+</form>
+```
+
+To prepare, you will need to do the following:
+
+1. Add `data-custom="*"` attributes for parent elements and specifying the `error` value in the `fetchit.frontend.custom.invalid.class` system setting.
+2. Add `data-error="*"` attributes for elements that will be displayed with the error text.
+3. For FormIt compatibility, placeholders with values and errors must be specified.
+
+<!--@include: ../../parts/action.info.md-->
+
+::: code-group
+
+```modx [Changes]
+<form class="ui form"> // [!code --]
+<form action="[[~[[*id]]]]" class="ui form"> // [!code ++]
+  <div class="field"> // [!code --]
+  <div class="field" data-custom="name"> // [!code ++]
+    <label>Name</label>
+    <input type="text" name="name"> // [!code --]
+    <input type="text" name="name" value="[[+fi.name]]"> // [!code ++]
+    <span class="ui error text"></span> // [!code --]
+    <span data-error="name" class="ui error text">[[+fi.error.name]]</span> // [!code ++]
+  </div>
+  <div class="field"> // [!code --]
+  <div class="field" data-custom="email"> // [!code ++]
+    <label>Email</label>
+    <input type="text" name="email"> // [!code --]
+    <input type="text" name="email" value="[[+fi.email]]"> // [!code ++]
+    <span class="ui error text"></span> // [!code --]
+    <span data-error="email" class="ui error text">[[+fi.error.email]]</span> // [!code ++]
+  </div>
+  <button class="ui button" type="submit">Submit</button>
+  <button class="ui button" type="reset">Reset</button>
+</form>
+```
+
+```modx [Finished markup]
+<form action="[[~[[*id]]]]" class="ui form">
+  <div class="field" data-custom="name">
+    <label>Name</label>
+    <input type="text" name="name" value="[[+fi.name]]">
+    <span data-error="name" class="ui error text">[[+fi.error.name]]</span>
+  </div>
+  <div class="field" data-custom="email">
+    <label>Email</label>
+    <input type="text" name="email" value="[[+fi.email]]">
+    <span data-error="email" class="ui error text">[[+fi.error.email]]</span>
+  </div>
+  <button class="ui button" type="submit">Submit</button>
+  <button class="ui button" type="reset">Reset</button>
+</form>
+```
+
+:::
diff --git a/docs/en/components/fetchit/examples/form/index.md b/docs/en/components/fetchit/examples/form/index.md
@@ -0,0 +1,12 @@
+# Form Layouts
+
+Below is a list of the form markup of popular CSS frameworks.
+
+- [Bootstrap](/en/components/fetchit/examples/form/bootstrap)
+- [Bulma](/en/components/fetchit/examples/form/bulma)
+- [UIkit](/en/components/fetchit/examples/form/uikit)
+- [Fomantic-UI](/en/components/fetchit/examples/form/fomantic)
+- [Pico.css](/en/components/fetchit/examples/form/pico)
+- [Cirrus CSS](/en/components/fetchit/examples/form/cirrus)
+- [turretcss](/en/components/fetchit/examples/form/turretcss)
+- [Vanilla](/en/components/fetchit/examples/form/vanilla)
diff --git a/docs/en/components/fetchit/examples/form/pico.md b/docs/en/components/fetchit/examples/form/pico.md
@@ -0,0 +1,43 @@
+# Pico.css
+
+With the [Pico.css](https://picocss.com/) framework everything is much simpler, because the `aria-invalid` attribute controls the invalid state, and our component adds it automatically. Let's look at a small example.
+
+```html
+<form>
+  <label>
+    Name
+    <input type="text" name="name">
+  </label>
+  <label>
+    Email
+    <input type="email" name="email">
+  </label>
+  <button type="submit">Submit</button>
+</form>
+```
+
+To prepare, you will need to do the following:
+
+1. Add text elements with attributes `data-error="*"` to be displayed with the error text.
+2. For FormIt compatibility, placeholders with values and errors must be specified.
+
+<!--@include: ../../parts/action.info.md-->
+
+```modx
+<form> // [!code --]
+<form action="[[~[[*id]]]]"> // [!code ++]
+  <label>
+    Name
+    <input type="text" name="name"> // [!code --]
+    <input type="text" name="name" value="[[+fi.name]]"> // [!code ++]
+    <small data-error="name">[[+fi.error.name]]</small> // [!code ++]
+  </label>
+  <label>
+    Email
+    <input type="email" name="email"> // [!code --]
+    <input type="email" name="email" value="[[+fi.email]]"> // [!code ++]
+    <small data-error="email">[[+fi.error.email]]</small> // [!code ++]
+  </label>
+  <button type="submit">Submit</button>
+</form>
+```