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 pgines HTML (relativament 
complexes) des d'un navegador, sense necessitar el Composer, el Frontpage o 
altres programes especialitzats. Permet transferir el contingut directament 
al servidor mitjanant un submit o pas per URL. D'aquesta forma es pot guardar 
fcilment les pgines a una base de dades.

Es pot fer servir com una aplicaci prpiament o b empotrat a qualsevol pgina
web, i s completament personalitzable per part del programador que l'inclou a 
una pgina web prpia.

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 captol 6.- d'aquest document per a ms informaci).

Suporta edici simultnia en varis texareas. (Veure el captol 4.- d'aquest 
document per a ms informaci).

T assistents per construir les estructures HTML ms 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 llenges diferents: catal, espanyol i 
angls.

Per a dubtes i suggerncies podeu contactar amb gabi@unica.edu.

                    INDEX
                    =====
	0.- Introducci

	1.- Installaci

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

	3.- Utilitzaci sense botonera.

	4.- Utilitzaci amb multi-textarea.

	5.- Utilitzaci tot sencer a una pgina.

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

	7.- Estructura del mdul.

	8.- Recepci al servidor de la pgina escrita.

	9.- Funci Save.

	10.- Bugs coneguts

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

0.- Introducci

L'editor php-js-webedit consisteix en una pgina 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 pgina per anar veient com va quedant.

La pgina de l'editor es construeix dinmicament 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 transms la pgina, 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' depn de la funci 'funcio_save' que es passi com a parmetre.
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 sn:

	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 ttol de document.

	7.- Canvi del color de fons del document.

	8.- Consulta d'una paleta bsica 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 lnia.

	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.- Lnia 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 pargraf.

	24.- Dos modes d'assistncia a l'usuari: guiat i directe.

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

1.- Installaci

L'editor php-js-webedit no requereix cap installaci 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 parmetres:

	$path_editor='/path_absolut_del_editor/php-js-webedit/'; // Path absolut (per
	al servidor de pgines 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)

Desprs cal editar l'arxiu "php-js-webedit.h3p" i assegurar-se que a la primera lnia 
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 ms cal com mnim 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 aplicacin tienen la extensin 'h3p' porque 
esa es la extensin 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 extensin 
(como por ejemplo '*.php3').

b) Reemplazar la cadena '.h3p' por la que corresponda a tu extensin (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 mdul empotrat en un document 
qualsevol cal fer el segent:

a) Al document PHP posar les lnies de parametritzaci. La llista de parmetres 
i el significat del seus valors s el segent (es mostra un exemple, amb els valors
per defecte del parmetres):

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

$document_complet=1; // Si es posa 1 es considerar que s'edita un document 
complet i hi haur capalera, i gesti d'estils, de color de fons i de ttol de 
document (aquestes funcionalitats noms s'inclouran si aix s'indica al parmetre
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 ttol de finestra, i tampoc es posar
capalera 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 pgina en la que s'empotra l'editor, cal donar aquest parmetre.

$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 mdul editor. 
Si el textarea es posat pel programador, cal que desprs de incloure'l posi una 
sentencia com la segent: 
<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 ms informaci vegeu el captol 
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 referncies al textarea que s'edita. Per a ms informaci veure el 
captol de 'multitextarea' en aquest mateix document.

$botonera=1; // Si est a 1 s'inclour la botonera de funcions predeterminades. 
Ara b noms 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 noms 
s'inclour les funcions Javascript indicades a la parametritzaci que segueix.

// De les funcionalitats disponibles, noms s'inclour les que es posi 1. La 
llista s la segent:

$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 lnia.

$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 lnia 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 ms que en el document en el que s'empotri l'editor no es poden fer 
servir els segents 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 segents 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 incls la botonera noms 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 parmetre de configuraci. A ms, 
a totes cal passar una referncia 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 noms 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 ms per inicialitzar amb capaalera un textarea cal:

* Posar a obj_txt la referencia al textarea:

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

* Desprs cal cridar la funci inici(int) i passar com a parmetre: 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 pgina.

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

Caldr passar tamb el parmetre $funcio_save='nom_funcio( ... );'

Aleshores, s'invocar la URL completa:

		URL_directori_editor/php-js-webedit.h3p?no_empotrat=1&funcio_save=nom_funcio
		( ...parmetros_funcin_save... )

Si no es passa el parmetre 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 mdul.

De forma sinttica, el mdul est programat amb la segent estructura:

* Es defineix els objectes HTMLtag (pels tags), i estil_var (pels estils). Per 
ms 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 
parmetre de configuraci.

	Per exemple: $negreta => negreta.h3p

En aquest fitxers es troben les funcions Javacript per tamb tots els missatges 
(en les 3 llenges, catal, espanyol i angls). Aix que per corregir o canviar 
missatges cal fer-ho en aquests fitxers.

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

8.- Recepci al servidor de la pgina escrita.

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

Si s'envia a una pgina del servidor caldr aplicar alguna funci per passar els 
carcters amb accents, com  a &Agrave;.

Hi ha disponible la funci (en php) convert_html($string); a l'arxiu 'convert_html.h3p'.
(Cont 94 carcters 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 carcter reservat (p.e. '').

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

9.- Funci Save.

La funci a executar en prmer el bot save, queda definida al parmetre $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 travs 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 segent:

a)	Els links a anchors de la prpia pgina 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 mitjanant la funci 
document.write(string). 

	El problema est gaireb resolt per Netscape, noms 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.

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