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.
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 callededitize
in the root of your site. A file in this directory should be accessible with a URL such ashttp://www.yoursite.com/editize/filename
. Upload all of the files in theaspdotnet
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 isC:\Inetpub\wwwroot
by default. If you use Apache, the Web root folder isC:\Apache\htdocs
by default. Crate a new folder callededitize
in your Web root folder. Copy all of the files in theaspdotnet
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
.
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.
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:
editize
folder under Web Sites. Unless your server
hosts multiple sites, it should be called Default Web Site.editize
folder you created in Step 1 above.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.
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 theDefault.aspx
sample script, typehttp://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 theDefault.aspx
test script by simply typinghttp://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!
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.
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="<p align="center">This is the document that Editize will edit.</p>"> </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 (< > "
).
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="<p align="center">This is the document that Editize will edit.</p>"> </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.
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 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.
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.