wysiwyg_web_edit 1.0 - Readme_english.txt for wysiwyg_web_edit editor
developed at Universitat Internacional de Catalunya (www.unica.edu)
(16/07/2001), starting from the contributions of Fernando Álvarez
(fer@onplaza.com).

The wysiwyg_web_edit editor is a web-based WYSIWYG HTML editor dessigned to generate
HTML code from a WYSIWYG view so you don't need to know HTML to use it. You can
embed it in your web pages so it can improve significantly your web-applications, 
specially if you want common users to contribute in the content management task.
It runs on both Netscape and Explorer browsers.

You can transfer the generated HTML code directly to the server by submiting it.
Then you can easily store it in your database.

It can be used as an independent application or embedded in any web page, and it
is configurable by the programmer who is embedding it in one of his pages. 

The wysiwyg_web_edit is written in HTML and Javascript, and it uses PHP as a
server-side language.( Though there is a version written exclusively in
Javascript and HTML. See chapter '4.- wysiwyg_web_edit without PHP' of this document
for further information). 

You can embed multiple instances of the editor in the same page.( See chapter
'3.- Multiple ns-editor's in one page' of this document for further
information).

It has functions to build the most common HTML structures: tables, links,
formatted text, images, numbered lists and non-numbered lists, etc. However
there are no functions for frames and forms.

It has been tested with Netscape 4.76 and Explorer 5.0

It can be used in three different languages: cathalan (the language from
Catalonia in Spain), spanish and english. Language can be easily changed by just
modifying the value of a parameter in the page where the editor is embedded.

If you have any doubt or suggestion you can contact gabi@unica.edu.

                  INDEX
                  =====
	0.- Introduction

	1.- Installation

	2.- Embedded use of wysiwyg_web_edit.

	3.- Multiple wysiwyg_web_edit's in one page.

	4.- wysiwyg_web_edit without PHP.

	5.- Save function.

	6.- Server reception of the HTML code.

	7.- Known Bugs.

================================================================================

0.- Introduction

wysiwyg_web_edit consists in an ActiveX control (Dhtmled.ocx) supplied in the
standard installation of Explorer 5.0 and higher, which is run on Netscape using
a plug-in specifically dessigned to run ActiveX controls on Netscape. (This
plug-in has been developed by Esker Software (www.esker.com) and it is a free
distribution software. Read chapter '1.- Installation' of this document for
further information).

Moreover, it has a toolbar which act on the edition area using JavaScript code.
This code acts on the ActiveX control through the plug-in, controlling what is
displayed in the edition area. Thus, edition is completely WYSIWYG and really
comparable to the most common text editors.(Even the cut, copy and paste
functions are OLE compatible so you can paste typical office objects as
datasheets or formatted text.)

Once you have created the page, the THML code can be easily accessed by a
JavaScript function specified in one of the PHP parameter which are passed to
the wysiwyg_web_edit PHP script.

The wysiwyg_web_edit's page is dinamically generated in the server according to the
configuration specified in the page where the wysiwyg_web_edit is embedded. This
configuration is detailed in chapter '2.- Embedded use of wysiwyg_web_edit' of this
document. To implement this we have used PHP as a server-side language.

Once the editor has been loaded (with the plug-in), the client can use all the
functionalities. What will be done when the client clicks on 'Save' button
depends on the save function specified in the '$funcio_save' parameter or the
page specified in the '$action_submit' parameter.

For instance, the HTML code can be send (by submit or in the url) to a page in
the server and there can be stored in a database. Thus, wysiwyg_web_edit is a powerful
tool to manage a website using a database.

wysiwyg_web_edit has the following functionalities:

	1.- New Document.

	2.- Save (trough a JavaScript function defined by the programmer or by
	    submit of the content to a server-page).

	3.- Copy, Cut and Paste : OLE compatible, so you can paste Excel tables and
	    Word texts.

	4.- Undo and Redo: you can undo and redo actions until the beginning of the
	    document.

	5.- Find: find a string in the text.

	6.- Links generation.

	7.- Images insertion.

	8.- Background colour of the document.

	9.- Tables insertion.

	10.- Functions to manage the table: add a row or a column, delete a row 
	     or a column, add and delete cells, combine and divide cells.

	11.- Formatted text: text font and size, text colour and foreground
	     colour, bold, italic, underlined.

	12.- Paragraph align: left, right, centered.

	13.- Numbered and non-numbered lists.

	14.- Indent and unindent blocks.

================================================================================

1.- Installation

To use the wysiwyg_web_edit you must install several components in the server and several
components in all the clients where you want to use the editor.

CLIENT INSTALLATION

NETSCAPE INSTALLATION:

To run on Netscape, the wysiwyg_web_edit requires the installation in the client of
several components:

