php-js-webedit 1.0 - Readme_english.txt for php-js-webedit editor, developed 
at Universitat Internacional de Catalunya (www.unica.edu) (30/11/2000).

php-js-webedit editor is a tool for editing and building HTML pages (relatively
complex) from a browser, so you can edit without the composer or the frontpage,
and transfer the content directly to a server by submiting a form, or passing it 
into the URL. This allows to store easily the HTML page in a database.
You can use it as an application itself or embedded in any page of your web 
applications, and it is completely configurable by the programmer who is
embedding it in one of his pages.

php-js-webedit editor is written in HTML and Javascript for the client side, and 
PHP as a server-side language.(Though there is a version written exclusively in
Javascript and HTML: see chapter 6.- in this document).

It supports multi-textarea edition. (See chapter 4.- in this document for more
information).

It has an assistant to write the most common HTML structures: tables, links, 
anchors, formatted text, styles, images, numbered and not numbered lists, etc. It has
no assistant to create frames and forms, so you have to built them up manually.

It has been tested in Netscape 4.05 and higher and in Explorer 5.0

php-js-webedit editor can be used in three different languages: cathalan (the language 
from Catalonia, a region in Spain whose capital is Barcelona), spanish and 
english. You can easily change the language by just changing a parameter($idi_edit).

For any doubt or question you can contact gabi@unica.edu.

                      INDEX
                      =====
	0.- Introduction

	1.- Installation

	2.- Embedded use of the php-js-webedit editor.

	3.- Use without toolbars.

	4.- Multi-textarea use.

	5.- Non-embedded use of the php-js-webedit editor.

	6.- php-js-webedit editor without PHP.

	7.- Program Structure (and how to change the messages and warnings of the 
            application).

	8.- Server reception of the written page.

	9.- Save function.

	10.- Known Bugs.

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

0.- Introduction

php-js-webedit editor is a web page which includes a lot of Javascript functions to 
generate HTML code within a textarea. Then, the functions help you to generate 
the HTML code so you don't have to know how to create a table or a link, or a 
list, in HTML. You can also always show a preview of how the document will 
look like.

The editor's page is dinamically built-up according to the configuration (see 
next chapter for more details). For doing this, the application uses PHP as a 
server-side language.

Once the page has been built-up and transferred to the client, you can use all 
the features locally so you don't need to connect to the server again 
until you want to save the page. Then you press 'Save' button which will invoke
the function you have configured. From this function you can submit the 
content of the textarea (which is the code of the document you have created),
and then store it in a database from the server. This makes php-js-webedit a
powerful tool to build a web site managed in a database.

php-js-webedit have the following features:

	1.- Page Preview.

	2.- Generation of document anchors.

	3.- Generation of Links.

	4.- Generation of tables.

	5.- Insert images in the document.

	6.- Change document's title.

	7.- Change document's background colour.

	8.- Consultation of a basic colours palette.

	9.- New document (blank one).

	10.- Styles use and management.

	11.- New line.

	12.- Blank space insertion.

	13.- Formatted text: font face, size, color, bold, italic, underlined.

	14.- Bold text.

	15.- Italic text.

	16.- Underlined text.

	17.- Horizontal line.

	18.- Left alignment.

	19.- Center alignment.

	20.- Right alignment.

	21.- Generation of numbered lists.

	22.- Generation of not numbered lists.

	23.- Block quoting.

	24.- Two modes of user-assistance: guided and direct.

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

1.- Installation

php-js-webedit editor does not require any specific installation process. It's enough 
to copy the files into a directory and edit the configuration file 
"paths_absoluts.h3p". In this file you have to configure two parameters to 
specifiy the paths and URL of the directory where the application is:

	$path_editor='my_absolute_path/gabi/php-js-webedit/'; // Absolute Path (from 
	the web-server) of the directory where the php-js-webedit editor is. This is to
	allow the editor to include the other files of the application independently of
	the document where the editor is embedded.

	$path_icons='http://my_server/my_path/php-js-webedit/'; // URL of the directory
	of the icons of the editor (usually same as the application)

After doing this you should edit file "php-js-webedit.h3p" and be sure the first line
is a correct include of the file "paths_absoluts.h3p", with THE RIGHT PATH. 
For instance:

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

You also need at least PHP 3.0 in the server. If you don't have PHP there is a 
non-configurable version written exclusively in HTML and Javascript. See chapter
"6.- php-js-webedit editor without PHP" for more information.

REMARK: All the PHP files of the application has the extension 'h3p' because this
our the extension our Apache server uses to recognize which files should be 
parsed by PHP. If you use 'php3' or any other you have to do two things:

a) Change the extension of all '*.h3p' files to your extension (as '*.php3').

b) Replace the string '.h3p' by your extension (as '.php3') in all the '*.h3p' files.

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

2.- Embedded use of the php-js-webedit editor:

