php-js-webedit 1.0 - Readme_spanish.txt para el editor php-js-webedit 
desarrollado en la Universidad Internacional de Catalunya (www.unica.edu)
(30/11/2000).

El editor php-js-webedit es una herramienta para editar y construir pginas HTML 
(relativamente complejas) desde un navegador, sin necesitar el Composer, el 
Frontpage o otros programas especializados. Permite transferir el contenido 
directamente al servidor mediante un submit o paso por URL. De esta forma se 
puede fcilmente guardar las pginas en una base de datos.

Se puede usar como aplicacin propiamente o empotrarlo en cuaqluier pgina web,
y es completamente personalizable por parte del programador que lo incluye en 
una pgina.

El editor php-js-webedit est escrito en HTML y Javascript, y utiliza como
lenguaje de servidor el PHP. (Aunque existe una versin escrita exclusivamente 
en JavaScript y HTML: ver captulo 6.- de este document).

Soporta edicin simultnea en varios textareas. (Ver captulo 4.- en este documento
para ms informacin).

Tiene asistentes para construir las estrucutras HTML ms utilizadas: tablas, links, 
anchors, texto con formato, estilos, imgenes, listas numeradas y no numeradas, etc.
No hay asistente para la utilizacin de frames ni formularios, por lo que se deben
crear manualmente.

Ha sido probado en Netscape 4.05 y superiores, y Explorer 5.0

El editor php-js-webedit se puede utilizar en tres lenguas diferentes: cataln, 
espaol e ingls. El idioma se cambia fcilmente con slo cambiar un parmetro.

Para dudas y sugerencias podis contactar con gabi@unica.edu.

                  NDICE
                  ======
	0.- Introduccin

	1.- Instalacin

	2.- Utilitzacin modular del editor php-js-webedit.

	3.- Utilitzacin sin botonera.

	4.- Utilitzacin con multi-textarea.

	5.- Utilitzacin del editor sin empotrar.

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

	7.- Estructura del mdulo.

	8.- Recepcin en el servidor de la pgina escrita.

	9.- Funcin Save.

	10.- Bugs conocidos.

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

0.- Introduccin

El editor php-js-webedit consiste en una pgina HTML que incluye una serie de botones y 
funciones Javascript que actan sobre un textarea para ayudar a construir un 
documento HTML de forma sencilla. De esta forma se genera el cdigo fuente HTML 
en el textarea, asistido por las funciones Javascript. En todo momento se puede 
ver una vista preliminar de la pgina para ver como va quedando.

La pgina del editor se construye dinmicamente en el servidor de forma personalizada,
mediante un sistema de parametrizacin que se detalla en el apartado 1.- de este
documento. Para implementar esto se ha utilizado, como lenguaje de servidor, PHP.

Una vez se ha construido y transmitido la pgina, el cliente puede operar con
todas las  funcionalidades. Lo que se haga cuando se acabe la pgina y se haga 
click en 'Guardar' depende de la funcin 'funcio_save' que se pase como parmetro.
Por ejemplo se puede pasar (por submit o en la URL) la pgina a una pgina del 
servidor y as registrar su contenido en una base de datos. De esta forma el 
php-js-webedit editor constituye una potente herramienta para gestionar un sitio
web mediante una base de datos.

Las funcionalidades que incluye el editor php-js-webedit son:

	1.- Vista preliminar.

	2.- Generacin de Anchors en el documento.

	3.- Generacin de Links.

	4.- Generacin de tablas.

	5.- Insercin de imgenes en el documento.

	6.- Cambio del ttulo del documento.

	7.- Cambio del color de fondo del documento.

	8.- Consulta de una paleta bsica de colores.

	9.- Nuevo documento (en blanco).

	10.- Utilizacin y gestin de estilos (estilos con cambio de fuente, tamao, 
	        color de la fuente, negrita, cursiva y subrayado).

	11.- Salto de lnea.

	12.- Insercin de un espacio en blanco.

	13.- Texto con formato: fuente, tamao, color, negrita, cursiva, subrayado.

	14.- Texto en negrita.

	15.- Texto en cursiva.

	16.- Texto subrayado.

	17.- Lnea horizontal.

	18.- Alineacin a la izquierda.

	19.- Alineacin centrada.

	20.- Alineacin a la derecha.

	21.- Generacin de listas numeradas.

	22.- Generacin de listas sin numeracin.

	23.- Indentado de prrafo.

	24.- Dos modos de funcionamento: guiado y directo.

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

