The Editize(TM) API for ASP








General ASP
ASP.NET JavaScript
PHP


Getting Started

Code Generator

API Reference



The Editize™ API for ASP
This section of the manual explains in detail how to add an Editize
field to a form on an ASP-equipped Web site.
Before integrating Editize into your Content Management System (CMS),
you should first install it on your Web server and try out one or more of
the sample scripts. Once you have verified that the samples work, you can
proceed to use Editize anywhere you like on your site.
Step 1: Put the Editize files on your server
Your first step should be to copy or upload the contents of the asp
folder of the Editize distribution to a folder on your Web server.
If you use your own computer as a Web server for development purposes, copy
the files in the asp folder to a folder in your Web root.

Example 1: Uploading to your Web Host
If your Web site is hosted by a Web hosting company, use your FTP program
(or whatever method you normally use to place files on your Web site) to
create a folder called editize in the root of your site. A
file in this directory should be accessible with a URL such as http://www.yoursite.com/editize/filename.
Upload all of the files in the asp folder of the Editize
distributon to this new folder on your Website.
Example 2: Installing on your local test server
If you use Microsoft Internet Information Server (IIS) as a Web
server on your Windows computer, the Web root folder is C:\Inetpub\wwwroot
by default. If you use Apache, the Web root folder is C:\Apache\htdocs
by default. Crate a new folder called editize in your Web root
folder. Copy all of the files in the asp folder of the Editize
distribution to this new folder on your Website.

The folder where you place the Editize files on your server must
not be password protected. None of these files is a security risk, so you
don't need to worry about them being publically accessible.
Here's a list of the files in the asp folder with an explanation
of what each one does:


editize.jar
The Editize Java library file. This contains the Editize
applet.


editize.wsc
The Editize API for ASP. This Windows Script Component will
generate the HTML and JavaScript code neccessary to display the Editize
applet on almost any browser or operating system.


kunststoff.jar
The Kunststoff Look & Feel. Improves the look of the Editize
user interface dramatically, but adds 43KB of Java files for users'
browsers to download the first time they visit your site. If you delete
this file, Editize will simply run without any visual enhancements, and
will load slightly quicker over slow modem connections.


osx.html
A small Web page containing JavaScript that allows Editize
to behave like a form field on Mac OS X browsers.


Default.asp
A sample ASP script written in VBScript that demonstrates how to create
Editize form fields compatible with most browsers.*


Default-jscript.asp
A sample ASP script written in JScript that demonstrates how to create
Editize form fields compatible with most browsers.*


Default-mac.asp
A sample ASP script written in VBScript that demonstrates how to create
Editize form fields compatible with most browsers, including
Internet Explorer and Mozilla on Mac OS 10.1.*


