Text Editor (customisations)

Words of warning

Some of these customisations require you to edit the code or the settings files. The syntax is in Python or Javascript and every punctuation mark, separator are thus very important. The case is also important. X is different from x. Using the wrong syntax or case is likely to cause errors that will temporarily break part or all of your site and might be difficult to debug.

The customisations marked as 'intermediate' level can be carried out by someone familiar with a scripting language. The ones marked as 'advanced' should be undertaken only be an experienced software developer.

It is highly recommended that you back up your data before making any change. It is also strongly recommended that you take careful note of the location of the files you change and copy the original sample of the code (and files) that you are about to change so you can easily revert to them without having to restore your site from backups.

Archetype is a flexible framework which has been customised for very different types of texts and corpora. However in order to keep your instance upgradable and repairable you should never edit any code within the docker container or outside of the digipal_project folder.

Types of texts (since version 1.2.2)

Level: advanced (requires good programming skills)

TODO

The tool bar (since version 2.1.1)

Level: intermediate

When you click the pencil icon on the Text Editor to move to edit mode, a new toolbar appear on top of the text box. It contains additional buttons to mark up selected parts of the text.

To customise the toolbar, open local_settings.py (or create it if it doesn't exist yet, it should be located under the /digipal_project folder, alongside settings.py) and edit or add the following settings variable:

TEXT_EDITOR_OPTIONS_CUSTOM = {
    'toolbars': {
        'default': 'psclear undo redo pssave | psconvert | psclause | psClauseSecondary | psperson | pslocation | psex pssupplied psdel | code ',
    }
}

In that variable, the string: 'psclear undo redo pssave | psconvert | psclause | psClauseSecondary | psperson | pslocation | psex pssupplied psdel | code ' is a list of buttons. There is a code for each button, for instance psclear is the 'cross' icon that is used to clear a mark up, 'undo' is the undo button, etc. '|' represents a vertical separator to visually group buttons in the toolbar.

Since version 2.2.1 you can also customise the toolbar for any type of texts. For instance, if you only need an undo and redo button while editing the translations, use the following definition:

TEXT_EDITOR_OPTIONS_CUSTOM = {
    'toolbars': {
        'default': 'psclear undo redo pssave | psconvert | psclause | psClauseSecondary | psperson | pslocation | psex pssupplied psdel | code ',
        'translation': 'undo redo',
    }
}

In that example transcriptions will use the 'default' toolbar because there is 'transcription' toolbar defined.

Here is the list of some commonly used buttons:

• psclear: clear the markup
• undo: undo the last action
• redo: redo the last action
• pssave: save the text to the database
• psconvert: convert notational conventions into mark up, e.g. | into line break, 7 into a tironian sign, ...
• psclause: primary diplomatic clauses
• psClauseSecondary: secondary diplomatic clauses
• psperson: name or title of a person
• pslocation: a place name
• psex: expansion
• pssupplied: supplied text
• psdel: deleted text
• code: HTML editor

Custom mark up buttons (since version 2.2.1)

Level: intermediate

TEXT_EDITOR_OPTIONS_CUSTOM = {
    'buttons': {
        'mynation': {'label': 'Nation', 'xml': '<span data-dpt="country" data-dpt-type="nation">{}</span>'},
        'mystate': {'label': 'State', 'xml': '<span data-dpt="region" data-dpt-type="state">{}</span>'},
        'myplaces': {'label': 'Places', 'buttons': ['mynation', 'mystate']},
    }
    'toolbars': {
        'default': 'psclear undo redo pssave | myplaces ',
    }
}

The above configuration in your local_settings.py adds three new buttons to tag regions and states in the Text Editor.

• mynation: a button to mark up a Nation name
• mystate: a button to mark up a State name
• myplaces: a dropdown to group mynation and mystate buttons on the toolbar

The 'xml' string under each button is used to specify your own mark up. For instance:

'xml': '<span data-dpt="country" data-dpt-type="nation">{}</span>'

The mark up will be inserted as it is, except for {} which will be substituted with the the part of the text you have selected before clicking the button.

Note that the mark up should be:

• a well formed XML fragment: any open tag should be closed, elements cannot overlap, ...;
• must be valid HTML: so you can't use TEI directly for instance, but you can design a TEI-inspired schema like in the example above;

Read on if you want to know how to style your newly created mark up elements.

The style of the texts (since version 1.2.2)

Level: intermediate

It is possible to customise the appearance of the text using CSS stylesheets. The system is very granular and modular, you can apply a specific style to each mark-up element, for each mode (viewing or editing), for each content type (e.g. translation, transcription) and for each display setting (see section below for intro about display settings).

INCOMPLETE, TO BE DOCUMENTED

The style of new mark up (since version 1.2.2)

Level: intermediate

Create or edit the following file to customise the appearance of the mark-up elements in the Text Editor:

customisations/static/digipal_text/viewer/tinymce_custom.css

For instance, to following styles will highlight the Nation and State markup in green in the Editing mode and add a small label 'Nation' or 'State' above them in the text.

.mce-content-body span[data-dpt=country],
.mce-content-body span[data-dpt=region]
{
    background-color: rgba(0,255,100,0.35);
}

.mce-content-body span[data-dpt=country][data-dpt-type=nation]:before {
    content: "Nation";
}

.mce-content-body span[data-dpt=region][data-dpt-type=state]:before {
    content: "State";
}

For the changes in the custom styles to be effective in your Docker site you need to restart the App with Kitematic. Then next time you go to the Text Editor web page force the web browser to load up you styles by pressing CTRL-F5 or (CMD-F5 on a mac).

If you are not using docker, you'll need to run the following command after each modification:

python manage.py collectstatic --noinput

Then hard-refresh the web page with CTRL-F5 or (CMD-F5 on a mac).

conversions of notational shorthands

Level: advanced

TODO

Display settings (since version 1.2.2)

Level: advanced

TODO