FCKeditor 2.x/Developers Guide/Server Side Integration - Revision history

Mosipov: Added encoding.

2008-10-19T13:09:39Z

Added encoding.

Mosipov: text/xml is a deprecated mime type => application/xml

2008-10-19T13:09:02Z

text/xml is a deprecated mime type => application/xml

Fredck at 10:21, 22 March 2008

2008-03-22T10:21:10Z

Fredck at 21:39, 19 March 2008

2008-03-19T21:39:01Z

W.olchawa at 14:08, 18 January 2008

2008-01-18T14:08:47Z

W.olchawa at 14:06, 18 January 2008

2008-01-18T14:06:55Z

W.olchawa at 14:05, 18 January 2008

2008-01-18T14:05:46Z

W.olchawa at 13:36, 18 January 2008

2008-01-18T13:36:46Z

W.olchawa at 13:27, 18 January 2008

2008-01-18T13:27:14Z

W.olchawa at 13:14, 18 January 2008

2008-01-18T13:14:54Z

@@ Line 101: / Line 101: @@
 Some important things must be considered when building the response:
-*The response encoding must be set to "application/xml".
+*The response encoding must be set to "application/xml" and UTF-8.
 *The "Cache-Control" HTTP header must be set to "no-cache". This is needed because the browsers usually cache the requests for XML files and this is not wanted in this case.
 *The Path and the URL must always start and finish with a slash (/).

@@ Line 89: / Line 89: @@
 '''NOTE''': Please try to let any configuration setting to be done outside the editor package directory. In this way it is easy to the end user to handle future editor updates (just replacing the entire directory with the new version).
-=== Connector Responses ===
+=== Connector Responses  ===
 All Connector responses have the same base XML structure, like this:
-<pre>
+<pre>&lt;?xml version="1.0" encoding="utf-8"&nbsp;?&gt;
-<?xml version="1.0" encoding="utf-8" ?>
+   &lt;Connector command="RequestedCommandName" resourceType=" RequestedResourceType"&gt;
-   <Connector command="RequestedCommandName" resourceType=" RequestedResourceType">
+     &lt;CurrentFolder path="CurrentFolderPath" url="CurrentFolderUrl" /&gt;
-     <CurrentFolder path="CurrentFolderPath" url="CurrentFolderUrl" />
+     &lt;Error number="ErrorNumber" text="CustomErrorMessage" /&gt;
-     <Error number="ErrorNumber" text="CustomErrorMessage" />
+     &lt;!-- Here goes all specific command data --&gt;
-     <!-- Here goes all specific command data -->
+&lt;/Connector&gt;
-</Connector>
+</pre>
-</pre>
+Some important things must be considered when building the response:
 Some important things must be considered when building the response:
-* The response encoding must be set to "text/xml".
+*The response encoding must be set to "application/xml".
-* The "Cache-Control" HTTP header must be set to "no-cache". This is needed because the browsers usually cache the requests for XML files and this is not wanted in this case.
+*The "Cache-Control" HTTP header must be set to "no-cache". This is needed because the browsers usually cache the requests for XML files and this is not wanted in this case.
-* The Path and the URL must always start and finish with a slash (/).
+*The Path and the URL must always start and finish with a slash (/).
 === Error Messages ===

@@ Line 84: / Line 84: @@
 * '''ResourceType''' - the File Browser is used on many parts of the editor, like the Link and Image dialog boxes and in the future Flash and Multimedia dialogs. So to separate each "Resource Type" the following type names are used: "File", "Image", "Flash" and "Media".
 * '''FolderPath''' - represents the path of the current folder visible in the File Browser. This path is not the final URL path for that folder, but it is relative to the Resource Type folder. The final folder is composed by: "Configured User Files Path" + "Resource Type" + "Folder Path". For example, the Folder Path "/Docs/Test/" of resources type "Image" could correspond to the following URL path: "/UserFiles/Image/Docs/Test/".
-** The Folder Path must always begin and finish with a slash ("/").
+** The Folder Path must begin and finish with a slash ("/"). If those slashes are missing, the server connector must append them before processing the request.<br>
 ** The developer is encouraged to make an easy and secure way to configure the "Server Path" folder available to the end user. For example, for the ASP.NET Connector the user can use the global Web.config file to set which folder to use. The default key for this is "FCKeditor:UserFilesPath". In case of absent configuration the Connector must use the "/userfiles/" folder. The Connector should also automatically create the folder if it doesn't already exist.

@@ Line 126: / Line 126: @@
 * Sample request:
 <pre>connector.ext?Command=GetFolders&amp;Type=File&amp;CurrentFolder=/Samples/Docs/</pre>
 * Sample response:
