Skip to content

iWE2#

The iWE2 – imperia's WYSIWYG Editor – is based on the CK Editor that has been adjusted to meet imperia CMS demands.
For current information on CK, see ckeditor.com. imperia uses the current CKEditor version 4.7.3 (in Dec. 2017).

In this chapter you will be informed on how to configure those options in the tool bar, and also how to adapt the view on the tool bar as well as on the editing area to the editors' demands.
In the users' manual you will find more detailed descriptions on how to work with the iWE.

Note

Please consider that iWE plugin is a separate feature that should be purchased additionally. Contact your imperia sales person for further information.

You can check if you have already licenced the iWE as follows:
In the right side of the menu bar of your imperia system, click ->About imperia. There you will find a list of all the already licenced plugins.

In the following you will see a figure of the iWE2 including all available options in the tool bar: *imperias* iWE2-Editor

iWE2 Configuration#

The iWE2 offers a variety of configuration options where the functionality, appearance and behavior can be influenced.

There are two ways to configure the editor:

Configuration hierarchy

Please consider the hierarchy of the configuration possibilities. There are following hierarchy steps:

  1. Processing Instructions (in a template)

  2. template specific configuration file

  3. Global configuration file (to be found in your file system under DOCUMENT-ROOT/imperia/components/iwe2config.js; if the file is missing, the file DOCUMENT-ROOT/imperia/components/default_config.js is loaded)

Example: When you have placed a configuration option in a template, this one has in general priority to the options set in a configuration file.

Configuration via processing instructions#

With this method the configuration of the corresponding iWE2 instance is done via processing instructions in an imperia template.

Example:

<?imperia iwe2
id: iwe2
width: 570
height: 400
?>

Important

  • Comments are not allowed in the processing instructions.
  • Please make sure that the value of the id option is unique.

Configuration via Flex module#

In order to use iWE2 in a flex module, you must make sure that the id of the iWE2 instance is unique. This is done by adding an ID to the flex module in the processing instruction.

Example:

#IF ("<!--XX-editmode-->")
<br />
<?imperia iwe2
id: iwe2_<!--FLEX_INDEX-->_<!--FLEX_ID-->?>
#ELSE
<div> <!--XX-FLEX-iwe2--> </div>
#ENDIF

Configuration options for processing instructions#

Important

Make sure to set a line break after IDS, for example:

<?imperia iwe2 
 id:iwe2_<!--FLEX_INDEX-->_<!--FLEX_ID-->  
 customConfig:/imperia/js/components/iwe2/default_config.js 
?>
#ELSE
<?imperia iwe2
 id:iwe2_<!--FLEX_INDEX-->_<!--FLEX_ID-->
 customConfig:/imperia/js/components/iwe2/iwe2config.js
?>
#ENDIF

Processing Instructions can be applied directly to the template. You don't need a configuration file for these. The following options are available:

  • width

    The “width” option defines the width of the editor window.

    Possible values ​​are numeric values ​​in pixels. Example:

    imp <?imperia iwe2 id: iwe2 width: 570 ?>

  • height

    The “height” option defines the height of the editor window.

    Possible values ​​are numeric values ​​in pixels. Example:

    imp <?imperia iwe2 id: iwe2 height: 400 ?>

  • external

    The “external” option switches the external mode on and off. An enabled external mode means that the editor pops up in a separate window and not embedded in a template.

    Possible values are: 1 (on) or 0 (off). Example:

    imp <?imperia iwe2 id: iwe2 external: 1 ?>

  • externalStyle

    “externalStyle” defines the appearance of the placeholder in a template, which displays the content that is maintained via the editor in external Mode. A possible value can be CSS code. Similarly, the specification of a CSS file that contains the class 'imperia_external_editor'. Example:

    imp <?imperia iwe2 id: iwe1 external: 1 externalStyle: background:white; border:2px dotted green; ?>

  • content

    The “content” option gives you the opportunity to set a content to be displayed in the editor.

    Possible values are any type of text (string) or imperia variables. Example:

    imp <?imperia iwe2 id: iwe1 content: This is an example ... ?>

  • default.config: If this option is set the imperia default.config will be ignored.

    imp <?imperia iwe2 id: iwe2 customConfig: /iwe2.js ignoreImperiaDefaultConfig: 1 ?>