1.- Instalacin

El editor php-js-webedit no requiere ninguna instalacin especial, es suficiente con copiar
los archivos de la aplicacin en un directorio y editar el archivo de configuracin
de los paths "paths_absoluts.h3p". Se debe dar valor a dos parmetros:

	$path_editor='/path_absoluto_del_editor/php-js-webedit/'; // Path absoluto 
	(para el servidor de pginas web), del editor php-js-webedit en el servidor 
	en el que se incluye la aplicacin. Esto es para que se puedan hacer los 
	includes correspondientes independientmente del documento en el que se empotra 
	el editor php-js-webedit.

	$path_icons='http://servidor/path_del_editor/php-js-webedit/'; // URL del
	directorio de iconos del editor php-js-webedit (normalmente el mismo que el 
	de la aplicacin)

Despus se debe editar el archivo "php-js-webedit.h3p" y asegurarse que en la primera 
lnea se hace un include correcto del archivo "paths_absoluts.h3p", CON EL PATH
NECESARIO. Por ejemplo:

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

Adems se requiere como mnimo PHP 3.0 en el servidor. Si no se tiene PHP se puede
tener una versin no configurable del editor. Ver el apartado "6.- Editor php-js-webedit 
sin PHP" de este mismo documento.

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.- UTILITZACIN MODULAR DEL EDITOR php-js-webedit:

Para poder utilizar el editor php-js-webedit como un mdulo empotrado en un 
documento cualquiera se debe hacer lo siguiente:

a) En el documento PHP poner las lneas de parametrizacin. La lista de parmetros
 y el significado de sus valores es el siguiente (se muestra un ejemplo, con los 
 valores por defecto para los parmetros):

$idi_edit='cat'; // Define el idioma en que se utilizar: 'cat' para cataln, 
'esp' para espaol, 'eng' para ingls.

$document_complet=1; // Si se pone 1 se considerar que se edita un documento 
completo y se incluir  cabecera, gestin de estilos, de color de fondo y de ttulo
de documento (estas funcionalidades slo se incluirn si as se indica en la 
parametrizacin, pero no se podrn incluir si no se trata de un documento 
completo). Si est a 0 se trata de una parte de un documento (como por ejemplo, 
un captulo de un documento mayor ) y por tanto no se incluir gestin de 
estilos, ni de color de fondo, ni de ttulo de ventana, y tampoco se pondr 
cabecera en el documento. 

$contingut_inicial=''; // Contenido inicial a cargar en el textarea. Esto es muy til 
si quieres editar un documento que ha sido creado con anterioridad.

$posar_form=1; // Si es 1 se englobar el editor (botonera y textarea) dentro de 
una form. Si no, no se pondr la form y se supondr que se genera la form 
correspondiente en el programa en el que se empotra el editor.

$nom_form='doc_html'; // Es el nombre que tendr la form. Aunque se indique 
$posi_form=0 se debe sumninistrar este parmetro para que la botonera propia del
editor funcione. Si no se utiliza esta botonera no es necesario dar este parmetro.

$posar_textarea=1; // Si es 1 se pondr textarea en el que editar. Si es 0 no se 
pondr y se supondr que lo incluye el programador que utiliza el editor.

$nom_textarea='text'; // Es el nombre del textarea en el que se edita. Si se pone 
botonera se debe especificar este parmetro aunque el textarea se genere en el 
archivo en el que se empotra el editor. Si el textarea lo pone el programador, es 
necesario que despus de ponerlo incluya una sentencia como la siguiente: 
<script> 
    obj_txt = document.nom_form.nom_textarea ; 
</script>
Si se utiliza multitextarea no es necesario, pero entonces se debe hacer la 
gestin de referencias al textarea que se edita. Para ms informacin ver el 
captulo de 'multitextarea' en este mismo documento.

$botonera=1; // Si est a 1 se incluir la botonera de funciones predeterminadas.
Se incluirn slo los botones especificados en la parametrizacin que sigue. Si 
est a 0 no se incluir botonera (se supone que la suministra el programador) y 
slo se incluir las funciones Javascript indicadas en la parametrizacin que 
sigue.

