Tips for Developers

Extensive use it made of autocompletion, in-place edition and generic ajax-filled modals, and we're trying to standardize things using some generic JS functions in the top-level html structure (currently in the app.blade.php layout).

Autocompletion

Autocompletion fields are data-driven and based on HTML5's datalist functionality. To use the provided autocompletion functionality, define the following attributes in your input field:

• data-ac="autocompletion source URL", e.g. data-ac="/actor/autocomplete",
• name="database column name to change", e.g. name="actor_id", and
• list="ajaxDatalist". This is what triggers the HTML5 datalist functionality - you don't need to care about the actual datalist location and content, because it's just a generic placeholder for Ajax content.

By default, the autocompletion source is configured to return { key: <an index>, value: <a value> }. Value is usually the "human readable" data displayed for selection, but often this data is not the data sent to the database. Systematically key is sent to the database.

So, in principle, as soon as you select a human readable item from your suggestions list, it will be replaced by key in the input field.

This is in fact not a problem for (correctly designed) in-place edited data, because the data is refreshed as soon as the item is selected, whereby the key is just flashed during the refresh time.

For static forms, such as creation forms, if you want to see the human readable value, and send key to the database you need to:

• provide a hidden input field with the required name attribute,
• insert the following attribute in the visible input field: data-actarget="database column name". Don't set the name attribute in the visible input field, nor an id with that name to avoid confusing the autocompletion functionality.

For example, to insert/change an actor from a visible input field:

• <input type="hidden" name="actor_id">
• <input type="text" list="ajaxDatalist" data-ac="/actor/autocomplete" data-actarget="actor_id">

Moreover, data-actarget is used to identify the visible input field for displaying validation error messages linked to the name of the hidden field.

In-place Edition

Most of the data displayed in modals is in-place editable. The editable data is displayed in input fields that have no graphic attributes, so their content fits seamlessly with the other content. These input fields have the class .noformat. Such input fields are listened to for changes: as soon as you start typing in one, its background warns you, and the new content is sent to the server and refreshed as soon as you leave the input field (by clicking anywhere outside the field).

To identify what record to modify in the database, use the attribute data-id="database record id" in:

• the parent <tr> when the input field is displayed in a list of similar items (e.g. list of tasks),
• the parent <table> in a window related to a single item (e.g. a modal showing the actor details). (For the moment, this functionality is thus implemented only in tables.)

Generic Ajax-filled Modals

The top-level structure has an empty modal with id="ajaxModal" to which all the above functionality is attached. To implement that modal, use the following attributes in an <a> trigger element (buttons are usable the same way - see Bootstrap 4 documentation for further details):

• data-target="#ajaxModal",
• href="route generating the html to display in the modal", e.g. href="/matter/1/edit",
• data-resource="REST resource for the modal", e.g. data-resource="/matter/" (note the ending "/")