Configuration via a configuration file#

Both global and template specific configuration files can be defined.

The global configuration is available on the file system:

    DOCUMENT-ROOT/imperia/ckeditor/config.js

The template specific configuration file has to be placed somewhere below your DOCUMENT-ROOT. Use the following processing instruction in your iWE call to apply it to the document:

        customConfig: /directory/below/doc-root/iweconfig.js

Important

If you use different custom configurations for iWE2 instances in one document, the behavior is undefined. If possible, prevent such cases.

Adding customConfig to Template#

1. Creating the config

  1. Copy the contents under DOCUMENT-ROOT/imperia/ckeditor/config.js to a new .js-file that has to be stored under DOC-ROOT/below/htdocs.
  2. Adapt the config file to your needs, see configuration file options.

2. Using the config

Create a new template (or edit an existing one) and add the following line:

<? imperia iwe2
id: iwe2
customConfig: /directory/below/doc-root/foo.js ?>

Important notes:

  • Make sure: the (iwe1) option must be unique.
  • Please consider the note in the install manual when updating imperia.
  • If no customConfig is defined, CKEDITOR will use the default one, meaning no changes apply
  • Next to the default config, you are able to use a number of other custom configs.

  • You can also place the desired configuration options in the 'foo.js' file.
    Then following is to be considered:

    • The configuration has to the start with editorConfig

    • Also, the pair option-alue has to be defined differently:

      CKEDITOR.editorConfig = function( config ) { config.language = 'de'; config.stylesSet = [ { name : 'Urheber', element : 'span', styles : { 'font-size': '.875rem', 'font-style': 'italic', 'color': '#B7B0A7' } }, ]

Configuration Options for Config file#

The iWE2 provides a large amount of options to customize the functionality to your needs. The following section describes some, but not all, options. A complete overview of all available configuration options is available on the Internet: http://docs.cksource.com/CKEditor_3.x/Developers_Guide/Setting_Configurations (August 2017).

The following section describes the syntax in a configuration file.

Editor's Behavior#

  • baseHref

    The “baseHref” option works like the HTML tag '<base href="">'. It defines the base URL of all links and images.

    Possible value is a URL. Example:

    config.baseHref = 'http://www.mysite.com/';

  • docType

    The “docType” option lets you specify the DOCTYPE to be used in the editable parts. It specifies how it is rendered.

    The following example allows the editor to render the specified content as 'XHTML 1.0 Transitional':

    config.docType = '<!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">';

  • undoStackSize

    The “undoStackSize” option sets the maximum number of “undo” steps, a user can use. The default value is 15.

    Example:

    config.undoStackSize = 20;

  • MAMAdditionalParams

    You can use the “MAMAdditionalParams” option to make the MAM call from the iWE2 display only assets in mixed categories.

    To define “MAMAdditionalParams” in a template, use the following processing instruction:

    MAMAdditionalParams: prefilter=(meta:__imperia_ac = 1)

  • MAMCaption:
    When using a caption in the parameter MAMCaption (Checkbox "hascaption"), the value of the key MAMCaption (from the MAM objekt) is set in the field "Caption".
    If no caption is set, the field stays empty.
    Example: MAMCaption: copyright

    Note

    Unvalid values are OBJURL, NAME, XRES, YRES and the same value as in __imperia_node_id.

  • startupFocus

    If the “startupFocus” is set to true, the editor enforces the input cursor to appear within the input range. This is useful when there is only one instance of the iWE2 in a template and a user can start typing directly.

    The possible values are true and false. Example:

    config.startupFocus = true;

  • Word Styleinfos:
    If you like to prevent styles/formats being inserted into the iWE when using STRG+V for Word content (default setting of the plug-in Paste - stylinfos are not applied), in a custom_config.js, set as following: 

    config.pasteFromWordPromptCleanup = true;
config.pasteFromWordRemoveFontStyles = true;
config.forcePasteAsPlainText = true;
config.ignoreEmptyParagraph = true;
config.removeFormatAttributes = true;
config.removePlugins += ",pastefromword";

  • HTML Comments:
    The default behavior of CKEditor is to strip certain code from its textarea. This however also includes the comments for html (<!-- -->). There is a workaround around it that currently works for the template that is being used.
    The workaround is to put config.protectedSource.push( /<!---.*--->/g ) in your template (that is (<!-- -->) with a dot and * in the middle without the space)
    This will make so that the CKEditor will ignore <!-- --> and will not append or add anything.

  • Template-Plugin:
    The templates plugin allows you to select a predefined template that you can insert into your textfield.

Styles#

  • bodyId and bodyClass

    This pair of options allows you to specify an ID and/or a class that is added to the BODY of the editing area.

    For example, the background color (background-color) is black (# 000), but the content, which is maintained through the editor, is located in a <div id="news"> element and uses this CSS:

    ``` imp
body { background-color:#000; } h1 { color:#FFF; }
#news { background-color:#FFF; } #news h1 { color:#333; }
```

    In the configuration file use this line

    config.bodyId = 'news' ;

    to make the background of the editor white . Also, all H1 elements are presented in a dark color. This option also offers the ability to use the same CSS file for the entire site and for the editor.

  • stylesSet
    The “stylesSet” gives you the ability to add your own styles in the Styles menu of the editor. The following example shows how a new style is created.
    Example: You want to add a new style, “MY STYLE 1”, which has the following properties:

    • The style includes the format Heading 2 (h2)
    • The font color is blue
    • The background color is red

    To add the custom style “MY STYLE 1” the following code should be put in the configuration file:

    ``` imp
config.stylesSet = [{ name : 'MY STYLE 1', element : 'h2',
styles : { 'color' : 'Blue', 'background-color' : 'Red'  }}];
```

    The syntax of the option is straightforward:

    • The name of the style is set in apostrophes ('').

    • After the equal sign, define the style in curly braces ({}).

    • 'element' corresponds to the element to which the style is applied (eg, h1, h2, h3).

    • 'styles' defines which properties should have custom style (color, background-color, font-family).

  • colorButton_colors

    The option “colorButton_colors” defines the colors that are listed in the 'Text Color' and ' BackgroundColor' menus: Tcolor button"

    Valid values are HTML HEX codes. Example:

    config.colorButton_colors =
'000000,993300,333300,003300,003366,000080,333399,333333,800000,
FF6600,808000,808080,008080,0000FF,666699,808080,FF0000,FF9900,
99CC00,339966,33CCCC,3366FF,800080,999999,FF00FF,FFCC00,FFFF00,
00FF00,00FFFF,00CCFF,993366,C0C0C0,FF99CC,FFCC99,FFFF99,CCFFCC,
CCFFFF,99CCFF,CC99FF,FFFFFF';

  • format_tags

    The “format_tags” option defines the font formats (eg Heading 1, Heading 2), which are listed in the 'Format' menu.

    Valid values ​​are HTML formats (eg, p, h1, div). Example:

    config.format_tags ='p;h1;h2;h3;h4;h5;h6;pre;address;div';

  • font_names

    The option “font_names” defines the fonts which are listed in the 'Font' menu.

    Example:

    config.font_names = 'Arial;Comic Sans MS;Courier New;
Tahoma;Times New Roman;Verdana';

  • fontSize_sizes

    The “fontSize_sizes” option defines the font sizes, which are listed in the 'Size' menu. By default, the following values ​​are available:

    config.fontSize_sizes = '8/8px;9/9px;10/10px;11/11px;12/12px;14/14px;16/16px;
18/18px;20/20px;22/22px;24/24px;26/26px;28/28px;36/36px;48/48px;72/72px';

    • Any valid CSS-compatible value can be used. The following example uses pixels, 'em' and percentage sizes:

          config.fontSize_sizes = '14px;1.5em;80%';

    • For each size a name to be displayed instead of the value in the 'Size' menu can be set. Name and value must be separated by a slash. Example:

      config.fontSize_sizes = 'Fourteen Pixels/14px;A bit biggger/1.5em;A bit
smaller/80%';

  • Images in DIV:
    An image won't be displyaed in a DIV, if an alignment (left/right) has been selected. To have the image displayed, you need display:table-cell - either as Style or class


HTML Output#

"fillEmptyBlocks"

This parameter fills empty block elements in HTML output with "white spaces" so that block elements are rendered properly with line-height. It is set by default.

    config.fillEmptyBlocks = false;


User Interface#

  • defaultLanguage

    The “defaultLanguage” option specifies a fallback language in case the CKEDITOR.config.language setting is left empty and it is not possible to localize the editor to the user language.

    config.defaultLanguage = 'de';

  • extraPlugins

    With the “extraPlugins” option, you can add a list of additional plugins to be loaded.

    config.extraPlugins = 'myplugin,anotherplugin';

  • tool bar

    With this option, it is possible to adjust the tool bar. You can edit the list manually or you can use the graphical Toolbar Configurator (Sept. 17) by ck-Editor to configure the toolbar to your needs and copy the code afterwards and paste it here.

    The default iWE2 tool bar is as follows:

    config.tool bar_Imperia = [
            ['Source','-','NewPage','-','Templates'],
            ['Cut','Copy','Paste','PasteText','PasteFromWord','-','Print',
            'SpellChecker', 'Scayt'],
            ['Undo','Redo','-','Find','Replace','-','SelectAll','RemoveFormat'],
            ['Form', 'Checkbox', 'Radio', 'TextField', 'Textarea', 'Select',
            'Button', 'MAMAssetButton', 'HiddenField'],
            '/',
            ['Bold','Italic','Underline','Strike','-','Subscript','Superscript'],
            ['NumberedList','BulletedList','-','Outdent','Indent','Blockquote',
            'CreateDiv'],
            ['JustifyLeft','JustifyCenter','JustifyRight','JustifyBlock'],
            ['BidiLtr', 'BidiRtl'],
            ['MAMAssetLink','Unlink','Anchor'],
            ['MAMAsset','Flash','Table','HorizontalRule','Smiley','SpecialChar',
            'PageBreak'],
            '/',
            ['Styles','Format','Font','FontSize'],
            ['TextColor','BGColor'],
            ['Maximize', 'ShowBlocks','-','About']
        ];
    • Square brackets []represent blocks. In the tool bar, blocks are separated by |.
    • Backslash \ represent a line break in the tool bar.
    • Important features that can be added to the tool bar are:
      • PastefromWord: This feature opens an editor where a formatted text from word can be pasted. The editor transforms it to unformatted text which then can be inserted in the iWE.
      • Source: This feature opens the source code view in the IWE.

      • MAMAsset, MAMAssetLink, Anchor, etc (for inserting links):

        • Hyperlink: This feature can link to external sites.
        • Anchor: This feature sets a link within the document (to the top)
        • Imperia-link: This feature links to other imoeria documents.

        • MAM-Asset: This feature links to imperia media assets.

          Note

          data-widget="mamasset" must be used with img-Tag.

        • Email: This feature links to email addresses.

    Note

    • Please consider for links that by selecting the option new window (blank) opens a new tab.
    • For image captions: Make sure to activate the checkbox Picture with caption; otherwise the entered caption won't be displayed.

Events#

The CKEditor offers events that you could use to trigger your own functions. For further information on these events, please refer to CKEditor's documentation.

A specific for imperia event, is the .change() event that is triggered when a user saves an external iWe2 window. Example:

$( "#your_iWE2_id" ).change(function() {
    alert( "Handler for .change() called." );
});