Quick links: Content - sections - sub sections
EN FR

To use a Wysiwyg HTML editor in your forms, you have to use the <htmleditor> element.


  <htmleditor ref="description">
	<label>Product Description</label>
  </htmleditor>

You can change the appearance of the editor, its configuration, and also the engine of the editor, by setting the attributes config and skin.

jForms uses CKEditor as default editor.

General configuration of the editors

The attribute config indicates the name of a configuration file of an editor. Its default value is default.

Configurations are declared in the section [htmleditors] in the configuration of Jelix. Here is its default content:


[htmleditors]
default.engine.name=ckeditor
ckdefault.engine.name=ckeditor
ckfull.engine.name=ckeditor
ckbasic.engine.name=ckeditor

As you can see, several configurations are possible. Here, 5 configurations : "default", "ckdefault", "ckfull"... For each configuration, you can have several parameters, which name start with the configuration name. Here, there is only one parameter defined, engine.name. It indicates the name of the editor. In fact, this name is used in a JS function name, a function that is responsible to instantiate the editor.

For each configuration, there is also several javascript files and css files to load in a web page. We are using webassets. The webassets group for htmleditor should have a name with the configuration name (here default) and a prefix jforms_htmleditor_. The default web assets are:


[webassets_common]

;...

jforms_htmleditor_default.js[]="$jelix/ckeditor5/ckeditor.js"
jforms_htmleditor_default.js[]="$jelix/js/jforms/htmleditors/ckeditor_default.js"

You can see here that we are loading the CKEditor javascript file, ckeditor.js, but also the instanciation script ckeditor_default.js.

You can also define a webassets group for each "skin" that can be used with the editor, when it supports theming. The group name has the following scheme: jforms_htmleditor_<configuration name>.skin.<skin name>.

For example, to declare webassets of the skin default for the configuration default, you create this group (which has only one CSS file):


jforms_htmleditor_default.skin.default.css="somewhere/skins/default/skin.css"

For a "silver" theme :


jforms_htmleditor_default.skin.silver.css="somewhere/skins/silver/skin.css"

Then you can use the configuration and the skin (if it exists) into a jforms file. Here we take the default configuration with the skin silver:


  <htmleditor ref="description" config="default" skin="silver">
	<label>Product description</label>
  </htmleditor>

Creating an instanciation script for an editor

Most of existing wysiwyg HTML editors can be configured, and for each different editor, the way how we configured them is different. And this configuration is made in Javascript.

jForms should know how to instantiate them.

So you have to create a javascript function which will configure the editor you want to use. This function should be in a specific javascript file and you have to indicate the url of this file in a webassets group, as you saw above.

For example, if you want to create a new configuration "ckfancy" for CKEditor, you create a file www/js/ckeditor_ckfancy.js (you can choose any name). And then you indicate it in the configuration file:


[htmleditors]
ckfancy.engine.name=ckeditor

[webassets_common]

;...


jforms_htmleditor_ckfancy.js[]="$jelix/ckeditor5/ckeditor.js"
jforms_htmleditor_ckfancy.js[]="js/ckeditor_ckfancy.js"

The javascript function you must create should have a name which follows a specific scheme jelix_<engine name>_<configuration name>(), where <engine name> is the identifier of the editor (which is written into *.engine.name), and where <configuration name> is the identifier of the configuration. So in our example, the name should be jelix_ckeditor_ckfancy(). This function receives the id of the textarea, the id of the form, the skin name and an object containing configuration values from jelix.

This last parameter contains these properties :

  • locale: the language code (valueof jApp::config()->locale)
  • basePath: the value of basePath
  • jqueryPath: The URL path to the jquery library
  • jelixWWWPath: The URL path to the jelix-www content.

Here is an example of this function, which add here a specific CSS file to wymeditor for the content to edit (this is not the skin of the editor):


function jelix_ckeditor_ckfancy(textarea_id, form_id, skin, config){

    var ckConfig = {
        toolbar: [ 'bold' ],
        language: config.locale.substr(0,2).toLowerCase()
    };

    ClassicEditor
        .create( document.querySelector( '#'+textarea_id ), ckConfig )
        .then( function(editor) {
                jQuery('#'+form_id).bind('jFormsUpdateFields', function(event){
                    editor.updateSourceElement();
                });
            } )
        .catch( function(error) {
            console.error( error );
        });
)}

Using an other editor

If you want to use an other editor, declare javascript files of this editors in the configuration of Jelix, and a configuration file for the editor.

Here is an example with TinyMCE. Careful about JS file names, it can be different.

TinyMCE


[htmleditors]
tinymceconf.engine.name = tinymce

[webassets_common]
;...
jforms_htmleditor_tinymceconf.js[]="tinymce/tinymce.js"
jforms_htmleditor_tinymceconf.js[]="js/tinymce_default.js"
jforms_htmleditor_tinymceconf.skin.default.css="tinymce/skins/default/full.css"

In js/tinymce_tinymceconf.js, create a function jelix_tinymce_tinymceconf() as indicated in the previous section. All forms where you want to use this configuration should have config="tinymceconf" on their <htmleditor> element.