XStandard Developer's Guide: Web Services: Subdocument

The XHTML WYSIWYG Editor For Desktop & Web Applications

Subdocument

Overview

Subdocuments are chunks of reusable content that authors insert into documents as required. Subdocuments are essentially custom elements that act as placeholders for content stored outside the document, within the CMS. However, whereas placeholders appear in the document as icons, in lieu of content, subdocuments display the content itself inside the document. One example of a reusable subdocument is an author's biography that can be inserted at the end of a number of articles.

Screen shot of a custom element used as a subdocument.

The Subdocument Web Service serves subdocuments to XStandard. XStandard then replaces custom elements with content from subdocuments and renders them in WYSIWYG mode as read-only content.

Requirements

  • ASP / ASP.NET on Windows
  • PHP 4.3.0+ on Linux / FreeBSD / Windows

ASP Installation

  1. Run the setup program called x-web-services-asp.exe Instructions for downloading this program are sent to you when you request download instructions for XStandard Pro.
  2. Set "Read & Execute" file permissions on C:\Program Files\XStandard Web Services to Everyone.
  3. Copy subdocument.asp, subdocument-example-A.txt, subdocument-example-B.txt, subdocument-example-C.txt, subdocument-example-D.txt, subdocument-example-E.txt to C:\InetPub\wwwroot (or another path that has an IIS virtual directory mapping) and set "Read & Write" file permissions on this folder to Everyone.

ASP.NET Installation

  1. Unzip the file called x-web-services-aspx.zip Instructions for downloading this file are sent to you when you request download instructions for XStandard Pro.
  2. Copy subdocument.aspx, subdocument-example-A.txt, subdocument-example-B.txt, subdocument-example-C.txt, subdocument-example-D.txt, subdocument-example-E.txt to C:\InetPub\wwwroot (or another path that has an IIS virtual directory mapping) and set "Read & Write" file permissions on this folder to Everyone. Into a sub-folder, copy the bin folder.

PHP Installation

  1. Unzip the file called x-web-services-php.zip Instructions for downloading this file are sent to you when you request download instructions for XStandard Pro.
  2. Copy subdocument.php, subdocument-example-A.txt, subdocument-example-B.txt, subdocument-example-C.txt, subdocument-example-D.txt, subdocument-example-E.txt to a folder on your Web site. Make sure this folder has the broadest possible permission settings. On Unix-based systems, set permissions to 0777.

Testing

In a Web browser, navigate to the URL where the Subdocument service is located. For example: http://localhost/subdocument.asp

If you don't see Status: Ready in the browser, the Web Service is not correctly installed. The most common cause of this is incorrectly set file permissions.

Configure XStandard

To set up XStandard to use the Directory service, modify the following <param> tag:

Property SubdocumentURL

(Available in XStandard Pro)
Absolute URL to a Subdocument Web Service. For testing purposes, the following URL is available:
http://soap.xstandard.com/subdocument.aspx

Configure Subdocument Web Service

In subdocument.asp, subdocument.aspx or subdocument.php, search for "ADD CUSTOM CODE HERE". The following is an example from subdocument.aspx:

  1. if(soap.Action == "doSubdocumentDescribe")
  2. {
  3. /*
  4. ** -------------------------------------------------------
  5. ** ADD CUSTOM CODE HERE
  6. ** -------------------------------------------------------
  7. */
  8. soap.AddSubdocumentDefinition("include", "doc");
  9. }

The AddSubdocumentDefinition() function is used to define custom elements that will act as subdocuments. The first argument is the custom element name. The second argument is the attribute that will contain the ID of the subdocument. Based on the previous example, the following custom element will act as a subdocument:

  1. <include doc="A" />

The following code is used to replace custom elements with content:

  1. else if(soap.Action == "doSubdocumentDownload")
  2. {
  3. string id = soap.GetProperty("id"); //id
  4. /*
  5. ** -------------------------------------------------------
  6. ** ADD CUSTOM CODE HERE
  7. ** -------------------------------------------------------
  8. */
  9. if (id == "A") {
  10. soap.SetSubdocument(soap.ReadFromFile(Server.MapPath("subdocument-example-A.txt")));
  11. }
  12. }

The if statement is used to check the subdocument ID and then the SetSubdocument() function is used to set the subdocument content from the given subdocument. In the example above, content for the subdocument is read from a file. You can customize this code to read from your CMS.

Notes

If subdocument content contains block elements (<p>, <table>, <ol>, <ul>, <dl>, <blockquote>, <h1> to <h6> and <address>), then the custom element that is used for the subdocument should be defined as a block element. This is done via the following <param> tag:

  1. <param name="CustomBlockElements" value="include" />