Immutable Elements

The immutable feature enables you to add HTML elements that cannot be edited by the user.

Although the immutable elements can not be modified, they can be removed. The actions that can be performed to remove an immutable element are described in the Removing Immutable Elements section.

Enabling Immutable Elements

To define the immutable elements in the content area, set the contenteditable DOM attribute to false. To make the Editor prevent the user from editing this element, you also need to enable the immutables option.

    <textarea id="editor">
        &lt;p&gt;A simple paragraph&lt;/p&gt;
        &lt;p contenteditable=&quot;false&quot;&gt;This paragraph cannot be edited&lt;/p&gt;
        &lt;p&gt;A simple paragraph&lt;/p&gt;
    </textarea>
    <script>
        $("#editor").kendoEditor({
            immutables: true
        });
    </script>

Serializing Immutables

The immutables.serialization option enables you to control the HTML representation of the immutable elements in the viewHtml dialog.

The immutables.serialization configuration option accepts the following parameters:

• String—A plain string that implements an opening and a closing tag of the representation you want to display in the viewHtml dialog.

      <textarea id="editor">
          &lt;p&gt;A simple paragraph&lt;/p&gt;
          &lt;p contenteditable=&quot;false&quot;&gt;This paragraph cannot be edited&lt;/p&gt;
          &lt;p&gt;A simple paragraph&lt;/p&gt;
      </textarea>
      <script>
          $("#editor").kendoEditor({
              tools: [
                  "bold", "italic", "underline", "justifyLeft", "justifyCenter", "justifyRight", "insertUnorderedList", "insertOrderedList", "indent", "outdent", "createLink", "unlink", "insertImage", "createTable", "viewHtml"
              ],
              immutables: {
                  serialization: "<div></div>"
              }
          });
      </script>
  

• Kendo UI Template—In it, the immutable DOM element is data.

      <textarea id="editor">
          &lt;p&gt;A simple paragraph&lt;/p&gt;
          &lt;p contenteditable=&quot;false&quot;&gt;This paragraph cannot be edited&lt;/p&gt;
          &lt;p&gt;A simple paragraph&lt;/p&gt;
      </textarea>
      <script>
          $("#editor").kendoEditor({
              tools: [
                  "bold", "italic", "underline", "justifyLeft", "justifyCenter", "justifyRight", "insertUnorderedList", "insertOrderedList", "indent", "outdent", "createLink", "unlink", "insertImage", "createTable", "viewHtml"
              ],
              immutables: {
                  serialization: "<#= data.nodeName # data=\"immutable-element\"></#= data.nodeName #>"
              }
          });
      </script>
  

• Function—A callback function that exposes the immutable DOM element in the overload and is expected to return a string.

      <textarea id="editor">
          &lt;p&gt;A simple paragraph&lt;/p&gt;
          &lt;p contenteditable=&quot;false&quot;&gt;This paragraph cannot be edited&lt;/p&gt;
          &lt;p&gt;A simple paragraph&lt;/p&gt;
      </textarea>
      <script>
          $("#editor").kendoEditor({
              tools: [
                  "bold", "italic", "underline", "justifyLeft", "justifyCenter", "justifyRight", "insertUnorderedList", "insertOrderedList", "indent", "outdent", "createLink", "unlink", "insertImage", "createTable", "viewHtml"
              ],
              immutables: {
                  serialization: function(node) {
                      var tagName = node.tagName;
                      return "<" + tagName + ">" + "</" + tagName + ">";
                  }
              }
          });
      </script>
  

Deserializing Immutables

The immutables.deserialization does the opposite of the immutables.serialization one—it takes the HTML representation from the viewHtml dialog and alters the immutable DOM element based on the logic implemented in the callback function.

The following example demonstrates how to use the immutables.serialization and immutables.deserialization options to expose the CSS text-align property in the viewHtml dialog so that the user is able to change it from the HTML code.

    <textarea id="editor">
        &lt;p&gt;A simple paragraph&lt;/p&gt;
        &lt;p contenteditable=&quot;false&quot; style=&quot;text-align:left;&quot; &gt;This paragraph cannot be edited&lt;/p&gt;
        &lt;p&gt;A simple paragraph&lt;/p&gt;
    </textarea>
    <script>
        $("#editor").kendoEditor({
            tools: [
                "bold", "italic", "underline", "justifyLeft", "justifyCenter", "justifyRight", "insertUnorderedList", "insertOrderedList", "indent", "outdent", "createLink", "unlink", "insertImage", "createTable", "viewHtml"
            ],
            serialization: "<immutable style='# if(data.style.textAlign){#text-align: #=data.style.textAlign##}#'></immutable>",
            deserialization: function (node, immutable) {
                    immutable.style.textAlign = node.style.textAlign;
            }
        });
    </script>

Applying a Default Decoration

To decorate all contenteditable="false" elements and improve user experience (UX), use a CSS rule.

• If you use the classic mode, add the CSS rule to an external CSS file adjoined to the stylesheet collection of the Editor.
• If you use the inline mode, place the CSS rule on the page as demonstrated in the following example.

    <style>
    .k-editor [contenteditable='false']{
        opacity: 0.5;
    }
    </style>
    <textarea id="editor">
        &lt;p&gt;A simple paragraph&lt;/p&gt;
        &lt;p contenteditable=&quot;false&quot;&gt;This paragraph cannot be edited&lt;/p&gt;
        &lt;p&gt;A simple paragraph&lt;/p&gt;
    </textarea>
    <script>
        $("#editor").kendoEditor({
            immutables: true
        });
    </script>

Removing Immutable Elements

The content of the immutable elements can not be edited, their format or text can not be modified. However, the immutable elements can be deleted.

The immutable elements will be removed when one of the following actions is performed:

• When the entire element or part of it is selected and you press the backspace or delete keys.
• If the entire element or portion of it is selected and then you start typing.
• When the immutable element is an inner part of the selection, the selection starts before the immutable element and ends after it and you press the delete key.
• When the cursor is located right before the immutable element and the delete button is pressed
• When the cursor is located right after the immutable element and the backspace button is pressed.

See Also

• Basic Usage of the Editor (Demo)
• JavaScript API Reference of the Editor