File: readme.txt

[DESCRIPTION]

    The HTML_Editor is meant to dynamically compose and output HTML documents.
    
    It provides functions to add many different types of the HTML elements to the document that 
    is being composed.
    
    Using HTML_Editor with classes like the PEAR::HTML_Table and PEAR::HTML_Forms or other 
    PEAR::HTML_* classes it provides a complete interface to create HTML documents of any 
    complication or parts of HTML formatted text on the fly. 
    
    With this class you can create any tags enclosed text like(P, H(1-6), B, LI, UL, SPAN, etc) 
    with any of attributes. You can also create link, image, meta tags.
    
    If you use PHP 5 you can reformat the output with the tidy extension. There is tidy.cnf 
    file included with all options available and you can customize it as you like to change output.
    
    this class also include very simple CSS creation class. It is called CSS_Editor. It has 
    3 main methods. setElement, setProperties, getCss.
    
    example of use
    
    1  $css = new CSS_Editor;
    2
    3  $h1 = $css->setElement('H1');
    4
    5  $array = (
    6      'color' => '#663399',
    7      'font-weight' => 'bold'
    8  );
    9  $css->setProperties($h1, $array); 
    10 
    11 $a = $css->setElement();
    12 $css->setProperties($a, array('text-decoration' => 'none'));
    13 
    14 $text_css = $css->getCss();
    
    in this example first we create new class in line 1, then in line 3 create an element H1 for 
    formating <H1> tag. than in lines 5-8 we create array of formatting properties and set these 
    properties to H1 element in line 9. Another element with pseudo class is created in line 11. 
    it could be not only 'a:hover' but link to id '#my_link' or class '.my_link'. In line 12 we 
    set property for  'a:hover' element. And finally in line 14 we get all this as a formated 
    string that would looks like this:
    
    H1{
       color:#663399;
       font-weight:bold;
    }
    
    a:hover{
        text-decoration:none;
    }


[INSTALLATION]
    to install this class simple copy html_editor.php to your include or lib directory.
    see section [EXAMPLES]
    

[Tidy]
    For php5 there is feature build-in for formating output with tidy. This uses tidy.cfg. This 
    file content all setting available for tidy. You just customize it the way you need. The 
    tidy.cfg file must be in the same directory as html_editor.php.
    

[EXAMPLES]
    to use HTML_Editor simply call it from directory you have coped it to using require_once.
    see example.php.


[REFERENCES]

    integer = newDocument([string = $title]);
        this function create new document and return pointer to this document that is used 
        almost in any other  function.
        
        example:
        
        $html = new HTML_Editor;
        $doc1 = $html->newDocument('This is the Title');


    void addMeta(integer = $doc, array = $meta);
        this method inserts name/content meta tags in to the document
        
        $doc = integer that point on document that is created by newDocument() function;
        $meta = array that content meta data
        
        example:
        $meta = array(
            'author' => 'Sergey Romanov',
            'generator' => 'HTML-Kit',
            'keywords' => 'html_editor, php, etc..',
            'description' => 'use HTML_Editor for improving you programming speed'
        );
        $html->addMeta($doc1, $meta);
    
    
    void addMetaHttp(integer = $doc, array = $meta);
        this method insert into document http meta tags.
        
        $doc = integer that point on document that is created by newDocument() function;
        $meta = array that content http meta data

        $meta_http = array(
            'content-type' => 'text/html; charset=windows-1251'
        );
        $html->addMetaHttp($doc1, $meta_http); 



    string = makeImg(string = $src [,array = $options]);
        this method return string that content <img ..> tag. It can  than be inserted to the 
        document
        
        $src = image source
        $options = array of additional attributes,
        
        example:
        $ico = $html->makeImg('/images/register_ico.gif', array('border'=>'0'));
    

    string = makeLink(string = $href, string = $lable [, array = $options]);
        this method return string that content <a ..>..</a> tag. It can than be inserted to the 
        document 
        
        
        $href = string link href
        $lable = string link text
        $options = array of additional attributes,

        example:
        $ico = $html->makeLink('http://msn.com', 'Go to MSN', array('title'=>'this is link to MSN sitr'));

        
    void = addHeadAdditions(integer = $doc1, string = $text);
        this function inserts into <head></head> section additional code. This is useful if you 
        want insert <style></style> or <script></script> tags into head section.
        
        $doc = integer that point on document that is created by newDocument() function;
        $test =  string you want to insert to head section
        
    
    void = setBodyAttr($doc, $attr);
        this method set attributes for body tag
        
        $doc = integer that point on document that is created by newDocument() function;
        $attr = array set of attributes.
        
        example:
        $ba = array(
            'margintop' => '0',
            'marginwidth' => '0'
        );
        $html->setBodyAttr($doc, $ba);
        
    
    viod = writeHtml(integer = $doc, string = $tag, string = $string [, array = $attributes]); 
        this method writes text($string) to the end of document($doc) enclosed in tag($tag)
        
        $doc = integer that point on document that is created by newDocument() function;
        $tag = string tag in which $text is enclosed
        $text = string text to write to document
        $attributes = array of attributes for tag
        
        example:   
        
        $html->writeHtml($doc, 'H1', 'This will appear as header 1');
        $html->writeHtml($doc, 'P', 'and this will be a paragraph under header.');
    
    string = getHtml( string = $tag, string = $string [, array = $attributes]);
        this is the same as writeHtml() method but this is not writing to document
        but return. This is useful to prepare parts of html formated text for displaying or 
        inserting to the document. 
    
        $tag = string tag in which $text is enclosed
        $text = string text to write to document
        $attributes = array of attributes for tag


    string = highlightText(string = $tag , string = holder, string = $text [, array = $attr]);
        this method provide you possibility to insert html tags into the text and return 
        formated text.
        
        $tag = string tag to insert
        $holder = string what to highlight
        $text = in which text to highlight
        
        example:
        $text = 'This is an example text';
        $text = $editor->highlightText('B',' is ',$text, array('class'=>'test'));
        $text = $editor->highlightText('i',' example ',$text);
        
        after that $text will contect
        
        This <B class="test">is</B> an <i>example</i> text
        
    
    string = docGet(integer = $doc);
        this method return html document with head, body sections ready to display.
        
        $doc = integer which document to return
        
        example:
        
        echo $html->docGet($doc);
    
    
    void = docSave(integer = $doc, string = $path);
        this method save document in path specified.
        
        $doc = integer which document to save
        $path = string the path document to save to.
        
        example:
        
        $html->docSave($doc, '/www/htdocs/dir/my.html');
        header('location:/dir/my.html');
        
        
    string = docShow($doc);
        just print document specified by $doc 
    
        
        
        
[TO DO]
method setBodyAttr() - the method that will allow to set attributes for tag <body>

[CHANGE LOG]

    [2-Aug-2004] v.0.0.2
    The error that have appeared on php4.x.x have been fixed.
    Added 2 new functions
    fixed (tidy.cfg not fond) error with php5