The Editize(TM) API for ASP.NET








General ASP
ASP.NET JavaScript
PHP


Getting Started

Code Generator

API Reference



The Editize™ API for ASP.NET
This section of the manual explains in detail how to add an Editize
field to a form on an ASP.NET-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 aspdotnet
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 aspdotnet 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 aspdotnet 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 aspdotnet 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 aspdotnet folder with an explanation
of what each one does:


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


bin/EditizeDotNet.dll
The Editize API for ASP.NET. This .NET assembly contains two
ASP.NET Server Controls that 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.aspx
A sample ASP.NET Web Form written in VB.NET that demonstrates how to
create Editize form fields compatible with most browsers.*


Default-csharp.aspx
A sample ASP.NET Web Form written in C# that demonstrates how to create
Editize form fields compatible with most browsers.*


Default-mac.aspx
A sample ASP.NET Web Form written in VB.NET 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: Create a Web Application for the Editize samples
ASP.NET looks for assemblies such as (EditizeDotNet.dll) in
a bin folder in the root of the current Web application. For
the Editize sample scripts to be able to find the Editize
API for ASP.NET on your server, the folder you created on your site in Step
1 must be set as the root of a Web application.
The following steps will walk you through the process of setting up your
new editize folder as the root of a new Web application:

On the server, open the Windows Control Panel.
Open the Administrative Tools folder.
Open the Internet Information Services console.
Expand the tree on the left to find the Web site that contains your new
editize folder under Web Sites. Unless your server
hosts multiple sites, it should be called Default Web Site.
Under Default Website, locate and select the editize
folder you created in Step 1 above.
Right-click the folder and choose Properties from the pop-up
menu.
In the properties window that opens, the Application name field
is disabled to indicate that this folder is not the root of a Web application.

Click the Create button next to the Application name
field to create a new Web application rooted in this folder. The Application
name field becomes enabled and the name of the folder becomes the name
of the new Web Application.

Click OK. Back in the Internet Information Services console, you should
notice that the folder in question now has a special Web Application icon,
instead of the plain folder icon it displayed previously.