// De las funcionalidades disponibles, slo se incluir aquellas en que el 
parmetro sea 1. La lista es la siguiente:

$gestio_modes=1; // Funcionalidad de modalidad doble: directo o guiado. Si se 
pone 0, no se incluir el desplegable para escoger el modo, y se tomar la 
modalidad guiada por defecto.

$save=1; // Funcionalidad de 'Guardar' documento.

$funcio_save='salvar_documento(obj_textarea);'; // Es la funcin Javascript que 
se debe invocar para salvar el documento. ESTA FUNCIN DEBE ESTAR PROGRAMADA POR 
EL PROGRAMADOR QUE UTILIZA EL MDULO.

$preview=1; // Vista preliminar.

$anchor=1; // Anchor en el mismo documento.

$link=1; // Link (en el documento o universal).

$taula=1; // Generacin de tablas HTML.

$imatge=1; // Inclusin de imgenes en el documento.

$titol=1; // Ttulo del document.

$bgcolor=1; // Color de fondo del documento.

$new_doc=1; // Reseteado del documento, document en blanco.

$paleta=1; // Utilidad de consulta de los colores y su nombre.

$rang_paleta='baix'; // Si se pone 'alt' se tendr una paleta de 119 colores, y 
si se pone otro valor, de 42 colores.

$gestio_estils=1; // Gestin de estilos.

$breakline=1; // Nova lnea.

$nbsp=1; // Espacio en blanco.

$tipus_font=1; // Texto con formato: fuente, tamao, color, negrita, cursiva, 
subrayado.

$negreta=1; // Texto en Negrita.

$cursiva=1; // Texto en Cursiva.

$subry=1; // Texto subrayado.

$lin_horiz=1; // Generaci de lnia horitzontal de separaci

$alin_esq=1; // Alineacin del texto a la izquierda.

$centrat=1; // Centrado del texto.

$alin_dreta=1; // Alineacin del texto a la derecha.

$llista_numerada=1; // Funcionalidad de generacin de lista numerada.

$llista_no_num=1; // Funcionalidad de generacin de lista no numerada (discos o 
crculos).

$indentat=1; // Indentado del texto.

Se debe saber adems que en el document en el que se empotre el editor no se 
podrn utilizar los siguientes nombres 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 se pueden incluir en el mismo documento las siguientes funciones 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) Entonces, una vez escrita la parametrizacin se har:

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

Es muy importante saber que aunque se manipule el cdigo se debe respetar:

* La variable obj_txt debe contener una referencia al objeto 'textarea' en el que
 se quiere insertar los tags.

* La variable ob_est debe contener una referencia al objeto select de los estils.
 (Si se utilizan).

Entonces, si se ha incluido la botonera slo ser necesario definir la 
$funcio_save a ejecutar cuando se haga click en el botn de guardar.

CON LOS ARCHIVOS DE LA APLICACIN SE INCLUYE UN EJEMPLO DE PARAMETRIZACIN. EST 
EN 'php_param_example.h3p'.

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

3.- Utilizacin sin botonera.

Si no se ha incluido botonera se puede utilizar las funcionalidades seleccionadas 
invocando las funciones Javascript correspondientes.

Estas funciones tienen el mismo nombre QUE EL PARMETRO de configuracin. Adems,
se debe pasar a todas una referencia al objeto textarea en el que se quiere poner
los tags.

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

Para gestionar la referencia al objeto textarea se puede hacer simplemente:

<script>
	obj_txt = document.nombre_form.nombre_textarea ;
</script>
...
Entonces se llama la funcin:  negreta(obj_txt)

Para gestionar los modos se tiene la funcin canvi_mode(object_select), que pone
como modo el seleccionado en el object_select. Si se quiere hacer sin select se 
puede parametrizar con $gestio_modes=0; y entonces invocar la funcin 
canvi_mode(int a), donde 'a' es el nuevo valor a poner como modo. Recordemos que
'0' es modo directo y '1' es guiado.

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

4.- Utilizacin con multi-textarea.

Para utilizar el editor con muchos textareas slo se requiere poner 
ONFOCUS="obj_txt=this;" en la definicin del textarea:

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

