[RFC] Custom Field Templates Documentation

[cdowdy]

Currently if you want to create a custom field for an extension in Bolt's backend the documentation is rather lacking.

If you want to supply simple fields ( ie: a select field) you can follow the color picker example or as @PhillippOhlandt mentioned in slack his guenther stubs for a regular text input field.

Without intimate knowledge of bolt's internals you have to do a lot of searching or an IDE search for terms.

As an example. If you want to provide the info tooltip popup

that uses font-awesome in the label nested inside your fieldset you have to search for a string similar to

info:        field.info|default('info.upload.filelist')  

Or you could also look at the _info.twig template

{% macro buic_info(label, id) %}
    {% set attributes = {
        'class':         'info-pop fa fa-info-circle',
        'data-content':  app.translator.trans(id, {}, 'infos'),
        'data-html':     true,
        'data-title':    label|trans,
    } %}
    <i{{ hattr(attributes) }}><span class="sr-only">{{ __('general.phrase.info') }}</span></i>
{% endmacro %}  

There is no documentation on how to set that info popup text in the data-content attributes object or change single or multiple words in the one provided by bolt or even if you all would want a custom field to provide the info popup.

If you want to build a "fieldset" you can open up a backened field template and see that it imports the fieldset twig template. That template imports other templates or uses the macro template with references to blocks.

The blocks in the templates have little to no documentation as to what they are meant to accomplish. Most comments are similar to:

{#=== INIT ====================================#}

or

{### Template: Listitem ###}

{% set template_item %}
    <div class="item ui-state-default">
        <div class="icon"><i class="fa fa-file-o"></i><span>%EXT_E%</span></div>
        <input type="text" class="title" value="%TITLE_A%">
        <input type="hidden" class="filename" value="%FILENAME_A%">
        <a href="#" class="remove"><i class="fa fa-times"></i></a>
        <span class="desc">%FILENAME_E%</span>
    </div>
{% endset %}  

Again without a lot of bolt internal knowledge or twig knowledge you have to do a lot of searching and deciphering where things like %FILENAME_E% are coming from. I know they are used in the loop later in the template with a replace filter. But if you just come across this you are all "huh" haha.

Blocks are also used in bolt's fields almost like variables. IE:

{% block fieldset_label_class 'col-xs-12' %}  

Typically you're used to seeing "blocks" follow a pattern similar to:

{% block fieldset_label_class %} {{ fieldset_label_class }} {% endblock fieldset_label_class %}

{# or referencing a block #}
{% block fieldset_label_class %} block(fieldset_label_class) {% endblock fieldset_label_class %}

This though is a minor nit :). It's just confusing when you first come across it.

If you try to match Bolt's css styles in your field and you insert buttons you may insert a button that triggers the ajax save event or an upload event. Only way you'd know this is if you a) accidentally named a button that has an even listener or b) look at the provided bolt javascript libraries for the backend. This is less a problem if you open up your dev tools and look at the event listeners or classes attached to them.

If you want to create a field that allows multiple uploads you have to find a template that does and try your hand at copy pasta haha or search for dropzone documentation on the interwebs

Other Things to note:

For newcomers having docs as to what to replace. For instance say I have a custom field named "hours" do I in the example below replace "filelist" or whatever the field i'm copying with my field name of "hours".

info:        field.info|default('info.upload.filelist')  

These things are obivious to advanced users or people who've built the backend templates. To someone coming across you don't know if adding or removing that would be beneficial or harmful.

Things that would be "nice" to have

Time is always a limiting factor and there already is a lot on your plates so I'm not expecting a lot to be done right away or in the near future but it would be nice to have

• advanced docs on more complex fields - multiple file upload as an example
  • generic examples of these fields would be good.
• reserved class names used by bolt to fire events
• basic style guide as to "here is the classes you should use to build your field"
• js events or libraries included by bolt available to the developer

or just a little more in depth documentation inside the templates that are currently used.

As An Aside and nothing to do with field creation :)

the backend has sr-only classes. These classes are completely skipped over by a screen reader such as nvda or chromevox. Using this you are presented with whatever is used as the placeholder then you can tab into the buttons below the input. for instance a file upload filed. The only thing read by the screen reading software is the placeholder and the upload file, select from server and stack buttons. There is no indication as to what field you are actually on and the info popup is completely skipped.

This has to do with a combination of the sr-only class and the legend and label tags being nearly identical.