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 Wymeditor 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=wymeditor
wymbasic.engine.name=wymeditor
ckdefault.engine.name=ckeditor
ckfull.engine.name=ckeditor
ckbasic.engine.name=ckeditor

As you can see, several configurations are possible. Here, 5 configurations : "default", "wymbasic", "ckdefault"... 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 instanciate 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/wymeditor/jquery.wymeditor.js"
jforms_htmleditor_default.js[]="$jelix/js/jforms/htmleditors/wymeditor_default.js"
jforms_htmleditor_default.require=jquery

You can see here that we are loading the Wymeditor javascript file, jquery.wymeditor.js, but also the instanciation script wymeditor_default.js.

For WymEditor, there is also a webassets group for each "skin" that can be used with the editor. For some other editor that support theming, you can also declare such group. 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="$jelix/wymeditor/skins/default/skin.css"

To use the "skin" silver of Wymeditor, you declare:


jforms_htmleditor_default.skin.silver.css="$jelix/wymeditor/skins/silver/skin.css"

For the ckfull configuraiton, you'll have :


[webassets_common]

jforms_htmleditor_ckfull.js[]="$jelix/ckeditor/ckeditor.js"
jforms_htmleditor_ckfull.js[]="$jelix/js/jforms/htmleditors/ckeditor_full.js"

No CSS file, nor theme here.

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 "wymfull" for wymeditor, you create a file www/js/wymeditor_wymfull.js (you can choose any name). And then you indicate it in the configuration file:


[htmleditors]
wymfull.engine.name=wymeditor

[webassets_common]

;...

jforms_htmleditor_wymfull.js[]="$jelix/wymeditor/jquery.wymeditor.js"
jforms_htmleditor_wymfull.js[]="js/wymeditor_wymfull.js"
jforms_htmleditor_wymfull.require=jquery

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_wymeditor_wymfull(). 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_wymeditor_wymfull(textarea_id, form_id, skin, config){
   jQuery(function(){
        jQuery("#"+textarea_id).wymeditor({
            basePath: config.jelixWWWPath+'wymeditor/',
            jQueryPath: config.jqueryPath != '' ? config.jqueryPath+'jquery.js' : '',
            lang: config.locale.substr(0,2).toLowerCase(),
            preInit : function(wym) {
                jQuery('#'+form_id).bind('jFormsUpdateFields', function(event){
                    wym.update();
                });
            },

            stylesheet: '/css/stylesEditor.css'
        });
)}

Note that, for Wymeditor and in the context of Jelix, you must redefine the option preInit as indicated in this example.

For more details about the configuration of wymeditor, see the documentation of the project.

Using an other editor

If you want to use tinymce or fckeditor, no problem. Declare javascript files of this editors in the configuration of Jelix, and a configuration file for the editor. Here are some examples with popular editors.

Careful about JS file names, it can be different.

CKEditor 3.x

To use CKEditor, some instanciation scripts are already provided in jelix-www, to have a "full" editor, a "default" editor and a "basic" editor. It is already declared in the jelix configuration.

So you just have to download CKEditor (it is a huge archive, so it is not included by default in jelix distribution), unarchive it into www/, (you should then have www/ckeditor/ckeditor.js) and then you have to indicate "ckfull", "ckdefault" or "ckbasic" in the attribute config of the element <htmleditor>. That's all !

Of course, if you want to customize CKEditor, you can do it.

For example, in the file mainconfig.ini.php:


[htmleditors]
ckmyconf.engine.name = ckeditor

[webassets_common]
;...
jforms_htmleditor_ckmyconf.js[]="ckeditor/ckeditor.js"
jforms_htmleditor_ckmyconf.js[]="js/ckeditor_myconf.js"

In js/ckeditor_myconf.js:


function jelix_ckeditor_ckmyconf(textarea_id, form_id, skin, config) {
    var conf = {toolbar:[ /* here the configuration of toolbars */],
       /*otherproperty:value,*/
     };
    if (skin !='default')
        conf['skin'] = skin;
    conf["language"] = config.locale.substr(0,2).toLowerCase();

    var editor = CKEDITOR.instances[textarea_id];
    if (editor){
        editor.destroy(true);
    }

    editor = CKEDITOR.replace(textarea_id, conf);
    jQuery('#'+form_id).bind('jFormsUpdateFields', function(event){
        editor.updateElement();
    });
}

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.