Adems para inicializar con cabecera un textarea se debe:

* Poner en obj_txt la referencia al textarea:

<script>
	obj_txt = document.nombre_form.nombre_textarea ;
</script>

* Despus se debe llamar a la funci inici(int) i passar como parmetro: 1 si has 
puesto contenido antes de llamar a inici(int), y 0 en caso contrario.

<script>
	inici(0)
</script>

CON LOS ARCHIVOS DE LA APLICACIN SE INCLUYE UN EJEMPLO DE MULTI-TEXTAREA, EN EL 
ARCHIVO  'multi_textarea_example.h3p'.

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

5.- Utilizacin del editor sin empotrar.

Para utilizar el editor sin empotrarlo en un documento, simplemente se debe 
invocar el archivo php-js-webedit.h3p y pasar como parmetre $no_empotrat=1;

Se deber pasar tambin el parmetro $funcio_save='nom_funcio( ... );'

Finalmente, se invoca en el navegador la URL completa:

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

Si no se pasa el parmetro funcio_save simplement no se tendr funcin de guardado
del documento.

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

6.- Editor php-js-webedit sin PHP

Si no se tiene PHP o no se quiere utilizar, con la aplicacin se incluye una 
versin del editor exclusivamente en HTML y Javascript. El archivo en espaol 
es "php-js-webedit_spanish.html".

La nica cosa que tiene que hacer es editar el archivo para poner bien la URL de
los iconos de la aplicacin.(Es decir, cambiar el valor del atributo src de los 
tags <img ...> ).

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

7.- Estructura del mdulo.

De forma sinttica, el mdulo est programado con la siguiente estructura:

* Se han definido los objetos HTMLtag (para los tags), y estil_var (para los estilos).
 Para ms detalles ver los archivos tag.h3p y gestio_estils.h3p

* La funcin escriu_tag(object_textarea,object_tag,int) es la que se llama 
  recursivamente para escribir los tags anidados, con sus atributos, etc.

* Hay tantos ficheros *.h3p como funcionalidades, y tienen el mismo nombre que el
  parmetro de configuracin.

	Por ejemplo: $negreta => negreta.h3p

En estos ficheros se encontrarn las funciones Javacript pero tambin todos los 
mensajes (en las 3 lenguas, cataln, espaol y ingls). As que para corregir o 
cambiar mensajes se debe hacer en estos ficheros.

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

8.- Recepcin en el servidor de la pgina escrita.

En la $funcio_save especificada se puede hacer lo que se quiera con el contenido
del textarea.

Si se envia a una pgina del servidor, ser necesario aplicar alguna funcin para
passar los caracteres con acentos, como  a &Agrave;.

Con los archivos de la aplicacin se facilita la funcin (en php) 
convert_html($string); en el archivo 'convert_html.h3p'. (Contiene 94 caracteres 
especiales).

No se debe olvidar que la funcin escape de Netscape no va bien, porque los signos
'+' (al aplicar la decodificacin) quedan convertidos en espacios en blanco. Se 
debe entonces, antes  de aplicarla, convertir los '+' a algn carcter reservado
(p.e. '').

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

9.- Funci Save.

La funcin a ejecutar al hacer click en el botn save, queda definida en el 
parmetro $funcio_save.

Por ejemplo:

$funcio_save='tu_funcion(obj_txt);';

Sin embargo, cuando se utilicen directamente las funciones Javascript es bueno no
invocar directamente tu_funcion(obj_txt) sino a travs de save(obj_txt). Esto es 
porque en save(obj_txt) se ponen los tags </BODY></HTML> si es necesario.

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

10.- Bugs conocidos

El nico bug conocido del editor php-js-webedit es el siguiente:

a)	Los Links a anchors en la propia pgina no funcionan bien en la 
previsualizacin. Esto es debido a que el navegador no se comporta segn lo 
esperado si se pone el contenido de un documento con Javascript mediante la 
funcin document.write(string). 

	El problema est casi resuelto para Netscape, slo falla si se hace la 
	previsualizacin mientras se tiene abiertas otras ventanas des del mismo 
	documento. En el Explorer simplemente los links a anchors en el propio 
	documento no funcionarn en la previsualizacin.

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