In order to use the php-js-webedit editor embedded in another document you have 
to do as follows:

a) In the PHP document where you want to embed the php-js-webedit editor define
the configuration parameters. The list of all the parameters and their meaning 
is the following (the list also shows the default values for the parameters):

$idi_edit='cat'; // It defines the language to use: 'cat' for cathalan, 'esp' 
for spanish , and 'eng' for english.

$document_complet=1; // If it is 1 it means you want to edit a complete document,
so it will include header and the associated features as document's title,
document's background colour, styles use and management. Of course all these 
features will only be included if the associated parameters are 1, but 
cannot be included if this parameter is 0. If this parameter is 0 this indicates
that you are building just a part of a document, for example as a chapter of a 
bigger document, so you won't be able to include header utilities(as title, 
or background colour or styles).

$contingut_inicial=''; // Initial content of the document. This is very useful 
if you want to edit a document which has already been created.

$posar_form=1; // If it is 1 the editor will be all included (buttons and 
textarea) into a form. If not, it is suposed the programmer will create the form
(<form name= ... >) and close it (</form>) after the embedding of the editor.

$nom_form='doc_html'; // Form's name. Even if you write the <form> and </form> 
tags before and after embedding the editor, you have to supply this name, 
for the Javascript functions in the editor to run correctly.

$posar_textarea=1; // If it is 1, the textarea will be created by the editor. If
not it has to be created by the programmer, and after putting it the programmer 
should include a sentence like this 
<script> 
	obj_txt = document.form_name.textarea_name ;
</script>
If you want to create the form and textarea, you better read all this 
document to understand how you have to manage the obj_txt object(a javascript 
reference to the textarea object where you want the editor to insert the HTML 
code).

$nom_textarea='text'; // Textarea's name where the editor is inserting the HTML 
code. If you use the toolbars it is necessary even if you are generating the 
textarea. If you use more than one textarea this should be one of the names, and 
then you have to manage the references to the textarea where you want to edit. 
See chapter '4.- Multi-textarea use' for more information.

$botonera=1; // If it is 1, the toolbars will be included, if it is 0 it will 
only be included the Javascript functions so you will have to build-up your own
method to invoke the functions, as menus or toolbars. Of course, in any case it
will be included only the buttons or functions corresponding to the 
features whose parameter you have set to 1.

// The parameters corresponding to the features are:

$gestio_modes=1; // Mode (guided or direct). If it is 1, the select box with the
two possibilities (guided and direct) will be shown. If it is 0, the select box 
won't be shown and the default mode will be guided. (See last paragraph of 
chapter 3.- to know how to use the function canvi_mode(int) to change the mode 
from your own Javascript code).

$save=1; // 'Save document' feature.

$funcio_save='salvar_documento(obj_textarea);'; // It is the prototype of the 
Javascript function you want to be invoked when the user clicks on Save button.
This function must be included in the document by the programmer.

$preview=1; // Preview.

$anchor=1; // Anchor in the document.

$link=1; // Link.

$taula=1; // Generation of tables.

$imatge=1; // Insert images in the document.

$titol=1; // Document's title.

$bgcolor=1; // Document's background colour.

$new_doc=1; // New document (blank).

$paleta=1; // Colours Palette consultation.

$rang_paleta='baix'; // if it is 'alt' the colours palette will have 119 colours,
if it is any other value it will have 42 colours.

$gestio_estils=1; // Styles use and managemenet.

$breakline=1; // New line.

$nbsp=1; // Blank space.

$tipus_font=1; // Formatted text: font face, size, color, bold, italic, underlined.

$negreta=1; // Bold text.

$cursiva=1; // Italic text.

$subry=1; // Underlined text.

$lin_horiz=1; // Horizontal line.

$alin_esq=1; // Align left.

$centrat=1; // Center horizontally.

$alin_dreta=1; // Right align.

$llista_numerada=1; // Numbered list generation.

$llista_no_num=1; // Not numbered list generation.

$indentat=1; // Indent text.

The document where you are embedding the php-js-webedit editor cannot have 
Javascript variables with the following names:

	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                 


// Same way, the document where you are embedding the php-js-webedit editor cannot
have Javascript functions with the following names: (in fact this list shows the 
prototypes of the functions)

	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) Then, once you have set the parameters you maust do:

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

You should know that... :

* The variable obj_txt must contain a reference to the textarea object where you
want to insert the HTML code. You can use this from your Javascript source (for 
instance the save_function function).

* The variable ob_est contains a reference to the select box object which shows 
the styles.

AMONG THE FILES OF THE APPLICATION THERE IS ONE EXAMPLE OF HOW TO PARAMETRIZE AND
EMBED THE php-js-webedit EDITOR FROM THE PHP. IT IS THE 'php_param_example.h3p' FILE.

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

3.- Use without toolbars.

