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 páginas 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 fácilmente guardar las páginas en una base de datos.

Se puede usar como aplicación propiamente o empotrarlo en cuaqluier página web,
y es completamente personalizable por parte del programador que lo incluye en 
una pàgina.

El editor php-js-webedit está escrito en HTML y Javascript, y utiliza como
lenguaje de servidor el PHP. (Aunque existe una versión escrita exclusivamente 
en JavaScript y HTML: ver capítulo 6.- de este document).

Soporta edición simultánea en varios textareas. (Ver capítulo 4.- en este documento
para más información).

Tiene asistentes para construir las estrucutras HTML más utilizadas: tablas, links, 
anchors, texto con formato, estilos, imágenes, listas numeradas y no numeradas, etc.
No hay asistente para la utilización 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: catalán, 
español e inglés. El idioma se cambia fácilmente con sólo cambiar un parámetro.

Para dudas y sugerencias podéis contactar con gabi@unica.edu.

                  ÍNDICE
                  ======
	0.- Introducción

	1.- Instalación

	2.- Utilitzación modular del editor php-js-webedit.

	3.- Utilitzación sin botonera.

	4.- Utilitzación con multi-textarea.

	5.- Utilitzación del editor sin empotrar.

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

	7.- Estructura del módulo.

	8.- Recepción en el servidor de la página escrita.

	9.- Función Save.

	10.- Bugs conocidos.

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

0.- Introducción

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

La página del editor se construye dinámicamente en el servidor de forma personalizada,
mediante un sistema de parametrización 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 página, el cliente puede operar con
todas las  funcionalidades. Lo que se haga cuando se acabe la página y se haga 
click en 'Guardar' depende de la función 'funcio_save' que se pase como parámetro.
Por ejemplo se puede pasar (por submit o en la URL) la página a una página 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.- Generación de Anchors en el documento.

	3.- Generación de Links.

	4.- Generación de tablas.

	5.- Inserción de imágenes en el documento.

	6.- Cambio del título del documento.

	7.- Cambio del color de fondo del documento.

	8.- Consulta de una paleta básica de colores.

	9.- Nuevo documento (en blanco).

	10.- Utilización y gestión de estilos (estilos con cambio de fuente, tamaño, 
	        color de la fuente, negrita, cursiva y subrayado).

	11.- Salto de línea.

	12.- Inserción de un espacio en blanco.

	13.- Texto con formato: fuente, tamaño, color, negrita, cursiva, subrayado.

	14.- Texto en negrita.

	15.- Texto en cursiva.

	16.- Texto subrayado.

	17.- Línea horizontal.

	18.- Alineación a la izquierda.

	19.- Alineación centrada.

	20.- Alineación a la derecha.

	21.- Generación de listas numeradas.

	22.- Generación de listas sin numeración.

	23.- Indentado de párrafo.

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

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

1.- Instalación

El editor php-js-webedit no requiere ninguna instalación especial, es suficiente con copiar
los archivos de la aplicación en un directorio y editar el archivo de configuración
de los paths "paths_absoluts.h3p". Se debe dar valor a dos parámetros:

	$path_editor='/path_absoluto_del_editor/php-js-webedit/'; // Path absoluto 
	(para el servidor de páginas web), del editor php-js-webedit en el servidor 
	en el que se incluye la aplicación. 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 aplicación)

Después se debe editar el archivo "php-js-webedit.h3p" y asegurarse que en la primera 
línea 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";

Además se requiere como mínimo PHP 3.0 en el servidor. Si no se tiene PHP se puede
tener una versión 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 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ÓN MODULAR DEL EDITOR php-js-webedit:

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

a) En el documento PHP poner las líneas de parametrización. La lista de parámetros
 y el significado de sus valores es el siguiente (se muestra un ejemplo, con los 
 valores por defecto para los parámetros):

$idi_edit='cat'; // Define el idioma en que se utilizará: 'cat' para catalán, 
'esp' para español, 'eng' para inglés.

$document_complet=1; // Si se pone 1 se considerará que se edita un documento 
completo y se incluirá  cabecera, gestión de estilos, de color de fondo y de título
de documento (estas funcionalidades sólo se incluirán si así se indica en la 
parametrización, pero no se podrán 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 capítulo de un documento mayor ) y por tanto no se incluirá gestión de 
estilos, ni de color de fondo, ni de título 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 parámetro para que la botonera propia del
editor funcione. Si no se utiliza esta botonera no es necesario dar este parámetro.

$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 parámetro 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 después 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 
gestión de referencias al textarea que se edita. Para más información ver el 
capítulo de 'multitextarea' en este mismo documento.

