.. _dijit/_editor/plugins/ViewSource:

dijit._editor.plugins.ViewSource
================================

:Status: Draft
:Version: 1.0
:Authors: Jared Jurkiewicz
:Developers: Jared Jurkiewicz
:Available: since V1.4

.. contents::
    :depth: 2

Have you ever wanted to edit the source generated by the dijit.Editor, but were unable to do so well?   Wouldn't it be nice to be able to see the source edited by the editor as an alternate view of the content?  Well, with this plugin you can do exactly that.

========
Features
========

Once required in and enabled, this plugin provides the following features to dijit.Editor.

* Button with icon in toolbar for switching the view of the content from RTE to Source mode and back
* Keyboard hotkey: CTRL-SHIFT-F12 toggles between source and RTE mode of the content.
* Works well when paired with the FullScreen plugin.  This plugin is 'FullScreen' aware and will behave appropriately.
* Built-in filters to strip out potentially dangerous input from being inserted, such as <script> tags, <iframe> tags, and comment tags, that are often used as a way to do XSS (Cross-SiteScripting hijacks).
* When enabled, all other RTE plugins are disabled for the duration of the source view.  This is because in source view mode, the other plugins  do not apply.
* Provides a 'readOnly' mode that, if enabled on the plugin, allows the user to see the source, but they cannot change it.  


=====
Usage
=====

Basic Usage
-----------
Usage of this plugin is quite simple and painless.  The first thing you need to do is require into the page you're using the editor.  This is done in the same spot all your dojo.require calls are made, usually a head script tag.  For example:

.. code-block :: javascript
 
    dojo.require("dijit.Editor");
    dojo.require("dijit._editor.plugins.ViewSource");