A) Esker's Plug-in to run ActiveX controls on Netscape. It's free distribution 
   and you can automatically install it at the following mailing list at Yahoo:

	http://groups.yahoo.com/group/esker-activex-plugin/

	You must register in the group to access to the download of the plug-in.
	Registering is free and easy.

	Once registered enter in the group and you can access the installation
	script at:
	
	Files/Versions/Esker ActiveX Plug-in 4.5/demo/npeskp32/install.htm

	For Netscape 6.0 you should install the version 6.0 of the plug-in. The
	script can automatically install the plug-in only if SmartUpdate is enabled.

	(In fact, to install the plug-in is enough to copy the file NPESKP32.dll
	in the plug-ins drectory of Netscape).

B) You must also install the ActiveX PropertyAccessor which can be found in the
   same mailing list at:
   
	http://groups.yahoo.com/group/esker-activex-plugin/

	You must register in the group to access to the download of the 
	PropertyAccessor. Registering is free and easy. 

	Once registered you can access the file accessor.ocx at:
	
	Files/Miscellaneous/Properry Accessor/accessor/accessor.ocx

	You must copy the file 'accessor.ocx' in any directory of the local hard
	disk (for instance in c:\my_path\) and then you must execute in the command
	line:

				regsvr32.exe "c:\my_path\accessor.ocx"

C) You should have installed the ActiveX control Dhtmled.ocx. This is done (by
default) when you install Explorer, so if you if you have Explorer installed you
don't have to do anything. If you don't have Explorer and you don't want to
install it, you can just copy the files Dhtmled.ocx and TRIEDIT.dll (you can get
them from any client with Explorer installed) in the directory (if it doesn't
exist you must create it):
'Program Files / Common Files / Microsoft Shared / TRIEDIT'.

EXPLORER INSTALLATION:

Explorer does not require any specific installation because the ActiveX control 
Dhtmled.ocx is in the default installation of Explorer 5.0+.

If it doesn't run in Explorer you should copy the file Dhtmled.ocx and
TRIEDIT.dll (which you can find in any Windows98 client which has installed
normally the Explorer).You can find the file usually in 
'Program Files / Common Files / Microsoft Shared / TRIEDIT'.

SERVER INSTALLATION

   Once installed the client components you should copy all the files in
   wysiwyg_web_edit.tar.gz in a directory (and this will preserve the predefined 
   structure of directories with all the files *.gif in the subdirectory 
   'images').

   Then you must edit the file "wysiwyg_web_edit.h3p". In the first two lines you
   should put the values of two parameters:

    $url_path_editor = "http://my_server/my_applications/wysiwyg_web_edit/"; // URL of
    the directory of the application

	$abs_path_editor = "/absolute_path/wysiwyg_web_edit/"; // Abolute path (for the web
	pages server), of wysiwyg_web_edit in the server. This is essential fo the PHP
	script to be able to include the necessary files.
	
The application needs at least PHP 3.0 in the server. If you don't have PHP
there is a no configurable version written exclusively in HTML and JavaScript.
See chapter '4.- wysiwyg_web_edit without PHP' of this document for further
information.

REMARK: all the PHP files of the application have '*.h3p' extension because this
is the extension our apache server uses to recognize which files should be
parsed by PHP.

If you are using another extension (for example 'php3' ) you should:

a) Change the extensions of all the files '*.h3p' to your PHP extension.

b) Replace the string '.h3p' by your extension in all the files of the
   application.

Or, perhaps more simple, you can configure your web server to recognize '.h3p'
as a PHP extension.

================================================================================

2.- Embedded use of wysiwyg_web_edit

In order to use the wysiwyg_web_edit embedded in your page you should the
following:

A) In the PHP document where you are embedding the wysiwyg_web_edit you should
   put the parameters lists. The list and signification of the parameters is the
   following :

	$nom_editor = "Editor_1"; // Name of the object editor that will be embedded
	in the page. It must be different from the name of any JavaScript and HTML
	objects in the page. In case you include more than one instance of the
	editor in the same page, each name must be different.
	
	$idi_edit = 'eng'; // Language: 'eng' -> english, 'esp' ->
	spanish, 'cat' -> cathalan.

	$document_complet = 1; // If it is 1 you are going to edit a complete HTML
	document so the code will include the <body> ... </body> tags . If it is 0
	the tags <body> ... </body> will automatically be stripped.

	$funcio_save= 'my_save_function(code);'; // Name of the JavaScript function
	that will be called when the user click the 'Save' button.  It must always
	have a parameter that will contain the HTML code. This function must be
	supplied by the programmer who is embedding the wysiwyg_web_edit and from this
	function you can just send the code to a page in the server , etc. If you
	don't want to write a JavaScript function you can just submit the HTML code
	to a page using next parameter.

	$action_submit = "sample_submit.h3p"; // Url of the page which is going to
	receive the HTML code when the user click on 'Save' button. This behaviour 
	is enabled only if the parameter $funcio_save is empty.

	$editor_width = 700; // Width (in pixels) of the edition area.

	$editor_height = 400; // Height (in pixels) of the edition area.
	
	$content_inicial = "Hello World"; // Initial content of the edition area
	when it is just loaded. It must be HTML code. It cannot contain line breaks
	(you should type line breaks as <br>).

