HTML X Lite: Generate HTML pages programatically

This small class code help you create html code to your browser
more easily and quickly

Problem:

When you write any html code you must be very carefully to close correctly
html tags, because the page can disintegrate.
If your site has more larger, you must do a hard work to debug any html
format fault in source code and you spend a much time with debugging,
instead of site develop. This short code can helps in this.

Solution:

The great htmlxlite.php class!

This code based on a stack array, where the handler functions collect
your opened tags with that names and that sort.
If you want to close any earlier opened tag, you mustn't remember those name
and sort. Indeed! Nor between particular of quantity.
You can close more tags correctly with a single function call!
And you can move any tag create calls for change parent-child creation!
Therein lies the real power of this code!

Please read this document carefuly before begin to use this class,
because may be difficult to understand at first.




CHAPTER I : How to use

You can begin to use this class with a simple include:

	include "htmlxlite.php"

This creates a 'html' namespace thus you can use immediately with

        html::<tagname>();

function calls. Example:

	html::hr();

The above call creates and send the next row to your browser, what displays a
simple horizontal line:

	<hr />

Of course you can create a more complex rows using any call parameter.
So you can add any html attribute with the next syntax:

	html::<tagname>("<attrname>=<parameter>","<attrname>=<parameter>",etc...);

Adding your call parameters always optionaly! Look an example:
i.e.: let's create a FONT tag with two parameter:

	html::font("class=fontclass1","color=#F00");

The htmlxlite transforms the above call to:

	<font class="fontclass1" color="#F00">

You can see the apostrof has moved to behind equal sign and the parameter comes into this only!
Because this tag has a close pair thus this html code now stays open!
I.e. now you can add any child tags on this point with same procedure.
For example you can insert any text into with an echo call:

	echo "This is some text";

Or use htmlxlite 'write' function:

	html::write("This is some text");

The different is the two solution just the code alignmention, which code will more
transparently, as if use echo call.
If you don't want to add more child tag or text to this, you can close with a simple call:

	html::closetag();

After above code you can see in browser:

	<font class="fontclass1" color="#F00">
	This is some text
	</font>

There is a two special call parameter to help you create more complex row.
The either of them inserts hipertext between the open and close tags, and
closes it immediately:

	html::font("class=fontclass1","color=#F00","txt=This is some text");

The htmlxlite translates the above code to:

	<font class="fontclass1" color="#F00">This is some text</font>

This solution is the real three in one: opens a tag with those name and attributes,
inserting some text and close the opened tag in care html standards and code aligning for
help!

Remark: there is some tag whose has no close pair. At those the 'txt=' parameter
not interpreted. You can use 'value=' parameter instead of 'txt='.
With the use 'txt=' parameter the text added same row, as tag.
If you didn't determine any parameter for 'txt=' then you just close tag immediately.
For example:

	html::div("txt=");

translate to

	<div></div>

The another special call parameter is the 'ret', which you can call back the translated
the row to any string variable instead of echo.
For example:

	$SOMEFONT = html::font("class=fontclass1","color=#F00","txt=This is some text","ret");

As the above code willn't send those result to the browser, only returns that to the
$SOMEFONT variable

Now look an example for parent-child creation:

	html::ul("class=ulclass1");
        html::li("class=liclass1","txt=this is the 1. element");
        html::li("class=liclass1","txt=this is the 2. element");
	html::closetag();

The above code results the next:

	<ul class="ulclass1">
	 <li class="liclass1">this is the 1. element</li>
	 <li class="liclass1">this is the 2. element</li>
	</ul>

Because the 'closetag' function closes always the last opened tag, so you must close 'ul' tag only here.
Please notice because, the 'li' tag is child of the 'ul' tag, therefore gets a white space character
a front comparing 'ul'. This is the automatic alignment function, what can help you debug html code!

Remark: if you set "DEVELOP_MODE" to false, you can disable this function, what results a
shorter code. So just stays the relevant html code, without any alignment, line feed, and remarks!

Now organize the above code a for cycle:

	html::ul("class=ulclass1");
        for ( $I = 1 ;$I < 3 ; ++$I ) { html::li("class=liclass1",sprintf("txt=this is the %s. element",$I)); }
	html::closetag();

This code results same html code, but you can determine, how many child elements let's have 'ul' tag
Now, you can embed any child combine with 'txt=' and 'ret" parameter.
For example: create a table with some child:

	html::table();
	html::tr("txt=".html::td("class=tdclass1","txt=cellinfo1","ret"));
	html::closetag();

The above code results:

	<table>
	 <tr><td class="tdclass1">cellinfo1</td></tr>
	</table>

You can look, both of 'tr' and 'td' tag now closed as reversed order. This come from bracked embed, what
determines the creating order.
Now look an example for multi tag closing.
Let's create a 'p' tag into a 'div' block, fill it with some text and close those once:

	html::div();
	html::p();
	html::write("This is some text");
	html::closetag(2);

The above code results the next:

	<div>
	 <p>
	  This is some text
	 </p>
	</div>

You can see the htmlxlite aligns the closer tags same column as those open tag.
Now change the first two row:

	html::p();
	html::div();
	html::write("This is some text");
	html::closetag(2);

And the result is:

	<p>
	 <div>
	  This is the some text
	 </div>
	</p>

