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.

Upgrading?
For information on updating an existing Editize installation to a new release, see below.

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 quicker over slow modem connections.
osx.html A small Web page containing JavaScript that allows Editize to behave like a form field on Internet Explorer for Mac OS X.
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.

* 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 three 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. The majority of trial licenses we issue are hostname licenses.

A domain license lets you use Editize on all Web sites within a particular domain (e.g. mydomain.com). With a domain license, you don't need additional licenses to use Editize on subdomains (e.g. admin.mydomain.com). When you buy Editize, you'll get a domain license for the domain of your choice.

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.

In most cases, Editize Customer Support will be happy to issue you with additional licenses if you need them at no extra charge, so long as they are only used to run Editize on a site for which you have already bought a license. Feel free to contact us if you have any questions about licensing Editize for your needs.

If you have a hostname or domain 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:

  1. On the server, open the Windows Control Panel.
  2. Open the Administrative Tools folder.
  3. Open the Internet Information Services console.
  4. 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.
  5. Under Default Website, locate and select the editize folder you created in Step 1 above.
  6. Right-click the folder and choose Properties from the pop-up menu.
  7. 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.
  8. 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.
  9. 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.

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 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

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 Control (Editize) 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. Check only the Editize component (EditizeSubmitButton is included for compatibility with older releases of Editize), and then click OK. You'll now see the Editize component 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.

Please note that, at this time, you must still deploy the editize.jar, kunstsoff.jar, osx.html, and license files on your site manually.

Upgrading to a New Version

In most cases, all you need to do to upgrade to a new release of Editize is to upload the new versions of editize.jar, editize.js, osx.html, and optionally kunststoff.jar over the old versions already on your server. It is very important that you replace all of these files, as changes made to one in a particular release often rely on changes made to another.

Occasionally, we add new features to Editize. Very occasionally, we change the way the APIs work. In both of these cases, you may need to make some changes to the page(s) on your site(s) that use Editize to make the new version work the way you expect it to. Always read the Revision History for the new release to find out when such changes are made.