* Files marked with an asterix are sample scripts only, and
are not required for Editize to function on your server.
See the next section to discover the meaning of the file called PLACE
YOUR LICENSE FILE IN THIS DIRECTORY.TXT.
Step 2: Put your Editize license file on your server
If you are installing Editize on your own machine for local testing
(i.e. the site you are working on will be accessible as http://localhost/...
or http://127.0.0.1/...), you do not need a license file and
can skip this step.
In most cases, however, you'll want to deploy Editize on a server
that is accessible to other people. To do this, you will require an Editize
license file. You can get a free trial license file from the Editize
Web site (click 'Download' and choose the type of license you need).
There are two types of Editize licenses. A hostname license
lets you use Editize on a Web site with a particular hostname (e.g.
mysite.com). If your Web site is accessible with more than one hostname, (e.g.
admin.mysite.com and mysite.com), you will need a license file for each hostname.
In most cases, Editize Customer
Support will be happy to issue you with additional hostname licenses for
use on a single Web site at no extra charge.
A private network IP license lets you use Editize
on a Web server within a private network. This is useful for Intranets and
home networks where servers may not neccessarily have hostnames or even fixed
IP addresses. In most cases, Editize customer support will be happy
to issue you with a temporary private network IP license for a test server
while you are developing a site that will eventually be launched on the Internet
with a hostname license.
If you have a hostname license, the file will be called editize.hostname.lic.
If you have a private network IP license, the file will instead be called
editize.lic. In either case, copy or upload the file into the
same folder that you created in Step 1 above. There is a file called PLACE
YOUR LICENSE FILE IN THIS DIRECTORY.TXT to remind you to do this, which
you can delete if you like.
Step 3: Try out a sample script
The Editize folder on your server contains a few sample scripts
for you to try out. Each of these scripts contains a form with an Editize
field in it. When you submit the form, the script should display the HTML
document you created in Editize, and allow you to load it back into
the original form to edit further.
Open your Web browser and type the URL to load the Default.asp
script in the Editize folder on your Web server into the address
field. Note: If your computer is a Macintosh running Mac OS 10.1, load
Default-mac.asp instead.

Example 1: Running the sample on your Web Host
If your Web site is hosted by a Web hosting company, the Editize
files should now be in a folder in the root of your Web site (e.g. http://www.yoursite.com/editize/).
To load the Default.asp sample script, type http://www.yoursite.com/editize/Default.asp
into your browser's address field.

Example 2: Running the sample on your local test server
If you've placed the Editize files in a folder on your local test
server, you should be able to run the Default.asp test script
by simply typing http://localhost/editize/Default.asp into
your browser's address field.

Have a play with the sample form, submit a document, and then re-open it
for editing. If you run into any problems, see the Troubleshooting
section of this manual. Otherwise, you're good to go!
Step 4: (Optional) Register the Editize
Component on your Server
To slightly simplify the code in your ASP pages and improve performance of
the Editize API for ASP, you can register the Windows Script Component
on your server. You can only do this if you have direct access to the server,
or if your Web host is willing to do it for you.
Complete the following steps (or ask your Web host to complete them for you)
to register the Windows Script Component in Windows on your Web server:

Copy the editize.wsc file (found in the asp
directory of this distribution) to a convenient folder on the server computer.
The SYSTEM32 subfolder of the Windows folder (e.g. C:\WINNT\SYSTEM32)
is a common choice, but you can put it elsewhere if you prefer. Please
note: the file may not reside on a network drive.
Right-click on the file in its new location and choose Register from the
pop-up menu.
A message box should be displayed confirming that registration was successful.




The Editize API for ASP is now registered as a Windows Script Component
on your server computer. Should you wish to unregister it at a later date,
simply right-click the file and choose Unregister, and then delete the editize.wsc
file.
If you have any trouble registering the component, please refer to the Troubleshooting
section of this manual.
Step 5: Integrate Editize into your own scripts
You can now add Editize fields to any form on your site.
Basic Syntax
As mentioned above, Editize is designed as a drop-in replacement
for the HTML <textarea> tag. We will therefore explain how to use it
by comparing it with that tag.
Here is a typical HTML form containing a <textarea> tag:
<form action="..." method="post">
<textarea name="example">
This is the document that the textarea will contain initially.
</textarea>
<input type="submit" value="Submit" />
</form>
The ASP API for Editize is designed so that you can simply replace
the <textarea> tag with some brief code to put an Editize
field in its place.
To quickly obtain the code to add an Editize to a form in your Web
site, use the Code Generator to generate it automatically.
Alternatively, read on to learn how to write the code yourself.
Here is an example of the simplest means to invoke Editize as a
form field:
<form action="..." method="post">
<%
Dim ed
Set ed = Server.CreateObject("Editize.aspapi")
ed.name = "example"
Response.Write ed.DisplayContent("<p align=""center"">This is the document that Editize will edit.</p>")
%>
<input type="submit" value="Submit" />
</form>
The Server.CreateObject line in the above will only work if
the Editize Windows Script Component is registered on your Web server (see
Component Registration above). If you are
unable or unwilling to register the component, you can use the following slightly
less efficient syntax:
<form action="..." method="post">
<%
Dim ed
Set ed = GetObject("script:" & Server.MapPath("Editize.wsc"))
ed.name = "example"
Response.Write ed.DisplayContent("<p align=""center"">This is the document that Editize will edit.</p>")
%>
<input type="submit" value="Submit" />
</form>
Similarly, in an ASP page set to use JScript as the scripting language:
<form action="..." method="post">
<%
var ed = Server.CreateObject("Editize.aspapi");
ed.name = "example";
Response.Write(ed.DisplayContent("<p align=\"center\">This is the document that Editize will edit.</p>"));
%>
<input type="submit" value="Submit" />
</form>
Or with an unregistered component file:
<form action="..." method="post">
<%
var ed = GetObject("script:" + Server.MapPath("Editize.wsc"));
ed.name = "example";
Response.Write(ed.DisplayContent("<p align=\"center\">This is the document that Editize will edit.</p>"));
%>
<input type="submit" value="Submit" />
</form>
The meaning of the 4 lines of VBScript (or 3 lines of JScript) should be
fairly apparent to experienced ASP developers. The first line or two creates
an Editize.aspapi object, which will do all the work of generating
the HTML and JavaScript code to display the Editize applet as a form
field.
The next line sets the name property of the object, which is
equivalent to the name attribute of a <textarea>
tag. You should always specify a field name in this way when you use Editize,
although if you don't a default of editize will be used.
Finally, the third line displays the Editize field; that is, it
outputs all of the HTML and JavaScript code to place the Editize
field in the page at that point. In this example, we have passed the initial
document to be displayed (the equivalent of the contents of the <textarea>
tag) to the DisplayContent method. Alternatively, the Display
method, which takes no arguments, can be used to display Editize
with a blank document.
Configuration Attributes
The Editize applet is very configurable. You can customize the formatting
applied by the various styles and tools available, and even specify that certain
features should be disabled entirely if they are not appropriate for your
environment.
By default, the Editize API for ASP enables all of Editize's
formatting tools with default format settings. This section demonstrates how
to use the properties supported by the Editize API for ASP to modify
these defaults.
To set the values of properties, simply specify them as you did for the name
attribute in the simple example above. For instance, to create an Editize
field with a base font of 12-pixel Verdana, you would use the following VBScript
code (or the equivalent JScript):
<form action="..." method="post">
<%
Dim ed
Set ed = Server.CreateObject("Editize.aspapi")
ed.name = "example"
ed.basefontface = "Verdana" ' SETS THE FONT FACE
ed.basefontsize = 12 ' SETS THE FONT SIZE
Response.Write ed.DisplayContent("<p align=""center"">This is the document that Editize will edit.</p>")
?>
<input type="submit" value="Submit" />
</form>
Note that you have to set all the properties you want before you call the
Display or DisplayContent methods.
A list of all supported properties with examples for each is provided in
the Reference section of this manual, or you
can use the Code Generator to select all the properties
you want from a list and have the code generated for you automatically.
Step 6: (Optional) Providing a List of Images
By default, the Insert Image tool in Editize will prompt the user
for the URL of the image he or she wishes to insert. Since it can be a fairly
tedious to hand-type the URL for every image, Editize also provides
a method to specify a list of images that users may quickly choose from.
The imglisturl property lets you set a URL from which Editize
will download a list of images to present it to the user in the Insert
Image dialog. The given URL may refer to a server-side script (e.g. to provide
an up-to-date list of images stored in a content management system). If a
static list of images is all that you need, you can simply point Editize
to a text file of the required format residing on your server.
The documentation for imglisturl
in the Reference section of this manual explains
the required format of the image list. A sample script written in PHP called
imglist.php that produces a list of all the images in a given
directory and its subdirectories is provided in the php folder
of this distribution.
Step 7: (Optional) Improving Browser Compatibility
By simply replacing <textarea> tags in your forms with
the code neccessary to display Editize, you will be able to provide
WYSIWYG HTML editing to users of Internet Explorer 4+, Netscape 6+, or Mozilla
for Windows or Linux. To support other browsers, you must make a few more
changes to your code.

Using a Java Submit Button
The following browsers do not support the standard for JavaScript-to-Java
communication, upon which Editize normally relies:

Opera 6.01+
Netscape 4.x
Internet Explorer for Mac OS 10.2 (OS X "Jaguar")
Mozilla for Mac OS 10.2 (OS X "Jaguar")

To support these browsers, you must also replace the submit button in your
form with a Java applet. Instead of an <input type="submit"/>
tag, you should instead use a line of ASP code similar to the following
to add a Java-based Submit button to your form:

Response.Write(ed.DisplaySubmit("Submit",100,30))
The DisplaySubmit function of the Editize API shown
here takes three parameters: the text to appear on the submit button ("Submit"
in this case), the width of the button (100 pixels in this case), and the
height of the button (30 pixels in this case). Adjust these parameters to
your preferred values if you wish.
The Default.asp sample script included in the asp
folder of this archive uses this method to provide greater browser compatibility.
Refer to the documentation for displaySubmit
in the Reference section of this manual for further
details.
Using an Integrated Submit Button
The Java support in Mac OS 10.1 (OS X) is affected by a bug that causes the
Web browser to hang if more than one signed applet appears on a page. On such
a page, Java will attempt to display multiple Security Alert dialog boxes
at once to allow the user to accept the security certificate for each of the
applets. These multiple dialogs cause the browser to hang with the 'spinning
rainbow disc' mouse cursor.

To avoid this bug, you must only use one Editize field on any given
page. In addition, since the Java-based Submit button discussed in the previous
section uses its own signed Java applet, you must remove this button and instead
set the showsubmitbutton
property of the Editize field, which will cause it to display
a Submit button at the bottom of the Editize field.
Additionally, the submitbuttonlabel
property lets you specify the text label that appears on the integrated
submit button.

A sample ASP script that uses this method to provide a Mac OS 10.1-compatible
Editize field is available as Default-mac.asp in the
asp directory of this distribution.

Getting Started | Code
Generator | API Reference