Because we change the order of first two row, with this changes the closer tags order too.
This guarantes the closer tag order stays always correct!

There is some more function, what helps you create your page complete:

You can call embed input object with call those type:
For example:

	html::password();

translates to:

	<input type="password" />

These the next functions: 'button','checkbox','file','hidden','image','password','radio','reset','submit','text','date','number','range','slider'
For more information, please refer the html standard at W3C school page ( http://www.w3schools.com/tags/tag_input.asp )




CHAPTER II : Block returns

During in develop you can be into such position, when you must returns from the middle of your code
(for example an error occur to handle),
therefore may too difficult to determine quantity of tags must be close, what that function is opened.
Here you can get help from 'start_block' and 'end_block' function pairs.

This functions based on relative stack index, where you can sign any return point, before run any other function.
The 'start_block' function puts a return point sign to the stack array.
The 'end_block' function calculates the quantity of unclosed tags and closes it.
Look an example:
We create a container for display main screen and we call a sub function, what must display any other information
as child, but doesn't close correctly all of those opened tags:

	function main() {
	  html::div("class=container");
	  this->display_info();
	  html::closetag();
        }

	function display_info()	{
	  html::div()
	  html::p("txt=This is some information");
	  if (ERROR) return;
	  html::closetag();
	}

We can look if call 'main' function, this creates a 'div' container to prepare display any other information.
The information displays the 'display_info' function, where become 'div' child and those 'p' child.
This translated to:

	<div class="container">
	 <div>
	  <p>This is some information</p>
	 </div>
	</div>

So when everything is good, the opened tags closed correctly. But what happen, if gets any error!?
Then you displayed the next:

	<div class="container">
	 <div>
	  <p>This is some information</p>
	 </div>

The main container 'div' wasn't closed, because the sub function returns before closes those opened tag.
Sometimes it's very hard to determine exact quantity, what you must close, before return, as you can use
the 'start_block' - 'end_block' function pair:

	function main() {
	  html::div("class=container");
	  start_block();
	  this->display_info();
	  end_block();
	  html::closetag();
        }

	function display_info()	{
	  html::div()
	  html::p("txt=This is some information");
	  if (ERROR) return;
	  html::closetag();
	}

If we now have any error, the 'end_block' function calculates the exact quantity of closer tag and
closes those if any! So even you can leave the last 'closetag' from the 'display_info' function!
i.e:

	function main() {
	  html::div("class=container");
	  start_block();
	  this->display_info();
	  end_block();
	  html::closetag();
        }

	function display_info()	{
	  html::div()
	  html::p("txt=This is some information");
	  if (ERROR) return;
	}

Now your block will always close correctly:

	<div class="container">

	 <-- here put a hidden index sign with using start_block

	 <div>
	  <p>This is some information</p>
	 </div>

         <--here we returned to the hidden index sign with using end_block

	</div>



CHAPTER III : Remark and messages

The htmlxlite can insert html remark - includes the DEVELOP_MODE - with call remark function:

	html::remark("this is some remark");

The above code translated to

	<!-- this is some remark -->

and can appends a sort javascript code to display any important message with call 'message' function

	html::message("this is some important message");

The above code translated to:

	<script text="javascript">alert('this is some important message');</script>

Remark: the message display row always appends the end of the html code




CHAPTER IV : The header

Building page with htmlxlite:

The htmlxlite can create a complex page header with previous parameter set.
Before begin to write any html code you must create a page header with call:

	html::display_header();

If you didn't set any parameter before, you can get the next:

	<!DOCTYPE html>
	 <html>
	  <header>
	  </header>

Because the 'body' tag isn't part of the header, therefore you must create it a 'body' call:

	html::body();

And finish our page to close any other opened tag:

	html::finish();

As a complete minimal page displays in htmlxlite the next:

	html::display_header();
	html::body();
	html::finish();

and the result is:

	<!DOCTYPE html>
	<html>
	 <header>
	 </header>
	 <body>
	 </body>
	</html>

Now we set some header parameter:

	html::set_header("charset=utf8","language=en","title=htmlxlite probe");
	html::display_header();

and the result is:

	<!DOCTYPE html>
	<html>
	 <head>
	  <meta http-equiv="Content-Type" content="text/html;charset=utf8" />
	  <meta http-equiv="language" content="en" />
	  <title>htmlxlite probe</title>
	 </head> 

you can look the htmlxlite extends your information to the html standards.
Now we add icon, javascript page, stylesheet page and keywords:

	html::set_header("charset=utf8","language=en","title=htmlxlite probe");
	html::set_header("js=default.js","css=default.css","icon=favicon.ico","keywords=html xml htmlxlite php helper");
	html::display_header();

Of couse, you can add all of header parameter in one row
The header parameters full list is:

   "charset=<charset>"
   "desctiption=<description>"
   "keywords=<keywords>"
   "refresh=<in sec>"
   "language=<lng code>"
   "nocache"
   "title=<title>"
   "css=<style sheet file>"
   "js=<javascipt file>"
   "link=<any other link>"
   "meta=<any other meta>"
      
Any other header parameter is not interpreted, except the <script> and <style> parameter.

Remark: I don't suggest to create any object from html class, because the access these functions is more harder
from any other classes as if use as namespace class.

Please see the full example source code for see how htmlxlite works