EditLive! 9 Documentation : Retrieving Content From EditLive!

There are several methods in which content can be retrieved from an instance of the EditLive! applet:

Using the Save and Save As... Menu and Toolbar Items.

Using the EditLive! Run Time Functions
EditLive! provides run-time functions to allow access to an editor's content at any time.

Through Hidden Form Fields Created During a HTTP Post.
When the HTML form containing an instance of EditLive! is submitted, several hidden form fields are generated containing content from the editor. These fields are available when:
- The onsubmit function of the form is called and client-side scripting can be used to access the hidden form fields before the form is posted, or
- The form is submitted and server-side scripting can be used to access the fields sent through HTTP Post.

Allowing EditLive! to Explicitly Call a HTTP Post.
EditLive! can explicitly call a HTTP Post (as opposed to the HTML form containing the instance of EditLive! calling a HTTP Post). To do this, you will need to use a custom created menu or toolbar item.

Using the Save and Save As... Menu and Toolbar Items

Using the Save and Save As... menu and toolbar items, users can save the entire XHTML document stored in EditLive! to their local machine.

These items are specified through an EditLive! configuration file. These items can be added by Manually Editing Configuration Files. See the Menu and Toolbar Item List, <menuItem> and <toolbarButton> sections of this SDK for more information.

Using the EditLive! Run Time Functions

EditLive! provides two run-time functions to extract the content of the editor:

getDocument Method
This property returns the entire XHTML document currently stored in EditLive!.

getBody Method
This property returns only the content nested between the <body> tags in EditLive!. The actual <body> tags are not included.

Both of these functions take two parameters:

A string matching a JavaScript function's name. This JavaScript function will be called upon invoking one of the above run-time properties, passing the content of EditLive! as a parameter.

An (optional) boolean value, indicating whether the uploadImages Method should be invoked before the above JavaScript function is called. This will ensure all locally stored images are uploaded to the relevant Web server and their URLs are adjusted in the EditLive! content.

Example
This example shows how to use the getDocument Method.

 
<script src="../../redistributables/editlivejava/editlivejava.js"></script>
 
<script language="JavaScript">
   var editlivejava1;
   editlivejava1 = new EditLiveJava("ELApplet1", "700", "400");
   ...
   editlivejava1.show();
</script>
  
<!-- 
   Pressing the button causes the content to be displayed in an alert.
-->
<input type="button" name="GetContent" onclick="alert(editlivejava1.GetDocument(true));"/>

Using the HTML Form HTTP Post

By default, the content of the EditLive! applet are retrieved when a HTML form containing the instance of EditLive! is submitted. Because of the lack of LiveConnect support on various operating systems and browsers, EditLive! populates a hidden field with its contents automatically rather than the developer calling for the contents explicitly. The name of this generated hidden field (contained within the same HTML form as the EditLive! instance) is given the same name that was specified by the developer when the EditLive! instance was created.

Example
This example shows an instance of EditLive! being created with the name ELApplet1.

 
<form name="form1" method="POST" action="http://www.yourserver.com/scripts/upload.jsp">
   <script src="../../redistributables/editlivejava/editlivejava.js"></script>
 
   <script language="JavaScript">
      var editlivejava1;
      editlivejava1 = new EditLiveJava("ELApplet1", "700", "400");
      ...
      editlivejava1.show();
   </script>
</form>

If ELApplet1 was specified as the name for the instance of the EditLive! applet, then the applet would store its contents in the hidden field named ELApplet1. This hidden field is then posted with the rest of the form data when the submit button is pressed.

When a form containing an instance of EditLive! is submitted, a hidden field containing all style information for the document is also created and posted with the form data. This hidden field will be called ELAPPLETNAME_styles, where ELAPPLETNAME is the name specified by the developer when the instance of EditLive! was created.

EditLive! automatically updates the hidden fields by attaching itself to the form's onsubmit() handler. If there is already a function specified in the onsubmit() handler, then this function will run after the hidden field has been updated. This means that you can still use the onsubmit() handler to run your own JavaScript functions. If you use another button/image/event to submit the form by calling form.submit(), the browser will not call the onsubmit() handler and EditLive! will not populate the hidden fields with data. For this reason, please ensure you use form.onsubmit() to avoid this problem.

By default, the content that is retrieved from the EditLive! applet will be the contents of the <BODY> element for the HTML Document. This behavior can be modified through setting the setReturnBodyOnly Method.

The automatic submission of the content of the EditLive! applet can be disabled through the use of the setAutoSubmit Method. By setting the AutoSubmit property to false, the automatic content submission can be disabled. Automatic submission of content by the applet is enabled by default.

