wysiwyg_web_edit 1.0 - Readme_catala.txt per l'editor wysiwyg_web_edit
desenvolupat a la Universitat Internacional de Catalunya (www.unica.edu)
(16/07/2001), a partir de les aportacions de Fernando Álvarez
(fer@onplaza.com).

El wysiwyg_web_edit és un editor WYSIWYG de códi HTML per editar i construir pàgines
HTML des d'un navegador, és a dir, a una pàgina web, sense necessitar el Composer,
el Frontpage o d'altres programes especialitzats. Permet transferir el contingut
directament al servidor mitjançant un submit o pas per URL. D'aquesta forma es 
pot fàcilment guardar les pàgines a una base de dades.

El wysiwyg_web_edit pot ser utilitzat tan amb Netscape com amb Explorer.

Es pot fer servir com a aplicació pròpiament o empotrar-lo a qualsevol pàgina web,
i és completament personalitzable per part del programador que l'inclou a una pàgina.

El editor wysiwyg_web_edit està escrit en HTML i Javascript, y fa servir PHP com a
llenguatge de servidor. (Malgrat això, existeix una versió escrita exclusivament en
JavaScript i HTML: veure capítol 6.- d'aquest document).

Soporta vàries instàncies a una mateixa pàgina. (Veure capítol '3.- Inclusió de
múltiples instàncies a una pàgina' en aquest document per a més informació).

Té funcions per construir les estructures HTML més utilitzades: taules,
links, text amb format, imatges, llistes numerades i no numerades, etc. Ara bé,
no hi ha funcions per a la utilització de frames ni formularis.

Ha estat testejat amb Netscape 4.76 i Explorer 5.0

El editor wysiwyg_web_edit es pot utilitzar en tres llengües diferents: català, 
espanyol e inglés. L'idioma es canvia fàcilment amb només variar el valor d'un
paràmetre en el moment d'empotrar l'editor.

Per dubtes i suggeriments podeu contactar amb gabi@unica.edu.

                  ÍNDEX
                  =====
	0.- Introducció

	1.- Instal·lació

	2.- Utilització modular de l'editor wysiwyg_web_edit.

	3.- Inclusió de múltiples instàncies a una pàgina.

	4.- Editor wysiwyg_web_edit sense PHP.

	5.- Funció Save.

	6.- Recepció al servidor de la pàgina escrita.

	7.- Bugs coneguts.

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

0.- Introducció

El editor wysiwyg_web_edit consisteix en un control ActiveX (Dhtmled.ocx) que ve inclòs
a la instal·lació standard de Explorer, que és comanat a Netscape a través d'un
plug-in dissenyat per executar controls ActiveX a Netscape. (Aquest 
plug-in està desenvolupat per l'empresa Esker i és de lliure distribució. Per a
més informació llegir el capítol '1.- Instal·lació' d'aquest document.)

A més, s'afegeix una botonera d'icones que, a traves de funcions Javascript
permeten controlar el que es mostra a l'objecte ActiveX (que és el quadre 
d'edició de texte), de forma que l'edició és WYSIWYG segons l'estil propi de les
eines d'ofimàtica.(Fins i tot les funcions de Tallar, Copiar i Enganxar són
OLE compatibles i per tant permeten enganxar objectes d'ofimàtica com fulles de
càlcul o documents de text amb format.)

Un cop completada l'edició del document es pot obtenir el codi font HTML
corresponent al document que s'està veient al quadre d'edició.
Això es fa mitjançant una funció Javascript que s'especifica a un dels
paràmetres que es pasan al script PHP que genera l'editor.

La pàgina de l'editor es construeix dinàmicament al servidor de forma personalitzada,
mitjançant un sistema de parametrització que es detalla a l'apartat '2.-
Utilització modular de l'editor wysiwyg_web_edit' d'aquest document. Per implementar
això s'ha utilitzat, com a llenguatge de servidor, PHP.

Un cop s'ha construit i transmés la pàgina, el client pot operar amb totes les
funcionalitats. El que es faci quan s'acabi la pàgina i es clicki a sobre de 
l'icona 'Guardar' depen de la funció '$funcio_save' que es passa com a
paràmetre, o bé de la pàgina $action_submit que s'especifiqui com a paràmetre.

Per exemple, es pot passar (per submit o a la URL) el codi generat a una página
del servidor i així enregistrar-lo a una base de dades. D'aquesta forma l'editor
wysiwyg_web_edit constitueix una potent eina per gestionar un lloc web mitjançant una
base de dades.

Les funcionalitats que inclou l'editor wysiwyg_web_edit son:

	1.- Nou document.

	2.- Guardar (a través d'una funció JavaScript definida pel programador
	    o per submit del contingut a una base de dades).

	3.- Tallar, Copiar, Enganxar: Ole compatibles, és a dir, permet enganxar 
	    objectes d'ofimàtica com fulles de càlcul o documents de text amb 
	    format.

	4.- Desfer i Refer: permet desfer (i tornar a fer) totes les
	    accions des de l'inici de l'edició.

	5.- Cercar: permet cercar cadenes de caracters al document.

	6.- Generació de Links.

	7.- Inserció d'imatges.

	8.- Color de fons del document.

	9.- Inserció de taules.

	10.- Funcions per gestió de taules: afegir fila o columna, suprimir fila
	     o columna, afegir i suprimir cel·les, combinar i dividir cel·les.

	11.- Formateig de text: tipus i tamany de lletra, color del text i color de
	     fons del text, negreta, cursiva, subratllat.

	12.- Alineació de paràgraf: dreta, esquerra i centrat.

	13.- Generació de llistes numerades i no numerades.

	14.- Indentat i deindentat de paràgrafs.

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

1.- Instal·lació

Per utilitzar el wysiwyg_web_edit cal instal·lar certs components al servidor i certs 
components a cadascun dels clients en els que es farà servir.

INSTAL·LACIÓ AL CLIENT

INSTAL·LACIÓ PER UN CLIENT NETSCAPE:

Per funcionar sobre Netscape, el editor wysiwyg_web_edit requereix la instal·lació en
el client de varios elements:

A) Plug-in de l'empresa Esker per executar controls ActiveX a Netscape. És
   de lliure distribució i existeixen programes d'instal·lació automàtica a la
   següent mailing list de Yahoo:

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

	Cal registrar-se al grup per accedir a la descàrrega del plug-in. Això es
	gratuït i gens problemàtic.

	Un cop enregistrat s'accedeix a la instal·lació a la següent pàgina de la
	llista:
	
	Files/Versions/Esker ActiveX Plug-in 4.5/demo/npeskp32/install.htm

	Per Netscape 6.0 cal descarregar la versió 6.0 del Plug-in.

	El plug-in s'instal·la automàticament sempre i quan es tingui el
	SmartUpdate de Netscape habilitat.

	(De fet, per instal·lar el plug-in n'hi ha prou de copiar l'arxiu
	NPESKP32.dll al directori de plug-ins de Netscape).

B) Cal instal·lar el control ActiveX PropertyAccessor que es troba a la
   mateixa mailing list a:

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

	Cal registrar-se al grup per accedir a la descàrrega del plug-in. Això es
	gratuït i gens problemàtic.

	Un cop enregistrat s'accedeix al arxiu accessor.ocx a la següent ruta:
	
	Files/Miscellaneous/Properry Accessor/accessor/accessor.ocx

	Cal copiar-lo a qualsevol directori del disc dur local (per exemple a 
	c:\my_path\) i després executar en linia de comandes (Inicio -> Ejecutar ):

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