The editize folder on your server is now the root of a Web Application.
Any ASP.NET scripts in this folder (or any of its subfolders) will be able
to find the EditizeDotNet.dll file in the bin subfolder
of the editize folder.
Note: If you later want to use the Editize API for ASP.NET
to add Editize fields to Web Forms elsewhere on your Web site, you will have
to copy the EditizeDotNet.dll file to the bin directory
of the Web Application to which those Web Forms belong.
Step 4: 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.aspx
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.aspx 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.aspx sample script, type http://www.yoursite.com/editize/Default.aspx
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.aspx test script
by simply typing http://localhost/editize/Default.aspx 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 first make sure you've followed
the instructions in Step 3 above. If the problem persist, see the Troubleshooting
section of this manual. Otherwise, you're good to go!
Step 5: Integrate Editize into your own Web Forms
If you use Visual Studio .NET to build your ASP.NET Web sites, you can skip
this section and read Using Editize in Visual Studio .NET
instead.
Add the following code to the top of any ASP.NET page to load the Editize
ASP.NET Server Control:
<%@ Register TagPrefix="SitePoint"
Namespace="EditizeDotNet" Assembly="EditizeDotNet"
%>
Feel free to use a different TagPrefix value if you like (see
the documentation for ASP.NET to learn more about tag prefixes), but the NameSpace
value must be "EditizeDotNet" and the Assembly
value must match the name of the .dll file you placed in the
bin directory (also "EditizeDotNet") of
the page's Web application.
You can now use the Editize ASP.NET Server Control in any form in
this page.
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 ASP.NET form containing a <textarea> tag:
<form method="post" runat="server">
<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 an ASP.NET tag 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 method="post" runat="server">
<SitePoint:Editize runat="server" id="example"
content="&lt;p align=&quot;center&quot;&gt;This is the document that Editize will edit.&lt;/p&gt;">
</SitePoint:Editize>
<input type="submit" value="Submit" />
</form>
Experienced ASP.NET developers should recognize this immediately. We have used
a special tag named <SitePoint:Editize> (where you replace
SitePoint with the TagPrefix you specified at the
top of the page, if you chose to use something different). This tag is translated
by ASP.NET into the HTML and JavaScript code that is neccessary to display an
Editize field as part of your form.
The attributes of the tag configure the behavior and appearance of the Editize
field. The runat="server" attribute is required
by all ASP.NET Server Controls, so it should always be there. The id="example"
attribute serves to uniquely identify this tag in your page. If you're not terribly
familiar with ASP.NET, think of it as the equivalent of the <textarea>
tag's name attribute.
Finally, the content attribute specifies the initial contents
of the field to be displayed when the page is first loaded. As you can see,
this is a simple fragment of HTML. Since this value is specified as an attribute,
the special HTML characters (< > ") must be translated
into their respective HTML character entities (&lt; &gt; &quot;).
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 ASP.NET Server Control 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.NET to
modify these defaults.
To set the values of properties, simply specify them as you did the other
attributes 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 ASP.NET
code:
<form method="post" runat="server">
<SitePoint:Editize runat="server" id="example"
basefontface="Verdana" basefontsize="12"
content="&lt;p align=&quot;center&quot;&gt;This is the document that Editize will edit.&lt;/p&gt;">
</SitePoint:Editize>
<input type="submit" value="Submit" />
</form>
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 <SitePoint:EditizeSubmitButton>
similar to the following to add a Java-based Submit button to your form:
<SitePoint:EditizeSubmitButton ID="EditizeSubmitButton1" runat="server" Text="Submit" Codebase="../editize/" Width="100px" Height="30px" />
The EditizeSubmitButton tag (also provided by the EditizeDotNet.dll
file) takes six parameters: the ID, the runat attribute
(runat="server"), the Text to appear on
the Submit button ("Submit" in this case), the Codebase
URL to indicate where editize.jar is located (see the Codebase
attribute for the Editize tag above), 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.aspx sample script included in the aspdotnet
folder of this archive uses this method to provide greater browser compatibility.
Refer to the documentation for
EditizeSubmitButton 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.NET Web Form that uses this method to provide a Mac OS 10.1-compatible
Editize field is available as Default-mac.aspx in the
aspdotnet directory of this distribution.
Using Editize in Visual Studio .NET
Using ASP.NET Server Controls such as the Editize API for ASP.NET
is very easy in Microsoft Visual Studio.NET. All you need to do is add the
Editize ASP.NET Server Controls (Editize and EditizeSubmitButton)
to your Visual Studio .NET Toolbox, and Visual Studio .NET will take care
of almost everything.
To add the Editize ASP.NET Server Control to your Toolbox, open
the Toolbox window if it is not already open and expand the Web Forms section
of the Toolbox. Right-click on the background of the Toolbox and select "Customize
Toolbox..." from the pop-up menu. In the Customize Toolbox window, select
the ".NET Framework Components" tab and click the "Browse..."
button. Browse to and select the EditizeDotNet.dll file you received
with this distribution (make sure it is given a permanent home, where Visual
Studio .NET will be able to find it in future). The Editize and
EditizeSubmitButton components will be added to the list of .NET
Framework Components. Make sure they are checked, and then click OK. You'll
now see the Editize components listed in the Toolbox window under Web Forms.
To add the Editize ASP.NET Server Control to an ASP.NET page in
Visual Studio, you can now simply double-click on the item in the Toolbox,
or drag the item directly to your page. Visual Studio .NET will take care
of registering the TagPrefix at the top of the page, copying
the EditizeDotNet.dll file into the bin directory
of your Web Application, and adding a reference to the library to make Visual
Studio .NET's IntelliSense and Properties Window features aware of the control.
Once you've added an Editize ASP.NET Server Control to an ASP.NET
page, you can edit its properties directly in the Properties Window, where
all of the properties are listed in appropriate categories and with short
descriptions. To assign an event handler to the ContentChanged
event supported by the Control (see Control
Events in the Reference section), all you
have to do is double-click on the Editize Control in the page while
in Design view; Visual Studio .NET will create the event handler method and
will take you to it so that you can write the code for it by hand. The EditizeSubmitButton
component works the same way.
Please note that, at this time, you must still deploy the editize.jar,
kunstsoff.jar, osx.html, and license files on your
site manually.

Getting Started | Code
Generator | API Reference