Retrieving EditLive!'s Content Using Client-Side Scripting Before the HTTP Post

By using the onsubmit() handler for the HTML form containing EditLive! client-side scripting can be used to access the hidden field containing EditLive!'s content.

If a HTML form's onsubmit() handler returns false, the HTML form won't submit. This technique can be used to extract the content of EditLive! without submitting the HTML form.

Example
The following example shows how to use the onsubmit() handler for a HTML form (containing an instance of EditLive!) to extract EditLive!'s content. In this example, the onsubmit() handler also cancels the HTML form submission using return false.

 
<form name="form1" method="POST" onsubmit="return retrieveELContents()">
 
   <script src="../../redistributables/editlivejava/editlivejava.js"></script>
 
   <script language="JavaScript">
      var editlivejava1;
      editlivejava1 = new EditLiveJava("ELApplet1", "700", "400");
       // ensuring a field is created in the form called ELApplet1, containing the contents of 
       editlivejava1.setAutoSubmit(true);
      ...
      editlivejava1.show();
   </script>
 
   <script language="JavaScript">
      function retrieveELContents()
      {
         // Setting contents of hidden field's value to a JavaScript variable
         var ELContents = document.getElementById('ELApplet1').value;
 
         alert(ELContents);
 
         return false;
      }
   </script>
 
   <input type="submit" name="submit" value="Submit"/>
</form>

The showBodyOnly attribute of the EditLive! <sourceEditor> Configuration File Element defines how the editor will store its contents in the hidden form fields identified above. If showBodyOnly is set to true, only the contents of the <BODY> element (for the HTML document stored in EditLive!) will be stored in the hidden form field. If showBodyOnly is set to false, the entire HTML document stored in EditLive! will be stored in the hidden form field.

Retrieving EditLive!'s Content Using the HTTP Post's Server-Side Script

Example

The following examples show using a server-side language to access the hidden HTML form field generated by instance of EditLive! named ELApplet1.

VB Scripting

<%
   Dim editorContent = Request( "ELApplet1" )
%>

JSP Scripting

<%
   String editorContent = request.getParameter("ELApplet1");
%>

Using EditLive! to Explicitly Call a HTTP Post

EditLive! can be configured to post its content directly to a Post Acceptor Script on a Web server. This is useful in situations where EditLive! cannot post its content as part of the HTML form submission architecture.

This technique creates two separate methods for retrieving the content of the EditLive! for Java editor:

Accessing the content via the Post Acceptor Script.
Examples of how to access the content sent from EditLive! to the Post Acceptor Script is given in the Retrieving EditLive! for Java's Content Using the HTTP Post's Server-Side Script section of this article.

Specifying either a Save As.. dialog or a JavaScript function to be called upon the HTTP Response. How to specify what action is performed upon the HTTP Response is different for the Custom Menu Item and Custom Toolbar Button.

EditLive! for Java allows a HTTP Post to be explicitly called through the creation of a Custom Menu Item or a Custom Toolbar Button with a PostDocument action.

Important Considerations When Using An Explicit EditLive! HTTP Post

Developers must consider several things when using the EditLive! applet to make the HTTP POST instead of using the browser's submit mechanisms:

If it is required that other form variables be submitted with the content of EditLive!, it is best to avoid using the explicit HTTP functionality of EditLive!. This is because when using the EditLive! explicit HTTP Post, the post of EditLive! occurs separately to the browser's post. This can unnecessarily complicate the server-side processing involved in receiving and processing the posted content.

The Post functionality can be used to submit the content of EditLive! to a completely different Post Acceptor Script than the browser's post. Thus, EditLive! can submit its content easily to two separate processes. This can be useful when using EditLive! in association with a related server-side process which produces a response which should be saved to the client.

Ensuring Output is XHTML or XML Compliant

In order to ensure that the output of content in EditLive! is XHTML or XML compliant, specific attributes in the <htmlFilter> configuration file element have to be set.

For XHTML compliant output, the following filter settings are required:

Set outputXHTML to true - This ensures that XHTML tags are used (i.e. <br/> instead of <br>).

Set allowUnknownTags to false - This ensures that no tags outside of the XHTML standard are used, i.e. custom tags. Instead, custom tags are HTML encoded.

Set encloseText to true - This ensures content is correctly nested inside the relevant parent tags.

For XML compliant output the following filter settings are required:

Set outputXML to true - this ensures that special characters are encoded as numeric entities and that XML style tags are used (i.e. <br/> instead of <br>).

Set encloseText to true - This ensures that the content is correctly nested inside the relevant parent tags.