C) Cal instal·lar el control ActiveX Dhtmled.ocx. N'hi ha prou amb instal·lar
Explorer per a que això es faci. Si no es vol instal·lar Explorer cal copiar els
arxius Dhtmled.ocx i TRIEDIT.dll (que es troben aqualsevol client amb Explorer 
instal·lat ) a la carpeta (si no existeix cal crear-la):
'Archivos de Programa / Archivos comunes / Microsoft Shared / TRIEDIT'.

INSTAL·LACIÓ PER UN CLIENT EXPLORER:

No cal cap instal·lació especial per Explorer, perquè el control
ActiveX Dhtmled.ocx ve per defecte amb la instal·lació de Explorer 5.0 o
superior.

Si no funciona sobre explorer cal copiar els arxiu Dhtmled.ocx i TRIEDIT.dll
(que es troba a qualsevol client amb instal·lació standard de Explorer 5.0 o
superior) al directori:
'Archivos de Programa / Archivos comunes / Microsoft Shared / TRIEDIT'.

INSTAL·LACIÓ AL SERVIDOR

   Un cop instal·lats els dos components anteriors cal copiar tots els arxius
   continguts a wysiwyg_web_edit.tar.gz en un directori (lo cual conservarà 
   l'estructura definida, amb tots els arxius *.gif en el subdirectori
   'images').

   Aleshores cal editar l'arxiu "wysiwyg_web_edit.h3p". Cal donar valor a dos
   paràmetres:

    $url_path_editor = "http://my_server/my_applications/wysiwyg_web_edit/"; // URL del
	directori de l'aplicación 

	$abs_path_editor = "/absolute_path/wysiwyg_web_edit/"; // Path absolut 
	(pel servidor de pàgines web), de l'editor wysiwyg_web_edit al servidor 
	en el que s'ha instal·lat l'aplicación. Això es per a que es puguin fer els
	'include' corresponents independentment del document en el que s'empotri el
	editor wysiwyg_web_edit.

