A simple extension for bolt.cm to easily create notes inside a text

Gabriele deb0be18b1 update testing 2 years ago
config ab60d88b8a Initial commit 2 years ago
screenshots ab60d88b8a Initial commit 2 years ago
src 97b81de935 corrected tests 2 years ago
templates ab60d88b8a Initial commit 2 years ago
tests deb0be18b1 update testing 2 years ago
web ab60d88b8a Initial commit 2 years ago
.gitignore ab60d88b8a Initial commit 2 years ago
CHANGELOG.md 97b81de935 corrected tests 2 years ago
README.md ab60d88b8a Initial commit 2 years ago
bolt_notes.png ab60d88b8a Initial commit 2 years ago
composer.json deb0be18b1 update testing 2 years ago
phpunit.xml.dist deb0be18b1 update testing 2 years ago

README.md

Bolt Notes

A simple extension to easily insert notes into the text and have them appear wherever you want. This extension provide two mechanisms: a Twig Function and a Twig Filter.

Usage

Function

To use it just put note(text) in your template or content:

Hello this is random text{{ note('This is a note') }} just ignore me, please.

In the location where you put the function, the only content shown will be a number, with a link to the note between two delimeters, which by default are [ and ].

You probably would like to use this directly from the content editor, in each individual piece of content, and not just in the templates. So remember to use allowtwig: true for every field of your contenttypes.yml in which you want to use it. For instance:

entries:
    name: entries
    singular_name: entry
    fields:
        [..]
        body:
            type: html
            height: 300px
            allowtwig: true

Then put notes() where you want to show the collected notes:

{{ notes() }}

Usually it would be in your templates, for example after record.body or in a sidebar.

Filter

You can use the notes filter just like any other filter. It will take the input and replace all the notes found between markers. You would want to use it only in your templates and not in the content editor.

{{ record.body|notes }}

Configuration

In the configuration file you can change the delimeter and the marker of the note. The delimeter is what will appear after the trasformation and will contain the calculated number of the note, while the marker is used, only by the filter, to find the notes.

delimeter:
    start: '['
    end:   ']'

marker:
    start: '[['
    end:   ']]'
    
# complete example
# this is a text[[an insightful note]]
# will become
# this is a text[1]
# of course the 1 could be any other number depending on the other notes already present

For example, you could change the delimeters in <sup> and </sup> to have the link to the note appear as a small number in the top part. While you could change the marker in anything you want, but you may want to think about choosing a marker that could degrade gracefully, if you ever need to stop using the extension.

There are a notes.css stylesheet and a notes.twig template that you can overwrite in the usual matter. In the default template the text of the note is shown through the filter raw, which is to say not escaped. This allow you to put link in the text of the note. You may want to change it, if you don't need to use it.

Known limitations

The notes created with the function are grouped in one unique group. So you would want to show them only for individual records (ie. not in a listing_template). If you need to use them in such manner you would want to use the filter instead.