php-js-webedit 1.0 - Readme_catala.txt per l'editor php-js-webedit desenvolupat a la 
Universitat Internacional de Catalunya (www.unica.edu) (30/11/2000).

L'editor php-js-webedit és una eina per a editar i construir pàgines HTML (relativament 
complexes) des d'un navegador, sense necessitar el Composer, el Frontpage o 
altres programes especialitzats. Permet transferir el contingut directament 
al servidor mitjançant un submit o pas per URL. D'aquesta forma es pot guardar 
fàcilment les pàgines a una base de dades.

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

L'editor php-js-webedit està escrit en HTML i Javascript, i fa servir com llenguatge de 
servidor el PHP.( Tot i que hi ha una versió en Javascript i HTML exclusivament. 
Veure el capítol 6.- d'aquest document per a més informació).

Suporta edició simultània en varis texareas. (Veure el capítol 4.- d'aquest 
document per a més informació).

Té assistents per construir les estructures HTML més utilitzades: taules, links, 
anchors, text amb format, estils, imatges, llistes numerades y no numerades, etc.
No hi ha assistent per a l'utilització de frames ni formularis, pel que cal
crear-los manualment.

Ha estat provat a Netscape 4.05 i superiors, i Explorer 5.0

L'editor php-js-webedit es pot utilitzar en tres llengües diferents: català, espanyol i 
anglès.

Per a dubtes i suggerències podeu contactar amb gabi@unica.edu.

                    INDEX
                    =====
	0.- Introducció

	1.- Instal·lació

	2.- Utilització modular de l'editor php-js-webedit.

	3.- Utilització sense botonera.

	4.- Utilització amb multi-textarea.

	5.- Utilització tot sencer a una página.

	6.- Editor php-js-webedit sense PHP.

	7.- Estructura del mòdul.

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

	9.- Funció Save.

	10.- Bugs coneguts

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

0.- Introducció

L'editor php-js-webedit consisteix en una pàgina HTML que inclou una serie de botons i 
funcions Javascript que actuen sobre un textarea per ajudar a construir un document
HTML de forma senzilla. D'aquesta forma es genera el codi font HTML al textarea, 
assistit per les funcions Javascript. En tot moment es pot fer una vista 
preliminar de la pàgina per anar veient com va quedant.

La pàgina de l'editor es construeix dinàmicament al servidor de forma personalitzada,
fent servir un sistema de parametrització que es detalla a l'apartat 1.- d'aquest
document. Per a implementar això s'ha fet servir, 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 de fer servir l'editor i es premi el 
botó de 'Guardar' depén de la funció 'funcio_save' que es passi com a paràmetre.
Per exemple, es pot transmetre la informació al servidor i emmagatzemar el contingut
a una base de dades. Això fa que el php-js-webedit constitueixi una eina molt 
potent per a ser integrada a d'altres aplicacions com per exemple assistents
per a la construcció de llocs web, taulons d'anuncis, etc.

Les funcionalitats que inclou l'editor php-js-webedit són:

	1.- Vista preliminar.

	2.- Generació de Anchors al document.

	3.- Generació de Links.

	4.- Generació de taules.

	5.- Inserció d'imatges al document.

	6.- Canvi del títol de document.

	7.- Canvi del color de fons del document.

	8.- Consulta d'una paleta bàsica de colors.

	9.- Nou document (en blanc).

	10.- Utilització i gestió d'estils (estils amb canvi de font, tamany, color 
	    de la font, negreta, cursiva i subratllat).

	11.- Salt de línia.

	12.- Inserció d'un espai en blanc.

	13.- Text en negreta.

	14.- Text amb format: font, tamany, color, negreta, cursiva, subratllat.

	15.- Text en cursiva.

	16.- Text subratllat.

	17.- Línia horitzontal.

	18.- Alineació a l'esquerra.

	19.- Alineació centrada.

	20.- Alineació a la dreta.

	21.- Generació de llistes numerades.

	22.- Generació de llistes no numerades.

	23.- Indentat de paràgraf.

	24.- Dos modes d'assistència a l'usuari: guiat i directe.

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

1.- Instal·lació

L'editor php-js-webedit no requereix cap instal·lació especial, n'hi ha prou amb copiar 
tots els arxius de l'aplicació a un directori i editar el fitxer 
"paths_absoluts.h3p" per configurar els paths. Cal donar valor a dos paràmetres:

	$path_editor='/path_absolut_del_editor/php-js-webedit/'; // Path absolut (per
	al servidor de págines web) de l'editor php-js-webedit en el servidor en el 
	que es troba la aplicació. Això és per a que es pugui fer els includes 
	corresponents sense dependre de que l'editor estigui empotrat a un document 
	a un altre.

	$path_icons='http://servidor/path_del_editor/php-js-webedit/'; // URL del 
	directori de icones de l'editor php-js-webedit (normalment el mateix que per 
	a la aplicació)