A més es requereix com a mínim PHP 3.0 al servidor. Si no es té PHP es pot tenir 
una versió no configurable del editor. Veure l'apartat '4.- Editor
wysiwyg_web_edit sense PHP' d'aquest mateix document.

NOTA: tots els arxius PHP de l'aplicació tenen l'extensió 'h3p' perquè 
aquesta és l'extensió que el nostre servidor Apache fa servir per reconèixer
quins arxius han de ser parsejats per PHP. Si s'utiliza 'php3' o qualsevol altre
cal fer el següent:

a) Canviar les extensions de tots els arxius '*.h3p' i posar la nova
extensió (per exemple '*.php3').

b) Reemplaçar la cadena '.h3p' per la que correspongui a la teva extensió (por
exemple '.php3') a tots els arxius '*.h3p'.

O bé, i poder més simple, configurar el servidor de págines web per a que 
reconegui '.h3p' com a extensió associada a PHP.

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

2.- Utilització modular de l'editor wysiwyg_web_edit

Per poder utilitzar el editor wysiwyg_web_edit com un mòdul empotrat en un 
document qualsevol cal fer el següent:

A) Al document PHP posar les línies de parametrització. La llista de
paràmetres i el significat dels seus valors és el següent (es mostra un
exemple, amb els valors per defecte pels paràmetres):

	$nom_editor = "Ed1"; // Nom que prendrà l'objecte editor a la pàgina.
	Ha de ser diferent de tots els objectes JavaScript a la mateixa pàgina. Si
	s'inclou més d'una instància de l'editor a una mateixa pàgina, cadascun dels
	noms ha de ser diferent.

	$idi_edit = 'eng'; // Idioma d'utilització: 'eng' -> anglès, 'esp' ->
	espanyol, 'cat' -> català.

	$document_complet = 1; // Si val 1 se està editant un document complet,
	i per tant, el codi HTMl que rebrà la funció save o que s'enviarà
	per submit serà amb tags <body> ... </body>. Si val 0, se està editant
	una part d'un document i per tant el codi HTMl serà sense <body> ...
	</body>.

	$funcio_save= 'my_save_function(codigo);'; // Nom de la funció
	Javascript que es cridarà al fer click sobre l'icona de guardar. Sempre
	ha de tenir un paràmetre, que rebrà el codi generat. Des d'aquesta funció,
	que ha de suministrar el programador, es pot enviar el contingut a
	alguna url, etc. Si no es vool donar una funció JavaScrip es pot fer servir
	el següent paràmetre.

	$action_submit = "sample_submit.h3p"; // Url de l'arxiu al que s'enviarà 
	per submit el codi HTML generat. Aquesta opció s'utilitza si no s'ha
	definit el paràmetre $funcio_save.

	$editor_width = 700; // Amplada (en pixels) del quadre d'edició de l'editor.

	$editor_height= 400; // Alçada (en pixels) del quadre d'edició de l'editor.
	
	$content_inicial = "Hello World"; // Contingut inicial a carregar al quadre
	d'edició. Ha de ser codi HTML, i sense salts de linia (cal que estiguin com
	a <br>).

B) Aleshores, un cop escrita la parametrització es farà:

	include " ...path_del_editor/wysiwyg_web_edit.h3p"; 

AMB ELS ARXIUS DE L'APLICACIÓ S'INCLOU UN EXEMPLE EN EL QUE ES POT VEURE LA 
PARAMETRITZACIÓ. ÉS A 'Sample.h3p'.

OBSERVACIONS
============

Cal saber que al document on s'empotri l'editor no pot fer servir els següents
noms de variables i funcion:

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

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

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


	-Funciones:
		
		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()