If you don't want to include the toolbars or you want to build-up your own toolbars
you can just use the Javascript functions.

This functions have the same name as the associated configuration parameter. All 
the functions need only one parameter: a reference to the textarea object where 
you want to insert the HTML code.

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

To manage the reference to the textarea object you can use code like this:

<script>
	obj_txt = document.form_name.textarea_name ;
</script>
...

Then you can invoke the negreta (sorry it means BOLD in cathalan :-)  ) function
as follows: negreta(obj_txt)

To manage the modes (guided or direct) you can use the function
canvi_mode(object_select_of_the_modes), which sets mode with the current value 
of the select box of the modes. If you are not using modes (or don't want to 
use a select box) you can set parameter $gestio_modes=0;  and then use function 
canvi_mode(int a) which put value 'a' as the new mode value (remember '0' is 
direct and '1' is guided).

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

4.- Multi-textarea use.

To use the php-js-webedit editor with more than one textarea you have to put 
ONFOCUS="obj_txt=this;" in the textarea definition:

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

Also, to initialize the textarea with a header you have to:

* Put into obj_txt the reference to the textarea where you want to insert the
  header:

<script>
	obj_txt = document.form_name.textarea_name ;
</script>

* After this you have to call the function inici(int a), where 'a' should be: 1 
  if you have put content before calling inici(int), and 0 if not:

<script>
	inici(0)
</script>

AMONG THE FILES OF THE APPLICATION THERE IS ONE EXAMPLE OF HOW TO MANAGE THE 
php-js-webedit EDITOR WITH TWO TEXTAREAS. IT IS THE 'multi_textarea_example.h3p'
FILE.


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

5.- Non-embedded use of the php-js-webedit editor.

To use the php-js-webedit editor without embedding it into another document, you
can just call the corresponding URL passing $no_empotrat=1 as a parameter.

If you want to use a specific save function (which can be in another frame) you 
can pass it as a parameter, as $funcio_save='nom_funcio( ... );'

So finally, the complete URL could be:

	URL_directory_editor/php-js-webedit.h3p?no_empotrat=1&funcio_save=function_name(
	  ...parameters_save_function... )

If you are not passing the parameter funcio_save, you won't simply have any save
function so the only way to preserve the code will be do copy & paste.

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

6.- php-js-webedit editor without PHP

If you don't have PHP or don't want to use it, with the application there is a 
version of the php-js-webedit editor written exclusively in php-js-webedit and 
Javascript. The file in english is "php-js-webedit_english.html".

The only thing you have to do is edit the file and correct the URL of the icons
directory of the application.(It means change the value of the src attribute of
the <img ...> tags).

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

7.- Application structure (and how to change the messages of the application).

Basically the structure of the source code of the application is:

* The class HTMLtag implements the tag behaviour, so there is as many objects as 
different tags the application can use. The class estil_var implements the 
behaviour of the styles, because each style is an instance of this class. For more 
details see files tag.h3p and gestio_estils.h3p

* The function escriu_tag(object_textarea,object_tag,int) is called recursively 
to insert the nested tags, the attributes, etc.

* There are as many *.h3p files as features, and they have same name as the
associated configuration parameter:

	For example: $negreta => negreta.h3p

In this files there are the Javascript functions but also the messages in the 
three different languages (cathalan, spanish and english). Then, to correct or 
modify any message you should do it in the corresponding file. English is not 
the native language of the creator of php-js-webedit, so if you find any ortographic 
or grammar error we would be very thankful if you send a mail to gabi@unica.edu 
to inform us.

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

8.- Server reception of the written page.

In the save function you can do whatever you want to with the content of the 
textarea.

If you send the document to a page of the server you should apply any function to
convert the special characters, (as À) to the html code (as &Agrave;).

Among the files of the application there is the function (written in php)
convert_html($string); in the file 'convert_html.h3p'. (It contains 94 different
special characters).

You should remember that Netscape's escape function doesn't work OK, because 
'+' character it is converted into a blank space when it is decoded. So before 
calling to escape(...) you have to convert the '+' to a reserved character as '´'.

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

9.- Save function.

The function to execute when the user clicks on save button is defined in the 
parameter $funcio_save.

For example:

$funcio_save='your_function(obj_txt);';

But when you call directly the Javascript function(if you are not using the 
buttons and toolbars) you should not call directly your_function(obj_txt); but 
trough save(obj_txt);. This is because save(obj_txt); puts the tags </BODY></HTML>
if needed.

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

10.- Known Bugs

The only known bug is the following:

a)	Links to anchors in the same page doesn't work properly in the preview. This 
is because browsers doesn't behaviour as expected when you create a document with 
a link in the same page by using the function document.write(string_with_the_HTML_code);.

The problem is almost solved in Navigator, it only appears if you have open 
windows (open from the same document) when you order the preview. In Explorer, 
links to anchors in the same document simply won't work in the preview.

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