Després cal editar l'arxiu "php-js-webedit.h3p" i assegurar-se que a la primera línia 
es fa un include de l'arxiu "paths_absoluts.h3p" AMB EL PATH ADEQUAT. Per exemple:

    include "/path_absolut_del_editor/php-js-webedit/paths_absoluts.h3p";

A més cal com mínim PHP 3.0 al servidor. Si no es té PHP es pot tenir una versió
no configurable de l'editor. Veure l'apartat "6.- Editor php-js-webedit sense PHP"
d'aquest document.

NOTA: todos los ficheros PHP de la aplicación tienen la extensión 'h3p' porque 
esa es la extensión que nuestro servidor Apache utiliza para reconocer qué archivos
deben ser parseados por PHP. Si se utiliza 'php3' o cualquier otra se debe hacer lo
siguiente:

a) Cambiar las extensiones de todos los archivos '*.h3p' y poner la nueva extensiòn 
(como por ejemplo '*.php3').

b) Reemplazar la cadena '.h3p' por la que corresponda a tu extensión (por ejemplo
 '.php3') en todos los archivos '*.h3p'.

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

2.- UTILITZACIÓ MODULAR DE L'EDITOR php-js-webedit:

Per a poder fer servir l'editor php-js-webedit 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 del seus valors és el següent (es mostra un exemple, amb els valors
per defecte del paràmetres):

$idi_edit='cat'; // Defineix l'idioma en que s'utilitzarà: 'cat' per català, 
'esp' per espanyol, 'eng' per anglès.

$document_complet=1; // Si es posa 1 es considerarà que s'edita un document 
complet i hi haurà capçalera, i gestió d'estils, de color de fons i de títol de 
document (aquestes funcionalitats només s'inclouran si així s'indica al paràmetre
corresponent, però no es podran incloure si no es tracta d'un docuemnt complet). 
Si està a 0 es tracta d'una part d'un document HTML i per tant no s'inclourà 
gestió d'estils, ni de color de fons, ni de títol de finestra, i tampoc es posarà
capçalera al document. 

$contingut_inicial=''; // Contingut inicial a carregar al textarea. Això és molt 
útil per a editar documents creats anteriorment.

$posar_form=1; // Si és 1 s'englobarà l'editor (botonera i textarea a dins d'una
form). Si no, no es posarà la form i es suposa que el programa en el que s'empotra
l'editor genera la form corresponent.

$nom_form='doc_html'; // És el nom que tindrà la form. Encara que la form es posi
manualment a la pàgina en la que s'empotra l'editor, cal donar aquest paràmetre.

$posar_textarea=1; // Si és 1 es posarà textarea en el que editar. Si és 0 no es 
posarà i es suposarà que el posarà el programador que utilitza el mòdul editor. 
Si el textarea es posat pel programador, cal que després de incloure'l posi una 
sentencia com la següent: 
<script> 
     obj_txt = document.nom_form.nom_textarea ; 
</script> . 
Si es fa servir multitextarea no es necessari, però aleshores cal fer la gestió 
de referencias al textarea en que s'edita. Per a més informació vegeu el capítol 
de 'multitextarea' en aquest mateix document.

$nom_textarea='text'; // És el nom del textarea en el que s'edita. Si es posa 
botonera cal donar-lo encara que el textarea es generi a l'arxiu en el que 
s'empotra l'editor. Si es fa servir multitextarea no cal, però aleshores cal fer 
la gestió de referències al textarea que s'edita. Per a més informació veure el 
capítol de 'multitextarea' en aquest mateix document.

$botonera=1; // Si està a 1 s'inclourà la botonera de funcions predeterminades. 
Ara bé només s'inclouran els botons especificats a la parametrització que segueix. 
Si està a 0 no s'inclourà botonera (es suposa la fa el programador) i només 
s'inclourà les funcions Javascript indicades a la parametrització que segueix.

// De les funcionalitats disponibles, només s'inclourà les que es posi 1. La 
llista és la següent:

$gestio_modes=1; // Funcionalitat de modalitat doble: directe o guiada. Si es 
posa 0, no s'inclourà el desplegable per a escollir el mode, i es prendrà la 
modalitat guiada per defecte.

$save=1; // Funcionalitat de guardat de document.

$funcio_save='salvar_documento(obj_textarea);'; // És la funció Javascript que 
cal cridar per salvar el document. Aquesta funció ha d'estar programada pel 
programador de l'arxiu en el que s'empotra l'editor.

$preview=1; // Vista preliminar.

