Improving usability

ajax-attributes-api.md

@@ -21,7 +21,7 @@ Attribute | Description
 `data-request-redirect` | specifies a URL to redirect the browser after the successful AJAX request.
 `data-request-url` | specifies a URL to which the request is sent. default: `window.location.href`
 `data-request-update` | specifies a list of partials and page elements (CSS selectors) to update. The format is as follows: `partial: selector, partial: selector`. Usage of quotes is required in some cases, for example: `'my-partial': '#myelement'`. If the selector string is prepended with the `@` symbol, the content received from the server will be appended to the element, instead of replacing the existing content. If the selector string is prepended with the `^` symbol, the content will be prepended instead.
-`data-request-ajax-global` | false by default. Set true to enable jQuery [ajax events](http://api.jquery.com/category/ajax/global-ajax-event-handlers/) globally : `ajaxStart`, `ajaxStop`, `ajaxComplete`, `ajaxError`, `ajaxSuccess` and `ajaxSend`.
+`data-request-ajax-global` | `false` by default. Set `true` to enable jQuery [ajax events](https://api.jquery.com/category/ajax/global-ajax-event-handlers/) globally : `ajaxStart`, `ajaxStop`, `ajaxComplete`, `ajaxError`, `ajaxSuccess` and `ajaxSend`.
 `data-request-data` | specifies additional POST parameters to be sent to the server. The format is following: `var: value, var: value`. Use quotes if needed: `var: 'some string'`. The attribute can be used on the triggering element, for example on the button that also has the `data-request` attribute, on the closest element of the triggering element and on the parent form element. The framework merges values of the `data-request-data` attributes. If the attribute on different elements defines parameters with the same name, the framework uses the following priority: the triggering element `data-request-data`, the closer parent elements `data-request-data`, the form input data.
 `data-request-before-update` | specifies JavaScript code to execute directly before the page contents are updated. Inside the JavaScript code you can access the following variables: `this` (the page element triggered the request), the `context` object, the `data` object received from the server, the `textStatus` text string, and the `jqXHR` object.
 `data-request-success` | specifies JavaScript code to execute after the request is successfully completed. Inside the JavaScript code you can access the following variables: `this` (the page element triggered the request), the `context` object, the `data` object received from the server, the `textStatus` text string, and the `jqXHR` object.
@@ -46,38 +46,52 @@ Element | Event
 <a name="data-attribute-examples"></a>
 ## Usage examples
 
-Trigger the `onCalculate` handler when the form is submitted. Update the element with the identifier "result"` with the **calcresult** partial:
+Trigger the `onCalculate` handler when the form is submitted. Update the element with the identifier "result" with the **calcresult** partial:
 
-    <form data-request="onCalculate" data-request-update="calcresult: '#result'">
+```html
+<form data-request="onCalculate" data-request-update="calcresult: '#result'">
+```
 
 Request a confirmation when the Delete button is clicked before the request is sent:
 
-    <form ... >
-        ...
-        <button data-request="onDelete" data-request-confirm="Are you sure?">Delete</button>
+```html
+<form ... >
+    ...
+    <button data-request="onDelete" data-request-confirm="Are you sure?">Delete</button>
+```
 
 Redirect to another page after the successful request:
 
-    <form data-request="onLogin" data-request-redirect="/admin">
+```html
+<form data-request="onLogin" data-request-redirect="/admin">
+```
 
 Show a popup window after the successful request:
 
-    <form data-request="onLogin" data-request-success="alert('Yay!')">
+```html
+<form data-request="onLogin" data-request-success="alert('Yay!')">
+```
 
 Send a POST parameter `mode` with a value `update`:
 
-    <form data-request="onUpdate" data-request-data="mode: 'update'">
+```html
+<form data-request="onUpdate" data-request-data="mode: 'update'">
+```
 
 Send a POST parameter `id` with value `7` across multiple elements:
 
-    <div data-request-data="id: 7">
-        <button data-request="onDelete">Delete</button>
-        <button data-request="onSave">Update</button>
-    </div>
+```html
+<div data-request-data="id: 7">
+    <button data-request="onDelete">Delete</button>
+    <button data-request="onSave">Update</button>
+</div>
+```
 
 Including [file uploads](../services/request-input#files) with a request:
 
-    <form data-request="onSubmit" data-request-files>
-        <input type="file" name="photo" accept="image/*" />
-        <button type="submit">Submit</button>
-    </form>
+```html
+<form data-request="onSubmit" data-request-files>
+    <input type="file" name="photo" accept="image/*" />
+    <button type="submit">Submit</button>
+</form>
+```

ajax-extras.md

@@ -27,21 +27,25 @@ When an AJAX request starts the `ajaxPromise` event is fired that displays the i
 
 You may specify the `data-request-validate` attribute on a form to enable validation features.
 
-    <form
-        data-request="onSubmit"
-        data-request-validate>
-        <!-- ... -->
-    </form>
+```html
+<form
+    data-request="onSubmit"
+    data-request-validate>
+    <!-- ... -->
+</form>
+```
 
 <a name="throw-validation-exception"></a>
 ### Throwing a validation error
 
 In the server side AJAX handler you may throw a [validation exception](../services/error-log#validation-exception) using the `ValidationException` class to make a field invalid, where the first argument is an array. The array should use field names for the keys and the error messages for the values.
 
-    function onSubmit()
-    {
-        throw new ValidationException(['name' => 'You must give a name!']);
-    }
+```php
+function onSubmit()
+{
+    throw new ValidationException(['name' => 'You must give a name!']);
+}
+```
 
 > **NOTE**: You can also pass an instance of the [validation service](../services/validation) as the first argument of the exception.
 
@@ -50,76 +54,92 @@ In the server side AJAX handler you may throw a [validation exception](../servic
 
 Inside the form, you may display the first error message by using the `data-validate-error` attribute on a container element. The content inside the container will be set to the error message and the element will be made visible.
 
-    <div data-validate-error></div>
+```html
+<div data-validate-error></div>
+```
 
 To display multiple error messages, include an element with the `data-message` attribute. In this example the paragraph tag will be duplicated and set with content for each message that exists.
 
-    <div class="alert alert-danger" data-validate-error>
-        <p data-message></p>
-    </div>
+```html
+<div class="alert alert-danger" data-validate-error>
+    <p data-message></p>
+</div>
+```
 
 To add custom classes on AJAX invalidation, hook into the `ajaxInvalidField` and `ajaxPromise` JS events.
 
-    $(window).on('ajaxInvalidField', function(event, fieldElement, fieldName, errorMsg, isFirst) {
-        $(fieldElement).closest('.form-group').addClass('has-error');
-    });
+```js
+$(window).on('ajaxInvalidField', function(event, fieldElement, fieldName, errorMsg, isFirst) {
+    $(fieldElement).closest('.form-group').addClass('has-error');
+});
 
-    $(document).on('ajaxPromise', '[data-request]', function() {
-        $(this).closest('form').find('.form-group.has-error').removeClass('has-error');
-    });
+$(document).on('ajaxPromise', '[data-request]', function() {
+    $(this).closest('form').find('.form-group.has-error').removeClass('has-error');
+});
+```
 
 <a name="field-errors"></a>
 ### Displaying errors with fields
 
 Alternatively, you can show validation messages for individual fields by defining an element that uses the `data-validate-for` attribute, passing the field name as the value.
 
-    <!-- Input field -->
-    <input name="phone" />
+```html
+<!-- Input field -->
+<input name="phone" />
 
-    <!-- Validation message for the field -->
-    <div data-validate-for="phone"></div>
+<!-- Validation message for the field -->
+<div data-validate-for="phone"></div>
+```
 
 If the element is left empty, it will be populated with the validation text from the server. Otherwise you can specify any text you like and it will be displayed instead.
 
-    <div data-validate-for="phone">
-        Oops.. phone number is invalid!
-    </div>
+```html
+<div data-validate-for="phone">
+    Oops.. phone number is invalid!
+</div>
+```
 
 <a name="loader-button"></a>
 ## Loading button
 
 When any element contains the `data-attach-loading` attribute, the CSS class `wn-loading` will be added to it during the AJAX request. This class will spawn a *loading spinner* on button and anchor elements using the `:after` CSS selector.
 
-    <form data-request="onSubmit">
-        <button data-attach-loading>
-            Submit
-        </button>
-    </form>
-
-    <a
-        href="#"
-        data-request="onDoSomething"
-        data-attach-loading>
-        Do something
-    </a>
+```html
+<form data-request="onSubmit">
+    <button data-attach-loading>
+        Submit
+    </button>
+</form>
+
+<a
+    href="#"
+    data-request="onDoSomething"
+    data-attach-loading>
+    Do something
+</a>
+```
 
 <a name="ajax-flash"></a>
 ## Flash messages
 
 Specify the `data-request-flash` attribute on a form to enable the use of flash messages on successful AJAX requests.
 
-    <form
-        data-request="onSuccess"
-        data-request-flash>
-        <!-- ... -->
-    </form>
+```html
+<form
+    data-request="onSuccess"
+    data-request-flash>
+    <!-- ... -->
+</form>
+```
 
 Combined with use of the `Flash` facade in the event handler, a flash message will appear after the request finishes.
 
-    function onSuccess()
-    {
-        Flash::success('You did it!');
-    }
+```php
+function onSuccess()
+{
+    Flash::success('You did it!');
+}
+```
 
 To remain consistent with AJAX based flash messages, you can render a [standard flash message](../markup/tag-flash) when the page loads by placing this code in your page or layout.
 
@@ -139,47 +159,51 @@ To remain consistent with AJAX based flash messages, you can render a [standard
 
 Below is a complete example of form validation. It calls the `onDoSomething` event handler that triggers a loading submit button, performs validation on the form fields, then displays a successful flash message.
 
-    <form
-        data-request="onDoSomething"
-        data-request-validate
-        data-request-flash>
+```html
+<form
+    data-request="onDoSomething"
+    data-request-validate
+    data-request-flash>
 
-        <div>
-            <input name="name" />
-            <span data-validate-for="name"></span>
-        </div>
+    <div>
+        <input name="name" />
+        <span data-validate-for="name"></span>
+    </div>
 
-        <div>
-            <input name="email" />
-            <span data-validate-for="email"></span>
-        </div>
+    <div>
+        <input name="email" />
+        <span data-validate-for="email"></span>
+    </div>
 
-        <button data-attach-loading>
-            Submit
-        </button>
+    <button data-attach-loading>
+        Submit
+    </button>
 
-        <div class="alert alert-danger" data-validate-error>
-            <p data-message></p>
-        </div>
+    <div class="alert alert-danger" data-validate-error>
+        <p data-message></p>
+    </div>
 
-    </form>
+</form>
+```
 
 The AJAX event handler looks at the POST data sent by the client and applies some rules to the validator. If the validation fails, a `ValidationException` is thrown, otherwise a `Flash::success` message is returned.
 
-    function onDoSomething()
-    {
-        $data = post();
+```php
+function onDoSomething()
+{
+    $data = post();
 
-        $rules = [
-            'name' => 'required',
-            'email' => 'required|email',
-        ];
+    $rules = [
+        'name' => 'required',
+        'email' => 'required|email',
+    ];
 
-        $validation = Validator::make($data, $rules);
+    $validation = Validator::make($data, $rules);
 
-        if ($validation->fails()) {
-            throw new ValidationException($validation);
-        }
-
-        Flash::success('Jobs done!');
+    if ($validation->fails()) {
+        throw new ValidationException($validation);
     }
+
+    Flash::success('Jobs done!');
+}
+```