Once it has been required in, all you have to do is include it in the list of extraPlugins (or the plugins property if you're reorganizing the toolbar) for you want to load into the editor.  For example:

.. code-block :: html

  <div dojoType="dijit.Editor" id="editor" extraPlugins="['viewsource']"></div>


And that's it.  The editor instance you can reference by 'dijit.byId("editor")' is now enabled with the ViewSource plugin!  You can use the button or hotkey to toggle between source and RTE views.

Configurable Options
--------------------

The ViewSource plugin has several configurable options to tailor it for your usage.  Please see the following table:

+---------------------------+-----------------------------------------------------------------------------------------------------------+
| **Option**                | **Description**                                                                                           |
+---------------------------+-----------------------------------------------------------------------------------------------------------+
| readOnly                  |When enabled, the source can only be viewed in read-only mode, it cannot be edited.  The default is false  |
+---------------------------+-----------------------------------------------------------------------------------------------------------+
| stripScripts              |When enabled, script tags are stripped from the source.  The default is true.  It is highly recommended    |
|                           |that this option is left enabled.  Disabling it opens up a vector for XSS attacks                          |
+---------------------------+-----------------------------------------------------------------------------------------------------------+
| stripComments             |When enabled, comments are stripped from the source.  The default is true.  It is highly recommended       |
|                           |that this option is left enabled.  Disabling it opens up a vector for XSS attacks                          |
+---------------------------+-----------------------------------------------------------------------------------------------------------+
| stripIframes              |When enabled, iframe tags are stripped from the source.  The default is true.  It is highly recommended    |
|                           |that this option is left enabled.  Disabling it opens up a vector for XSS attacks                          |
+---------------------------+-----------------------------------------------------------------------------------------------------------+



================
XSS Attack notes
================

See the section on limitations.

===========
Limitations
===========

* By default the plugin will strip any <script>, <iframe> or comment tags from the document.  This is to avoid XSS.  While these filters can be disabled, it is highly, highly recommended to leave them enabled.
* If readOnly mode is enabled, then it will persist for the life of the plugin.  This is to help avoid XSS injection attacks as well.  The same can be said for the enabling and disabling of filters.
* While this plugin does its best to try and help prevent XSS attacks, **the server side should always filter the incoming content for attack vectors anyway**.  This is because that since the editor runs in the client (browser), and browsers by their very nature are rather insecure, content sent from them should never be trusted.  Always do positive validation, where you assume the data coming from the client is bad and it must be proven to be good before it is allowed in the system.
* The content of the editor (as obtained by editor.getValue() or editor.attr("value")) is not updated with the source view content until it is toggled off.  This is to ensure that the filters are executed on the content to help prevent XSS attacks.
* On IE 7, do not use the IE 'zoom' function (CTRL+ or CTRL-), with the editor in source mode and then try to resize the browser window.  This is because the IE 7 function is, frankly, horribly broken.  It does not generate any events, nor does it actually scale things appropriately.  In fact, the information it returns isn't even valid and has to be 'fudged' to try and get things to size right.  Unfortunately, this doesn't always work well and this is one of those cases.  Because IE seems incapable of returning correct position data and the fudging amounts vary by some unknown formula, we cannot consistently get the source area to scale the height right.  If we ever come up with a fix for this, this limitation will be removed.  But at the moment, this seems highly doubtful.

==================
Other useful notes
==================

This plugin is particularly powerful when it is combined with the following plugins:

* :ref:`dijit._editor.plugins.FullScreen <dijit/_editor/plugins/FullScreen>` - Edit the document in the full 'viewport' of the window running dojo.
* :ref:`dojox.editor.plugins.PrettyPrint <dojox/editor/plugins/PrettyPrint>` - Format the content in the editor so that it is easily human readable and modifiable.


===================
A11Y Considerations
===================

* When using the hotkey CTRL-SHIFT-F12, the focus will be restored to the top of both the source view or the RTE view, keeping it consistent with retaining focus inside the 'editable' area of the editor.
* When using the button (via mouse click or keyboard), focus does not move into the edit area.  This is so that users who accidentally enable the mode do not have to chift-tab out to undo the mode.  They can just press the button again.


========
Examples
========

Basic Usage
-----------

.. code-example::
  :djConfig: parseOnLoad: true
  :version: 1.4

  .. javascript::

    <script>
      dojo.require("dijit.Editor");
      dojo.require("dijit._editor.plugins.ViewSource");
    </script>

  .. html::

    <b>Toggle the View Source button to see the contents in source mode.</b>
    <br>
    <div dojoType="dijit.Editor" height="250px"id="input" extraPlugins="['viewsource']">
    <div>
      <br>
      blah blah & blah!
      <br>
    </div>
    <br>
    <table>
    <tbody>
    <tr>
    <td style="border-style:solid; border-width: 2px; border-color: gray;">One cell</td>
    <td style="border-style:solid; border-width: 2px; border-color: gray;">
    Two cell
    </td>
    </tr>
    </tbody>
    </table>
    <ul> 
    <li>item one</li>
    <li>
    item two
    </li>
    </ul>
    </div>

Enabling read-only view 
-----------------------

.. code-example::
  :djConfig: parseOnLoad: true
  :version: 1.4

  .. javascript::

    <script>
      dojo.require("dijit.form.Button");
      dojo.require("dijit.Editor");
      dojo.require("dijit._editor.plugins.ViewSource");
    </script>

  .. html::

    <b>Toggle the View Source button to see the contents in source mode.</b>
    <br>
    <div dojoType="dijit.Editor" height="250px" id="input" extraPlugins="[{name:'viewsource',readOnly: true}]">
    <div>
    <br>
    blah blah & blah!
    <br>
    </div>
    <br>
    <table>
    <tbody>
    <tr>
    <td style="border-style:solid; border-width: 2px; border-color: gray;">One cell</td>
    <td style="border-style:solid; border-width: 2px; border-color: gray;">
    Two cell
    </td>
    </tr>
    </tbody>
    </table>
    <ul> 
    <li>item one</li>
    <li>
    item two
    </li>
    </ul>
    </div>


Viewing Source with PrettyPrint Plugin enabled
----------------------------------------------

.. code-example::
  :djConfig: parseOnLoad: true
  :version: 1.4

  .. javascript::

    <script>
      dojo.require("dijit.Editor");
      dojo.require("dijit._editor.plugins.ViewSource");
      dojo.require("dojox.editor.plugins.PrettyPrint");
    </script>

  .. html::

    <b>Toggle the View Source button to see the contents in source mode.</b>
    <br>
    <div dojoType="dijit.Editor" height="250px" id="input" extraPlugins="[{name: 'viewsource', readOnly: true}, {name:'prettyprint', indentBy: 3}]">
    <div>
      <br>
      blah blah & blah!
      <br>
    </div>
    <br>
    <table>
    <tbody>
    <tr>
    <td style="border-style:solid; border-width: 2px; border-color: gray;">One cell</td>
    <td style="border-style:solid; border-width: 2px; border-color: gray;">
    Two cell
    </td>
    </tr>
    </tbody>
    </table>
    <ul> 
    <li>item one</li>
    <li>
    item two
    </li>
    </ul>
    </div>

Viewing Source with PrettyPrint Plugin enabled and readOnly source
------------------------------------------------------------------

.. code-example::
  :djConfig: parseOnLoad: true
  :version: 1.4

  .. javascript::

    <script>
      dojo.require("dijit.Editor");
      dojo.require("dijit._editor.plugins.ViewSource");
      dojo.require("dojox.editor.plugins.PrettyPrint");
    </script>

  .. html::

    <b>Toggle the View Source button to see the contents in source mode.</b>
    <br>
    <div dojoType="dijit.Editor" height="250px" id="input" extraPlugins="[{name:'viewsource',readOnly: true}, 'prettyprint']">
    <div>
      <br>
      blah blah & blah!
      <br>
    </div>
    <br>
    <table>
    <tbody>
    <tr>
    <td style="border-style:solid; border-width: 2px; border-color: gray;">One cell</td>
    <td style="border-style:solid; border-width: 2px; border-color: gray;">
    Two cell
    </td>
    </tr>
    </tbody>
    </table>
    <ul> 
    <li>item one</li>
    <li>
    item two
    </li>
    </ul>
    </div>

Viewing Source with PrettyPrint and FullScreen Plugins enabled
--------------------------------------------------------------
This example also organizes the toolbar a bit.


.. code-example::
  :djConfig: parseOnLoad: true
  :version: 1.4

  .. javascript::

    <script>
      dojo.require("dijit.Editor");
      dojo.require("dijit._editor.plugins.ViewSource");
      dojo.require("dijit._editor.plugins.FullScreen");
      dojo.require("dojox.editor.plugins.PrettyPrint");
    </script>

  .. html::

    <b>Toggle the View Source button to see the contents in source mode.</b>
    <br>
    <div dojoType="dijit.Editor" height="250px" id="input" plugins="[{name:'prettyprint',indentBy:3},'viewsource','fullscreen','|','undo','redo','|','cut','copy','paste','|','bold','italic','underline','strikethrough','|','insertOrderedList','insertUnorderedList','indent','outdent','|','justifyLeft','justifyRight','justifyCenter','justifyFull',{name:'dijit._editor.plugins.EnterKeyHandling',blockNodeForEnter:'DIV'}]">
    <div>
      <br>
      blah blah & blah!
      <br>
    </div>
    <br>
    <table>
    <tbody>
    <tr>
    <td style="border-style:solid; border-width: 2px; border-color: gray;">One cell</td>
    <td style="border-style:solid; border-width: 2px; border-color: gray;">
    Two cell
    </td>
    </tr>
    </tbody>
    </table>
    <ul> 
    <li>item one</li>
    <li>
    item two
    </li>
    </ul>
    </div>


========
See Also
========

* :ref:`dijit.Editor <dijit/Editor>`
* :ref:`dojox.editor.plugins <dojox/editor/plugins>`