$anchor=1; // Anchor al mateix document.

$link=1; // Link (al document o universal).

$taula=1; // Generació de taules HTML.

$imatge=1; // Inclusió d'imatges al document.

$titol=1; // Titol del document.

$bgcolor=1; // Color de fons del document.

$new_doc=1; // Resetejat del document, document en blanc.

$paleta=1; // Utilitat de consulta dels colors i el seu nom.

$rang_paleta='baix'; // Si es posa 'alt' es tindrá una paleta de 119 colors, i 
si es posa altre cosa, de 42 colors.

$gestio_estils=1; // Gestió d'estils.

$breakline=1; // Nova línia.

$nbsp=1; // Espai en blanc.

$tipus_font=1; // Text amb format: font, tamany, color, negreta, cursiva, subratllat.

$negreta=1; // Negreta al text.

$cursiva=1; // Cursiva al text.

$subry=1; // Subratllat al text.

$lin_horiz=1; // Generació de línia horitzontal de separació

$alin_esq=1; // Alineació del text a l'esquerra.

$centrat=1; // Centrat del text.

$alin_dreta=1; // Alineació del text a la dreta.

$llista_numerada=1; // Funcionalitat de generació de llista numerada.

$llista_no_num=1; // Funcionalitat de generació de llista no numerada (discs o 
cercles).

$indentat=1; // Indentat del text.

Cal saber a més que en el document en el que s'empotri l'editor no es poden fer 
servir els següents noms de variables Javascript:

	jAlin_L        jItalics            nr
	jAlin_R        jLI                 ob_est
	jAnchor        jLink               obj_txt       
	jBFont         jOL                 pal_col
	jbnsp          jSubry              retorn_escriu_tag
	jBold          jTable              s1            
	jBreak         jTH                 s2            
	jCenter        jTipus_font         s3            
	jEstil         jTR                 t1            
	jHR            jUFont              t2
	jIFont         jUL                 t3            
	jIMG           mode                taula_colors  
	jIndent        msg                 

// No es poden incloure en el mateix document les següents funcions Javascript:

	alin_dreta(object_textarea)
	alin_esq(object_textarea)
	anchor(object_textarea)
	bgcolor(object_textarea)
	bgcolor(object_textarea)
	bgcolor_posa(int)
	breakline(object_textarea)
	canvi_mode(int)
	canvi_mode(object_select)
	centrat(object_textarea)
	col_est(string)
	cursiva(object_textarea)
	def_estils()
	escriu_tag(object_textarea,object_tag,int)
	estil_var( ... consulta gestio_estils.h3p ... )
	gestio_estils(object_textarea)
	HTMLtag( ... consulta tag.h3p ...)
	imatge(object_textarea)
	indentat(object_textarea)
	inici(int)
	lin_horiz(object_textarea)
	link(object_textarea)
	llista_no_num(object_textarea)
	llista_numerada(object_textarea)
	MakeArray(int)
	nada()
	nbsp(object_textarea)
	negreta(object_textarea)
	nested(object_textarea)
	new_doc(object_textarea)
	paleta(object_textarea)
	paleta_colors(string)
	posa_estil(object_textarea)
	posa_estils()
	preview(object_textarea)
	save(object_textarea)
	spot_from_inici(string,string,int)
	subry(object_textarea)
	taula(object_textarea)
	taula_colors()
	tipus_font(object_textarea)
	titol(object_textarea)

b) Aleshores, un cop posada la parametrització caldrà fer:

	include " ...path_del_editor/php-js-webedit.h3p"; 

Es molt important saber:

* La variable obj_txt ha de contenir una referencia a l'objecte 'textarea' en el 
que es vol insertar els tags.

* La variable ob_est conté una referencia a l'objecte select dels estils.

Aleshores, si s'ha inclòs la botonera només caldrà definir la $funcio_save a 
executar quan es premi el botó.

AMB ELS ARXIUS DE LA APLICACIÓ ES TÉ UN EXEMPLE DE PARAMETRITZACIÓ. ES TROBA 
A 'php_param_example.h3p'.

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

3.- Utilització sense botonera.

Si no s'ha inclos botonera es pot fer servir les funcionalitats seleccionades 
cridant les funcions Javascript corresponents.

Aquestes funcions tenen el mateix nom que el paràmetre de configuració. A més, 
a totes cal passar una referència a l'objecte textarea en el que es vol posar 
els tags.

Exemple: $negreta=1;   =>   negreta(object_textarea)

Per gestionar la referencia a l'objecte textarea es pot simplement fer:

<script>
	obj_txt = document.nom_form.nom_textarea ;
</script>
...
Aleshores es crida la funció:  negreta(obj_txt)