-<pre>?xml version="1.0" encoding="utf-8" ?>
+<pre>&lt;?xml version="1.0" encoding="utf-8"&nbsp;?&gt;
-  <Connector command="GetFolders" resourceType="File">
+&lt;Connector command="GetFolders" resourceType="File"&gt;
-    <CurrentFolder path="/Samples/Docs/" url="/UserFiles/File/Samples/Docs/" />
+  &lt;CurrentFolder path="/Samples/Docs/" url="/UserFiles/File/Samples/Docs/" /&gt;
-    <Folders>
+  &lt;Folders&gt;
-      <Folder name="Documents" />
+    &lt;Folder name="Documents" /&gt;
-      <Folder name="Files" />
+    &lt;Folder name="Files" /&gt;
-      <Folder name="Other Files" />
+    &lt;Folder name="Other Files" /&gt;
-      <Folder name="Related" />
+    &lt;Folder name="Related" /&gt;
-   </Folders>
+  &lt;/Folders&gt;
-</Connector></pre>
+&lt;/Connector&gt;</pre>
 ==== GetFoldersAndFiles (XML) ====

@@ Line 254: / Line 254: @@
 The easiest way for the end user to understand how to use the editor is to see it in action. So it's important to make available samples that clearly show how to use it.
-The developers are invited to create samples similar to that available for the Javascript Integration Pack. Please take a look at the _samples/html folder. All files must be put together in a folder under the _samples folder.
+The developers are invited to create samples similar to that available for the Javascript Integration Pack. Please take a look at the '''_samples/html''' folder. All files must be put together in a folder under the _samples folder.
-All samples should post the posted data to a single page that shows that data. The Javascript integration module uses an ASP file, called sampleposteddata.asp, that does that (just because JavaScript doesn't handle posted data). That file can be used as a reference for a custom implementation. Please use the same file name, like sampleposteddata.ext.
+All samples should post the posted data to a single page that shows that data. The Javascript integration module uses an ASP file, called '''sampleposteddata.asp''', that does that (just because JavaScript doesn't handle posted data). That file can be used as a reference for a custom implementation. Please use the same file name, like sampleposteddata.ext.

@@ Line 218: / Line 218: @@
 All connectors available in the editor package can be found at the following folder: "editor/filemanager/connectors". Each server side language has its own folder there, with the Connector file inside it. To choose which connector to use, the end-user just edits the configuration file '''fckconfig.js''' or the custom [[FCKeditor 2.x/Developers Guide/Configuration/Configuration File|Configuration File]] and modifies the following key (in this case for the Link Dialog box in PHP):
 <pre>FCKConfig.LinkBrowserURL = FCKConfig.BasePath + 'filemanager/browser/default/browser.html?Connector=../../connectors/php/connector.php&nbsp;;
 </pre>
 * [[FCKeditor 2.x/Developers Guide/Configuration/Configuration Options/LinkBrowserURL|LinkBrowserURL]]
-* [[FCKeditor 2.x/Developers Guide/Configuration/Configuration Options/ImageBrowserURL|LinkBrowserURL]]
+* [[FCKeditor 2.x/Developers Guide/Configuration/Configuration Options/ImageBrowserURL|ImageBrowserURL]]
-* [[FCKeditor 2.x/Developers Guide/Configuration/Configuration Options/LinkrowserURL|LinkBrowserURL]]
+* [[FCKeditor 2.x/Developers Guide/Configuration/Configuration Options/FlashBrowserURL|FlashBrowserURL]]
 for further information

← Older revision		Revision as of 14:05, 18 January 2008
Line 219:		Line 219:
	<pre>FCKConfig.LinkBrowserURL = FCKConfig.BasePath + 'filemanager/browser/default/browser.html?Connector=../../connectors/php/connector.php ;		<pre>FCKConfig.LinkBrowserURL = FCKConfig.BasePath + 'filemanager/browser/default/browser.html?Connector=../../connectors/php/connector.php ;
	</pre>		</pre>
		+
		+	The user can even write his custom Connector and point the LinkBrowserURL to it, like "?Connector=/MyFolder/MyConnector.php" for example.
		+	See:
		+	* [[FCKeditor 2.x/Developers Guide/Configuration/Configuration Options/LinkBrowserURL\|LinkBrowserURL]]
		+	* [[FCKeditor 2.x/Developers Guide/Configuration/Configuration Options/ImageBrowserURL\|LinkBrowserURL]]
		+	* [[FCKeditor 2.x/Developers Guide/Configuration/Configuration Options/LinkrowserURL\|LinkBrowserURL]]
		+	for further information
		+
		+	== Quick Uploader ==
		+
		+	The "Image Properties", "Link Properties" and "Flash Properties" dialog windows provide a way to quickly upload a file to the server. This feature works much like the "FileUpload" command of the File Browser Connector.
		+
		+	The implementation must provide a URL where the editor will POST the file to be uploaded. The "Uploader" will them process the file, making the necessary security checks, and return a simple "HTML" with a script that confirms the upload success or failure. The posted file is named "'''NewFile'''".
		+
		+	The "Uploader" must return a simple <script> tag with a script that calls the "window.parent.OnUploadCompleted" function. This is the response template:
		+	<pre>
		+	<script type="text/javascript">
		+	window.parent.OnUploadCompleted( 'ErrorNumber', 'FileUrl', 'FileName', 'CustomMessage' );
		+	</script>
		+	</pre>
		+	The "OnUploadCompleted" function expects the following parameters:
		+	* '''ErrorNumber''': indicates the success or failure of the upload processing. The following values are valid:
		+	** 0: File sucessfuly uploade.
		+	** 1: Custom error. In this case the "CustomMessage" parameter value is displayed to the user in an alert box.
		+	** 201: The file has been successfully uploaded, but a file with the same name already exists. So the file has been renamed to the value present in the "FileName" parameter.
		+	** 202: Invalid file type (usually for security reason).
		+	** 203: Not enough permission to write in the server.
		+	* '''FileUrl''': the final URL to load the uploaded file.
		+	* '''FileName''': see the error number "201".
		+	* '''CustomMessage''': see the error number "1".
		+
		+	== Samples ==
		+
		+	The easiest way for the end user to understand how to use the editor is to see it in action. So it's important to make available samples that clearly show how to use it.
		+
		+	The developers are invited to create samples similar to that available for the Javascript Integration Pack. Please take a look at the _samples/html folder. All files must be put together in a folder under the _samples folder.
		+
		+	All samples should post the posted data to a single page that shows that data. The Javascript integration module uses an ASP file, called sampleposteddata.asp, that does that (just because JavaScript doesn't handle posted data). That file can be used as a reference for a custom implementation. Please use the same file name, like sampleposteddata.ext.

← Older revision		Revision as of 13:36, 18 January 2008
Line 215:		Line 215:

	=== Configuring the Connector ===		=== Configuring the Connector ===
		+
		+	All connectors available in the editor package can be found at the following folder: "editor/filemanager/connectors". Each server side language has its own folder there, with the Connector file inside it. To choose which connector to use, the end-user just edits the configuration file '''fckconfig.js''' or the custom [[FCKeditor 2.x/Developers Guide/Configuration/Configuration File\|Configuration File]] and modifies the following key (in this case for the Link Dialog box in PHP):
		+	<pre>FCKConfig.LinkBrowserURL = FCKConfig.BasePath + 'filemanager/browser/default/browser.html?Connector=../../connectors/php/connector.php ;
		+	</pre>

← Older revision		Revision as of 13:27, 18 January 2008
Line 171:		Line 171:
	==== CreateFolder (XML)<br> ====		==== CreateFolder (XML)<br> ====

−	<br>	+	Creates a child folder.
		+	* Sample request:
		+	<pre>
		+	connector.ext?Command=CreateFolder&Type=File&CurrentFolder=/Samples/Docs/&NewFolderName=FolderName
		+	</pre>
		+	* Sample response:
		+	<pre>
		+	<?xml version="1.0" encoding="utf-8" ?>
		+	<Connector command="CreateFolder" resourceType="File">
		+	<CurrentFolder path="/Samples/Docs/" url="/UserFiles/File/Samples/Docs/" />
		+	<Error number="0" />
		+	</Connector>
		+	</pre>
		+	Possible Error Numbers are:
		+	* 0 : No Errors Found. The folder has been created.
		+	* 101 : Folder already exists.
		+	* 102 : Invalid folder name.
		+	* 103 : You have no permissions to create the folder.
		+	* 110 : Unknown error creating folder.
		+
		+	==== FileUpload (HTML) ====
		+
		+	Adds a file in a folder.
		+
		+	This is a special command that doesn't require a XML response. A common "multipart/form-data" post goes with the request. The posted file is named "'''NewFile'''".
		+
		+	In the case a file with the same name already exists, the Connector must automatically rename it adding a progressive number suffix. For example, if the posted file is named "Test.doc", the names to be used, in order, are: "Test(1).doc", "Test(2).doc", Test(3).doc"... and so on.
		+	* Sample request:
		+	<pre>
		+	connector.ext?Command=FileUpload&Type=File&CurrentFolder=/Samples/Docs/
		+	</pre>
		+	* Sample response (simple HTML):
		+	<pre>
		+	<script type="text/javascript">
		+	window.parent.OnUploadCompleted( 'ErrorNumber', 'FileUrl', 'FileName', 'CustomMessage' ) ;
		+	</script>
		+	</pre>
		+	The "OnUploadCompleted" is a JavaScript function that is called to expose the upload result. The possible values are:
		+	* OnUploadCompleted( 0 ) : no errors found on the upload process.
		+	* OnUploadCompleted( 1, , , 'Reason' ) : the upload filed because of "Reason".
		+	* OnUploadCompleted( 201, ,'FileName(1).ext' ) : the file has been uploaded successfully, but its name has been changed to "FileName(1).ext".
		+	* OnUploadCompleted( 202 ) : invalid file.
		+
		+	=== Configuring the Connector ===

@@ Line 144: / Line 144: @@
 Gets the list of the children folders and files of a folder.
-* Sample request:<pre>connector.ext?Command=GetFoldersAndFiles&amp;Type=File&amp;CurrentFolder=/Samples/Docs/</pre>
+* Sample request:
 <pre>connector.ext?Command=GetFoldersAndFiles&amp;Type=File&amp;CurrentFolder=/Samples/Docs/</pre>
 The file size must be expressed as KBytes (KB).