This section of the manual explains in detail how to add an Editize field to a form on any 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.
Since most cases where Editize will be used will involve server-side scripting of some form or another, you should usually endeavour to use an API that will integrate well with your server-side script. In addition, the JavaScript API involves downloading significantly more code for the user than a server-side method. For these reasons the JavaScript API should be seen as a 'method of last resort' when no compatible API is available to you.
Your first step should be to copy or upload the contents of the javascript
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 javascript
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 thejavascript
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 thejavascript
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 javascript
folder with an
explanation of what each one does:
editize.jar |
The Editize Java library file. This contains the Editize applet. |
editize.js |
The Editize API for JavaScript. This JavaScript library 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 Editize uses automatically to behave like a form field on Internet Explorer for Mac OS X. |
index.php * |
A sample PHP script that demonstrates how to create Editize form fields compatible with most browsers with the JavaScript API. |
default.asp * |
A sample ASP script that demonstrates how to create Editize form fields compatible with most browsers with the JavaScript API. |
* 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.
The Editize folder on your server contains a couple of 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.
The samples provided are written in ASP and PHP. Obviously, if your Web server supports either of these languages, you are better off using the ASP or PHP APIs instead. Nevertheless, you can examine the code of the examples to see how they work.
If you're a ColdFusion developer, the Editize API for JavaScript will work well for you until a dedicated ColdFusion API becomes available. See the Troubleshooting section of this document for a little how-to guide on how to put Editize to work in a ColdFusion page.
You can add the following code to the top of any Web page to load the Editize API for JavaScript:
<script language="JavaScript" src="path/to/editize.js"></script>
For instance, if you placed the Editize files including editize.js
in the C:\InetPub\wwwroot\editize
folder (where C:\InetPub\wwwroot
is the root of your Web site), you can simply type:
<script language="JavaScript" src="/editize/editize.js"></script>
You can now add Editize fields to 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 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 JavaScript 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"> <script language="JavaScript"> var ed = new Editize(); ed.name = 'example'; ed.display('<p align="center">This is the document that Editize will edit.</p>'); </script> <input type="submit" value="Submit" /> </form>
The meaning of the 3 lines of JavaScript code should be fairly apparent to
experienced Web developers. The first line creates an Editize
object,
which will do all the work of generating the HTML and JavaScript code to display
the Editize applet as a form field.
The second 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 display
method, though Editize will default
to a blank document if you don't pass a document to it.
In typical use, you'll generate the initial document portion of this code with a fragment of server-side script in whichever language you use on your site.
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 JavaScript 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 JavaScript 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 code:
<form action="..." method="post"> <script language="JavaScript"> var ed = new Editize(); ed.name = 'example'; ed.basefontface = 'Verdana'; // SETS THE FONT FACE ed.basefontsize = 12; // SETS THE FONT SIZE ed.display('<p align="center">This is the document that Editize will edit.</p>'); </script> <input type="submit" value="Submit" /> </form>
Note that you have to set all the properties you want before you call the
display
method.
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.
The following browsers do not support the standard for JavaScript-to-Java communication, upon which Editize relies:
Editize therefore uses an alternative submission method on these browsers. As a side effect, when the form is submitted using an HTML submit button (<input type="submit">
), that submit button's value is not submitted to the server for processing along with the rest of the form data.
To make HTML submit buttons submit correctly in all supported browsers, you must include the following JavaScript code immediately after the closing </form>
tag for the form that contains your Editize field(s):
<script language="JavaScript"> ed.endForm(); </script>
The endForm
method of the Editize API shown here outputs some additional HTML and JavaScript code that makes HTML submit buttons work correctly alongside the Editize fields in your form. This code must occur in the page after your form, which is why it must be output separately using this method.
On top of this, Netscape 4.x by default is not supported by the Editize API for JavaScript, as it contains bugs that prevent this alternative submission method from working properly. By default, Editize fields will be displayed as standard <textarea>
fields in Netscape 4.x.
To run Editize in Netscape 4.x, you need to use the endForm
method as described above, and you must additionally set the ns4support
property of your Editize field(s) to true
:
ed.ns4support = true;
Remember, although the call to endForm
goes after your closing </form>
tag, you must set the ns4support
property along with your other Editize field properties before calling display
.
The index.php and default.asp sample scripts included in the javascript
folder of this archive use the above techniques to provide maximum browser compatibility.
Refer to the documentation for endForm
and ns4support
in the Reference section of this manual for further details.
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.