Tampoc es pot fer servir per elements de formulari, imatges, variables i
funcions JavaScript, noms que comencin pel nom donat a l'editor en el paràmetre
$nom_editor.

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

3.- Inclusió de múltiples instàncies a una pàgina.

Per incloure multiples instàncies del wysiwyg_web_edit en una mateixa pàgina n'hi ha
prou amb repetir la parametritzación i la sentència 
		include " ...path_del_editor/wysiwyg_web_edit.h3p".
 Lo important és assignar un valor diferent cada cop al paràmetre $nom_editor.

 Hi ha un arxiu-exemple a 'Sample_multi.h3p'.

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

4.- Editor wysiwyg_web_edit sense PHP

Si no es te PHP o no es vol utilitzar, amb l'aplicació s'inclou una versió en
català del editor escrita exclusivament en HTML i Javascript. L'arxiu per
explorer és "ie_wysiwyg_web_edit_catala.html" i per netscape és
"ns_wysiwyg_web_edit_catala.html".

Si es tenen coneixements de HTML i JavaScript es pot editar aquest arxiu 
per seleccionar només la part que convingui (entre <body bgcolor=beige > i
</body>) per enganxar-la en qualsevol altre document.

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

5.- Funció Save.

El codi HTML generat es pot accedir de dues maneres:

a) La funció JavaScript especificada al paràmetre $funcio_save rep com
 a paràmetre el codi HTML generat. Al cos d'aquesta funció, que ha de ser inclòs
 a la pàgina pel programador que empotra el wysiwyg_web_edit, es pòt enviar el
 contingut al servidor. Per exemple, si es vol enviar el contingut a la pàgina
 'save.h3p', el codi podria ser: (suposem que a la parametrització hem
 especificat $funcio_save = 'my_save_function(code)'; ):

		function my_save_function(code){
			// Aquí es pot tractar el codi, que está a la variable code
			code = escape(code)
			document.location = "save.h3p?htmlcode=" + code
			return true
		}

b) Si a la parametrització s'especifica algun valor per $action_submit, al
fer click sobre la icona de guardar s'enviarà el codi generat a la pàgina
que es crida com $action_submit. El contingut es rep a la variable
'nombre_editor_contingut_html'.

 Per exemple:
 	$nom_editor = "my_editor";
 	$action_submit = "save.h3p";

 	Aleshores, al fer click a 'guardar' es cridarà a la página 'save.h3p' i se
 	li enviarà la variable de nom 'my_editor_contingut_html'.

 	Així, a la pàgina 'save.h3p' es pot accedir una base de dades i guardar el
 	codi html.

 	Cal recordar que si es vol tenir el codi original, a la pàgina de recepció
 	(al nostre cas 'save.h3p') cal fer:
 		$my_editor_contingut_html = stripslashes( $my_editor_contingut_html );

 	Amb els fitxers de l'aplicació es suministra un exemple d'això, als arxius
 	'Sample_submit.h3p' i 'Submit_reception.h3p'.

NOTA: és important saber que per raons de seguretat, des de el wysiwyg_web_edit NO ES
POT GUARDAR EN EL CLIENTE la pàgina generada.

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

6.- Recepció al servidor de la pàgina escrita.

Si s'envia el codi generat a una pàgina del servidor, serà necessari aplicar
alguna funció per passar els caracters especials a la seva codificació HTML.
(Exemple: À->&Agrave; ).

Amb els arxius de l'aplicació es facilita la funció (en php)
convert_html($string); a l'arxiu 'convert_html.h3p', que realitza aquesta
conversió. (Conté 94 caracters especials).

Cal no oblidar que la funció 'escape(code)' de Netscape no va bé, perquè els
signes '+' (al aplicar la decodificació) quedan convertits en espais en
blanc. Cal, aleshores, abans d'aplicar-la, convertir els '+' a algun
caracter reservat (p.e. '´') i realitzar la descodificació inversa al rebre
el valor.

Cal recordar que si es vol tenir el codi original, a la pàgina de recepció
cal fer:
 	$my_editor_contingut_html = stripslashes( $my_editor_contingut_html );


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

7.- Bugs coneguts

El wysiwyg_web_edit presenta alguns bugs en temps d'edició, com per exemple la
pèrdua del color de fons del text al canviar el color dels caracters del
text. Aquests bugs són propis del control ActiveX suministrat per Microsoft
(Dhtmled.ocx).

Si es detecten bugs associats al codi PHP, JavaScript o HTML es poden reportar a
gabi@unica.edu.

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