B) Then, once the parametrization is specified, you should put:

	include " ...wysiwyg_web_edit_path/wysiwyg_web_edit.h3p"; 

WITH THE FILES OF THE APPLICATION THERE IS AN EXAMPLE OF HOW TO DO THIS. IT IS
THE FILE 'Sample.h3p'.

REMARKS
=======

In the document where the wysiwyg_web_edit will be embedded you can't use the following 
variable names and function names:

* For PHP:
	-Variables:
		$nom_editor
		$idi_edit
		$document_complet
		$funcio_save
		$action_submit
		$editor_height
		$editor_width
		$content_inicial
		$url_path_editor
		$abs_path_editor
		$noset
		$navegador
		$insertat_editor
		$mesg1, $mesg2, $mesg3, $mesg4, $mesg5, $mesg6, $mesg7, $mesg8, $mesg9,
		$mesg10, $mesg11, $mesg12, $mesg13, $mesg14, $mesg15, $mesg16, $mesg17,
		$mesg18, $mesg19, $mesg20, $mesg21, $mesg22, $mesg23, $mesg24, $mesg25,
		$mesg26, $mesg27, $mesg28, $mesg29, $mesg30, $mesg31, $mesg32, $mesg33,
		$mesg34, $mesg35, $mesg36, $mesg37, $mesg38, $mesg39, $mesg40, $mesg41,
		$mesg42

	-Functions:
		PropAcce_string($situ,$nomeditor,$property,$value)

* For Javascript:

	-Variables:
		obj_editor
		PropertyAccessor
		ObjTableInfo
		wol
		DECMD_BOLD		DECMD_COPY
		DECMD_CUT		DECMD_DELETE
		DECMD_DELETECELLS	DECMD_DELETECOLS
		DECMD_DELETEROWS	DECMD_FINDTEXT		
		DECMD_FONT		DECMD_GETBACKCOLOR	
		DECMD_GETBLOCKFMT	DECMD_GETBLOCKFMTNAMES
		DECMD_GETFONTNAME	DECMD_GETFONTSIZE		
		DECMD_GETFORECOLOR	DECMD_HYPERLINK		
		DECMD_IMAGE		DECMD_INDENT
		DECMD_INSERTCELL	DECMD_INSERTCOL		
		DECMD_INSERTROW		DECMD_INSERTTABLE	
		DECMD_ITALIC		DECMD_JUSTIFYCENTER
		DECMD_JUSTIFYLEFT	DECMD_JUSTIFYRIGHT
		DECMD_LOCK_ELEMENT	DECMD_MAKE_ABSOLUTE
		DECMD_MERGECELLS	DECMD_ORDERLIST
		DECMD_OUTDENT		DECMD_PASTE
		DECMD_REDO		DECMD_REMOVEFORMAT
		DECMD_SEND_BACKWARD	DECMD_BRING_FORWARD
		DECMD_SEND_BELOW_TEXT	DECMD_BRING_ABOVE_TEXT
		DECMD_SEND_TO_BACK	DECMD_BRING_TO_FRONT
		DECMD_SETBACKCOLOR	DECMD_SETBLOCKFMT
		DECMD_SETFONTNAME	DECMD_SETFONTSIZE
		DECMD_SETFORECOLOR	DECMD_SPLITCELL
		DECMD_UNDERLINE		DECMD_UNDO
		DECMD_UNLINK		DECMD_UNORDERLIST
		DECMD_PROPERTIES	OLECMDEXECOPT_DODEFAULT
		DECMDF_NOTSUPPORTED	DECMDF_DISABLED
		DECMDF_ENABLED		DECMDF_LATCHED
		DECMDF_NINCHED		DEAPPEARANCE_FLAT
		EAPPEARANCE_3D		OLE_TRISTATE_UNCHECKED
		OLE_TRISTATE_CHECKED	DECMD_SELECTALL
		OLE_TRISTATE_GRAY
		OLECMDEXECOPT_PROMPTUSER
		OLECMDEXECOPT_DONTPROMPTUSER


	-Functions:
		
		alin_dreta()
		alin_esq()
		bg_color_posa(int)
		canvi_imatge(string,string)
		centrat()
		cercar()
		combinar_celdas_table()
		contingut_html(string)
		copiar()
		cortar()
		cursiva()
		deindentat()
		desfer()
		doc_bgcolor_posa(string)
		elim_celda_table()
		elim_col_table()
		elim_fila_table()
		fer_link()
		fg_color_posa()
		Fontname_onchange()
		FontSize_onchange()
		indentat()
		ins_img()
		insert_celda_table()
		insert_col_table()
		insert_fila_table()
		insert_table(int,int,string,string,string)
		llista_no_num()
		llista_numerada()
		MakeArray(int)
		mostra_insert_table()
		mostra_pal_fg_color()
		mostra_pal_bg_color()
		mostra_pal_doc_bgcolor()
		negreta(object_textarea)
		nou_doc(object_textarea)
		paleta_colors(string)
		pegar()
		posa_contingut_html(string,string)
		refer()
		salvar_html(string)
		split_celdas_table()
		strip_body(string)
		subry()
		taula_colors()

