Ephox EditLive! for XML can be configured to POST its content directly to a POST acceptor script on a Web server. This is useful in situations where EditLive! for XML cannot its content as part of the HTML form submission architecture. The POST operation can be called by either a custom interface item or via a JavaScript function.
The PostDocument functionality of EditLive! for XML can be configured via the following parameters:
This parameter is required.
The name of the field in the HTTP POST that EditLive! for XML uses to POST its content.
This parameter is required.
The URL for the POST acceptor script that EditLive! for XML POSTs to.
This parameter is required.
This parameter indicates how EditLive! for XML should process the response. It has the following possible values:
saveToDisk
callback
When setting this parameter to callback the strJSFunctionName must also be specified.
This parameter is optional.
The name of the JavaScript function to be used as a callback function. The JavaScript function specified should accept the content of the HTTP response as its only parameter.
This parameter should be set in conjunction with setting the strResponseProcessing parameter to callback.
When using the PostDocument functionality as a JavaScript function then the parameters can be used as follows:
PostDocument(strFieldName, strPostURL, strResponseProcessing,
[strJSFunctionName]);
For more information on the PostDocument runtime JavaScript function see the information on the PostDocument function in the JavaScript runtime API.
When using the PostDocument functionality as a custom interface item these parameters are passed through the value attribute of the custom item. The parameters are passed as a single string delimited by the string ##ephox##. For more information see the example below or the article on Custom Menu and Toolbar Items for EditLive! for XML.
Example 4.2. Configuring a Custom Item to Use the PostDocument Functionality
This example demonstrates how to define a custom menu item which uses the PostDocument action for use within EditLive! for XML. The menu item defined in this example will POST the content in the field editlive_field to the script at http://someserver/post/POSTacceptor.aspx upon completion of the POST the content of the HTTP response will be passed to the JavaScript callback function JSFunction.
<editLive>
...
<menuBar>
...
<menu>
<customMenuItem
name="customItem1"
text="POST Content"
imageURL="http://www.someserver.com/image16x16.gif"
action="PostDocument"
value="editlive_field##ephox##http://someserver/post/POSTacceptor.aspx
##ephox##callback##ephox##JSFunction"
/>
</menu>
...
</menuBar>
...
</editLive>When EditLive! for XML POSTs its content it will receive the HTTP response. This response is processed by EditLive! for XML in accordance with the value of the strResponseProcessing parameter. When set to saveToDisk EditLive! for XML will open a Save dialog. This will allow users to save the content of the response to their local machine.
When set to callback EditLive! for XML will pass the content of the HTTP response to the JavaScript callback function specified by the strJSFunctionName parameter. This JavaScript method should accept the content of the response as a string, this should be the function's only parameter.
Example 4.3. Using the PostDocument Functionality with a JavaScript Callback
The following example demonstrates how to use the PostDocument JavaScript function with a JavaScript callback function which processes the response. The function jsCallback receives the content of the response from EditLive! for XML and places it in a textarea.
<HTML>
<HEAD>
<TITLE>EditLive! for XML JavaScript Example</TITLE>
<!--Include the EditLive! for XML JavaScript Library-->
<SCRIPT src="editlivexml/editlivexml.js" language="JavaScript">
</SCRIPT>
<!--Define the JavaScript callback function for HTTP response
processing from EditLive! for XML-->
<SCRIPT language="JavaScript">
function jsCallback(responseContent){
document.exampleForm.responseContentArea.value = responseContent;
}
</SCRIPT>
</HEAD>
<BODY>
<FORM name = exampleForm>
<P>Click this button to POST the document in EditLive!</P>
<P>
<INPUT type="button" name="button1" value="Save"
onClick="editlivejs.PostDocument('editliveField',
'http://someserver/post/postacceptor.jsp', 'callback', 'jsCallback');">
</P>
<!--Create an instance of EditLive! for XML-->
<SCRIPT language="JavaScript">
<!--
var editlivejs;
editlivejs = new EditLiveXML("editlive",450 , 275);
editlivejs.setDownloadDirectory("editlivexml");
editlivejs.setLocalDeployment(false);
editlivejs.setConfigurationFile("sample_elconfig.xml");
editlivejs.setDocument(escape("<P>This is EditLive!</P>"));
editlivejs.show();
-->
</SCRIPT>
<P>
<TEXTAREA name="responseContentArea" rows="20" cols="50">
</TEXTAREA>
</P>
</FORM>
</BODY>
</HTML> When using the EditLive! for XML applet to make the HTTP POST instead of using the browser's submit mechanisms developers must consider several things:
If it is required that other form variables be submitted with the content of EditLive! for XML it is best to avoid using the PostDocument functionality of EditLive! for XML. This is because, when using the PostDocument functionality, the POST of EditLive! for XML 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! for XML to a completely different POST acceptor than the browser's POST. Thus, EditLive! for XML can submit its content easily to two separate processes. This can be useful when using EditLive! for XML in association with a related server side process which produces a response which should be saved to the client. For example, the POST by EditLive! for XML could send content to a server-side publishing engine which transforms the document into a PDF or some other format which is returned to the client in the HTTP response which can then be saved. In this situation the browser's POST mechanism would still be used to submit the EditLive! for XML with values from other fields for saving.
When using the callback mechanism developers should be careful to provide users with adequate feedback by displaying the HTTP response in case the POST operation fails.
The PostDocument functionality gives developers an alternative way of submitting the content of EditLive! for XML to their systems. It can be implemented either via a custom interface item or as a JavaScript function. When implementing EditLive! for XML to POST its content directly there are several important considerations that should be addressed to ensure that EditLive! for XML will behave as expected.
Copyright 2001-2004 Ephox Corporation. All Rights Reserved.