$botonera=1; // Si está a 1 se incluirá la botonera de funciones predeterminadas.
Se incluirán sólo los botones especificados en la parametrización que sigue. Si 
está a 0 no se incluirá botonera (se supone que la suministra el programador) y 
sólo se incluirá las funciones Javascript indicadas en la parametrización que 
sigue.

// De las funcionalidades disponibles, sólo se incluirá aquellas en que el 
parámetro 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 función Javascript que 
se debe invocar para salvar el documento. ESTA FUNCIÓN DEBE ESTAR PROGRAMADA POR 
EL PROGRAMADOR QUE UTILIZA EL MÓDULO.

$preview=1; // Vista preliminar.

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

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

$taula=1; // Generación de tablas HTML.

$imatge=1; // Inclusión de imágenes en el documento.

$titol=1; // Título 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; // Gestión de estilos.

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

$nbsp=1; // Espacio en blanco.

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

$negreta=1; // Texto en Negrita.

$cursiva=1; // Texto en Cursiva.

$subry=1; // Texto subrayado.

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

$alin_esq=1; // Alineación del texto a la izquierda.

$centrat=1; // Centrado del texto.

$alin_dreta=1; // Alineación del texto a la derecha.

$llista_numerada=1; // Funcionalidad de generación de lista numerada.

$llista_no_num=1; // Funcionalidad de generación de lista no numerada (discos o 
círculos).

$indentat=1; // Indentado del texto.

Se debe saber además que en el document en el que se empotre el editor no se 
podrán 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 parametrización se hará:

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

Es muy importante saber que aunque se manipule el código 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 sólo será necesario definir la 
$funcio_save a ejecutar cuando se haga click en el botón de guardar.

CON LOS ARCHIVOS DE LA APLICACIÓN SE INCLUYE UN EJEMPLO DE PARAMETRIZACIÓN. ESTÁ 
EN 'php_param_example.h3p'.

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

3.- Utilización 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 PARÁMETRO de configuración. Además,
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 función:  negreta(obj_txt)

Para gestionar los modos se tiene la función 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 función 
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.- Utilización con multi-textarea.

Para utilizar el editor con muchos textareas sólo se requiere poner 
ONFOCUS="obj_txt=this;" en la definición del textarea:

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

Además 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>

* Después se debe llamar a la funció inici(int) i passar como parámetro: 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 APLICACIÓN SE INCLUYE UN EJEMPLO DE MULTI-TEXTAREA, EN EL 
ARCHIVO  'multi_textarea_example.h3p'.

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

5.- Utilización 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 parámetre $no_empotrat=1;

Se deberá pasar también el parámetro $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( ...parámetros_función_save... )

Si no se pasa el parámetro funcio_save simplement no se tendrá función de guardado
del documento.

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

6.- Editor php-js-webedit sin PHP

Si no se tiene PHP o no se quiere utilizar, con la aplicación se incluye una 
versión del editor exclusivamente en HTML y Javascript. El archivo en español 
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 aplicación.(Es decir, cambiar el valor del atributo src de los 
tags <img ...> ).

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

7.- Estructura del módulo.

De forma sintética, el módulo está programado con la siguiente estructura:

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

* La función 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
  parámetro de configuración.

	Por ejemplo: $negreta => negreta.h3p

En estos ficheros se encontrarán las funciones Javacript pero también todos los 
mensajes (en las 3 lenguas, catalán, español y inglés). Así que para corregir o 
cambiar mensajes se debe hacer en estos ficheros.

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

8.- Recepción en el servidor de la página escrita.

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

Si se envia a una página del servidor, será necesario aplicar alguna función para
passar los caracteres con acentos, como À a &Agrave;.

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

No se debe olvidar que la función escape de Netscape no va bien, porque los signos
'+' (al aplicar la decodificación) quedan convertidos en espacios en blanco. Se 
debe entonces, antes  de aplicarla, convertir los '+' a algún carácter reservado
(p.e. '´').

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

9.- Funció Save.

La función a ejecutar al hacer click en el botón save, queda definida en el 
parámetro $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 través 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 página no funcionan bien en la 
previsualización. Esto es debido a que el navegador no se comporta según lo 
esperado si se pone el contenido de un documento con Javascript mediante la 
función document.write(string). 

	El problema está casi resuelto para Netscape, sólo falla si se hace la 
	previsualización mientras se tiene abiertas otras ventanas des del mismo 
	documento. En el Explorer simplemente los links a anchors en el propio 
	documento no funcionarán en la previsualización.

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