Per gestionar els modes es té la funció canvi_mode(object_select), que posa com 
a mode el seleccionat al object_select. Si es vol fer-ho sense select es pot 
parametritzar amb $gestio_modes=0; i aleshores cridar la funció canvi_mode(int a),
on 'a' és el nou valor a posar com a mode. Recordem que '0' és mode directe i '1'
és guiat.

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

4.- Utilització amb multi-textarea.

Per fer servir l'editor amb molts textareas només cal posar 
ONFOCUS="obj_txt=this;" a la definició del textarea:

<TEXTAREA NAME="nom_textarea" ONFOCUS="obj_txt=this;" ROWS="20" COLS="90" WRAP="SOFT" >

A més per inicialitzar amb capaçalera un textarea cal:

* Posar a obj_txt la referencia al textarea:

<script>
	obj_txt = document.nom_form.nom_textarea ;
</script>

* Després cal cridar la funció inici(int) i passar com a paràmetre: 1 si has 
posat contingut abans de cridar a inici, i 0 en cas contrari.

<script>
	inici(0)
</script>

AMB ELS ARXIUS DE LA APLICACIÓ ES TROBA UN EXEMPLE DE MULTI-TEXTAREA, A L'ARXIU 
'multi_textarea_example.h3p'.

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

5.- Utilització tot sencer a una página.

Per a fer servir l'editor sense empotrar-lo en un document, cal simplement cridar-lo
i passar com a paràmetre $no_empotrat=1;

Caldrà passar també el paràmetre $funcio_save='nom_funcio( ... );'

Aleshores, s'invocarà la URL completa:

		URL_directori_editor/php-js-webedit.h3p?no_empotrat=1&funcio_save=nom_funcio
		( ...parámetros_función_save... )

Si no es passa el paràmetre funcio_save simplement no es tindrà funció de guardat 
del document.

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

6.- Editor php-js-webedit sense PHP

Si no es compta amb PHP o no es vol fer servir, amb l'aplicació s'inclou una versió
exclusivament amb HTML i Javascript. L'arxiu en català és "php-js-webedit_catala.html".

La única cosa que cal fer és editar l'arxiu per a posar bé la URL dels icons de 
l'aplicació.(És a dir canviar el valor de l'atribut src dels tags <img ..> ).

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

7.- Estructura del mòdul.

De forma sintètica, el mòdul està programat amb la següent estructura:

* Es defineix els objectes HTMLtag (pels tags), i estil_var (pels estils). Per 
més detalls veure els arxius tag.h3p i gestio_estils.h3p

* La funció escriu_tag(object_textarea,object_tag,int) es la que es crida 
recursivament per escriure els tags anidats, amb atributs, etc.

* Hi ha tants fitxers *.h3p com funcionalitats, i tenen el matiex nom que el 
paràmetre de configuració.

	Per exemple: $negreta => negreta.h3p

En aquest fitxers es troben les funcions Javacript però també tots els missatges 
(en les 3 llengües, català, espanyol i anglès). Així que per corregir o canviar 
missatges cal fer-ho en aquests fitxers.

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

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

En la $funcio_save especificada es pot fer el que es vulgui amb el contingut del 
textarea.

Si s'envia a una pàgina del servidor caldrà aplicar alguna funció per passar els 
caràcters amb accents, com À a &Agrave;.

Hi ha disponible la funció (en php) convert_html($string); a l'arxiu 'convert_html.h3p'.
(Conté 94 caràcters especials).

Cal recordar que la funció escape de Netscape no va bé, perquè els signes '+' 
(en aplicar la decodificació) queden convertits en espais en blanc. Cal doncs, 
abans d'aplicar-la, convertir els '+' a algun caràcter reservat (p.e. '´').

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

9.- Funció Save.

La funció a executar en prémer el botó save, queda definida al paràmetre $funcio_save.

Per exemple:

$funcio_save='la_teva_funcio(obj_txt);';

Ara bé, quan es faci servir directament les funcions Javascript es bo no cridar 
directament la_teva_funcio(obj_txt) sino a través de save(obj_txt). Això és perquè
a dins de save(obj_txt) es posen els tags </BODY></HTML> si és necessari.

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

10.- Bugs coneguts

L'únic bug conegut del editor php-js-webedit és el següent:

a)	Els links a anchors de la pròpia pàgina no funcionen bé del tot en la 
previsualització. Això es degut a que el navegador no es comporta segons lo 
esperat si es posa el contingut d'un document amb Javascript mitjançant la funció 
document.write(string). 

	El problema està gairebé resolt per Netscape, només falla si es fa la 
	previsualització mentre es té obertes altres finestres des del mateix document. 
	A Explorer simplement els links a anchors al mateix document no funcionaran a
	la previsualització.

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