You can't either use for any form , image, JavaScript variables and functions
any name which begins by the given name for the editor in the parameter
$nom_editor.

================================================================================

3.- Multiple wysiwyg_web_edit's in one page.

If you want to include more than one editor in the same page you just have to
write another parametrization and another include sentence 
( include " ...wysiwyg_web_edit_path/wysiwyg_web_edit.h3p" )

 The important precaution is not to repeat the value of the parameter
 $nom_editor.

 There is a sample of how to do this in the file 'Sample_multi.h3p'.

================================================================================

4.- wysiwyg_web_edit without PHP

If you don't have PHP or don't want to use it, with the application it is
included a JavaScript-HTML version. The file for english is
"ie_wysiwyg_web_edit_english.html" for Explorer and
"ns_wysiwyg_web_edit_english.html" for Netscape.

The only thing you have to do is edit the file and change the url of the images
to adapt it to your server names. (It is, change the value of the 'src'
attribute of the tags <img ..>).

If you have knowledge of HTML and JavaScript you can edit the file and just
copy&paste the code you need.

================================================================================

5.- Save function.

The generated HTML code can be accessed with two alternative ways:

a) The JavaScript function specified in the parameter $funcio_save receives the
   HTML code as a parameter. In the body of this function, which should be
   included in the page where the editor is embedded, you can send the content
   to the server. For instance, if you want to send the content to the page
   'save.h3p', the JavaScript code could be (assume you have given the parameter
   $funcio_save = 'my_save_function(code)'; ):

		function my_save_function(code){
			// Here treat the HTML code, which is in the variable 'code'
			code = escape(code)
			document.location = "save.h3p?htmlcode=" + code
			return true
		}

b) If in the parametrization you give a value for $action_submit, when the user
   click on 'Save' button the code will be directly submitted to the page whose 
   name is the value of $action_submit. This page will receive the variable 
   'editor_name_contingut_html' containing the HTML code.

 For instance:
 	$nom_editor = "my_editor";
 	$action_submit = "save.h3p";

 	Then, when clicking on 'Save' button the page 'save.h3p' will be invoked
 	and the variable '$my_editor_contingut_html' will be available for PHP in
 	'save.h3p'. Then you can put the HTML code in your database.

 	Remember also that if you want to obtain the original code, in the reception
 	page (in our case 'save.h3p') you have to do:
 		$my_editor_contingut_html = stripslashes( $my_editor_contingut_html );
 	
 	Within the files of the application there is an example of how to do this,
 	in the files 'Sample_submit.h3p' and 'Submit_reception.h3p'.

REMARK: it is important to know that due to safety reasons, from the wysiwyg_web_edit THE
CODE CAN'T BE SAVED IN THE CLIENT.

================================================================================

6.- Reception in the server of the generated code.

Either if you send the code from a JavaScript function or if you just submit it, 
it will be necessary to convert the special chars into its HTML codification. 
(For example: À->&Agrave; ).

Within the application files there is the file 'convert_html.h3p', which contains
the php function 'convert_html(string $html_code)' which returns the converted
codes.(It contains 94 special chars).

You should remember that the function 'escape(code)' does not operate rightly in
Netscape because it does not convert the '+' symbols, so in the server they will
be converted into blank spaces. Then, you should pre-convert the '+' symbols 
into a reserved code (as '´') and decode them in the server.

Remember also that if you want to obtain the original code, in the reception
page you have to do:
 		$my_editor_contingut_html = stripslashes( $my_editor_contingut_html );

================================================================================

7.- Known Bugs

The wysiwyg_web_edit presents some bugs in edition time, as some problems with the
foreground colour and colour of the text. These bugs are due to the
ActiveX control supplied by Microsoft.(Dhtmled.ocx).

If you detect any bug associated to the PHP or JavaScript code, please report it 
to gabi@unica.edu.

================================================================================