This is the Yahjf 0.5 Readme.txt

Yahjf 0.5 copyright Nicolas Chartoire 2008-2011 available under the terms of the BSD License ; refer to Copying.txt that you must have received with this software package. 

Download Yahjf at : http://sourceforge.net/projects/yahjf/

Donate to Yahjf at : http://sourceforge.net/projects/yahjf/ ; Donage to Nicolas Chartoire alias Shangri-l, main and for now only developper at : http://flattr.com/thing/277852/Yahjf or just send money trough Paypal to shg-l@hotmail.fr (send an email before to see if the address is still valid - copy and paste to avoid errors)

Why use Yahjf ? 

It's a simple framework to generate markup languages such as HTML from Java. Store your objects representing your HTML code in session, application or (since 0.4) or on disk, and modify them programmatically. You can subclass Yahjf classes to integrate dynamic content. You can navigate in the Yahjf HTML objects hierarchy that are stored in a root HTMLElement object, and modify their properties. 

What's new in version 0.5 ? 

You can, naturally, create just any tag by using the HTMLElement class. But there's prebuild classes for common tags, including some new. The actual list is : 

Html Img Input P Table Td Tr A Audio Div Form 

Also, there's now a few prebuild attributes (or in Yahjf slang, parameters) ; naturally you can set any parameter you want using the HTMLParameter class ; but you can also use the following one to save a line of code or two : 

HrefParameter.java
IdParameter.java
SrcParameter.java
StyleParameter.java

For all of them, the constructor takes a single argument, which is the value of the parameter. 

If you wish to submit more classes for more tags or more attributes you are welcome. 

Please note that there's still many, many bugs in the HTMLParser and Html2Yahf side utilities. These bugs does not affect the core of the framework, but for the utilities, they may work, or not, depending on the HTML input that is provided. They are not recommended for daily usage. If someone whish to rewrite them, as an example using DOM or SAX, well, it would be nice. 




Here's now the old README, slightly edited but some informations may be not up to date

Note to Yahjf-toolkit-0.1 users

As of version 0.2, the HtmlTag no longer has built-in head, body and title element. This mean that Yahjf-toolkit-0.1 won't work with Yahjf-0.2. Please upgrade to Yahjf-toolkit-0.2

Thank you for downloading Yahjf. 

Installing Yahjf. 

Download and install Tomcat. 

Windows users:
In the system tray icon, right-click on the Tomcat icon. Click on Configure, then click on Java. In the 'Java Classpath' textfield, add a semicolon followed by the path where you unpacked Yahjf. For example add ';c:\YAHJF' if you unpacked Yahjf in C:\YAHJF.

Linux users:
Copy the <Yahjf installation dir>/org directory into the /common/classes directory of Tomcat. 

Running Yahjf

In the Tomcat Webapps\ROOT directory, create a new directory called yahjf-examples. 
In this directory, create a new index.jsp file. 

Edit the file as follow :

---beginning of index.jsp---
<%@page import="org.yahjf.*"%>
<%=new HtmlTag().getHTML()%>
---end of index.jsp---

Point your web browser to http://localhost:8080/yahjf-examples . It should display a blank page. 

In Yahjf, HTML tag name and parameters are always in minuscules.  

Let's add a title to our web page :

---beginning of index.jsp---
<%@page import="org.yahjf.*"%>
<%
HtmlTag h=new HtmlTag();
HTMLElement title=new HTMLElement();
title.setName("title");
HTMLElement head=new HTMLElement();
head.setName("head");
head.addHTMLElement(title);
h.addHTMLElement(head);
HTMLElement body=new HTMLElement();
body.setName("body");
h.addHTMLElement(body);
h.getHTMLElementByName("head").getHTMLElementByName("title").addValue("Our first Yahjf page");
%>
<%=h.getHTML()%>
---end of index.jsp---

It should now display a page with a title. 

We'll now add a PTag element to our page : 

---beginning of index.jsp---
<%@page import="org.yahjf.*"%>
<%
HtmlTag h=new HtmlTag();
HTMLElement title=new HTMLElement();
title.setName("title");
HTMLElement head=new HTMLElement();
head.setName("head");
head.addHTMLElement(title);
h.addHTMLElement(head);
HTMLElement body=new HTMLElement();
body.setName("body");
h.addHTMLElement(body);
h.getHTMLElementByName("head").getHTMLElementByName("title").addValue("Our first Yahjf page");
PTag p=new PTag();
p.addValue("A paragraph");
h.getHTMLElementByName("body").addHTMLElement(p);
%>
<%=h.getHTML()%>
---end of index.jsp---

Yahjf also offers FormTag, DivTag, ImgTag, InputTag, TableTag, AudioTag, TdTag, TrTag and ATag. But what if you need a tag that does not exist ? With Yahjf you can create tags on the fly. Here comes an examples with the <table>, <td> and <tr> tags, which exists, but this is only an example : 

---beginning of index.jsp---
<%@page import="org.yahjf.*"%>
<%
HtmlTag h=new HtmlTag();
HTMLElement title=new HTMLElement();
title.setName("title");
HTMLElement head=new HTMLElement();
head.setName("head");
head.addHTMLElement(title);
h.addHTMLElement(head);
HTMLElement body=new HTMLElement();
body.setName("body");
h.addHTMLElement(body);
h.getHTMLElementByName("head").getHTMLElementByName("title").addValue("Our first Yahjf page");
PTag p=new PTag();
p.addValue("A paragraph");
h.getHTMLElementByName("body").addHTMLElement(p);

HTMLElement table=new HTMLElement();
table.setName("table");
HTMLElement tr1=new HTMLElement();
tr1.setName("tr");
table.addHTMLElement(tr1);
HTMLElement tr2=new HTMLElement();
tr2.setName("tr");
table.addHTMLElement(tr2);
HTMLElement td1=new HTMLElement();
td1.setName("td");
tr1.addHTMLElement(td1);
HTMLElement td2=new HTMLElement();
td2.setName("td");
tr2.addHTMLElement(td2);
PTag p2=new PTag();
p2.addValue("First cell");
td1.addHTMLElement(p2);
PTag p3=new PTag();
p3.addValue("Second cell");
td2.addHTMLElement(p3);
h.getHTMLElementByName("body").addHTMLElement(table);


%>
<%=h.getHTML()%>
---end of index.jsp---

Using HTMLParameters :

you can easily set extra Html parameters with the HTMLParameter object :

---beginning of index.jsp---
<%@page import="org.yahjf.*"%>
<%
HtmlTag h=new HtmlTag();
HTMLElement title=new HTMLElement();
title.setName("title");
HTMLElement head=new HTMLElement();
head.setName("head");
head.addHTMLElement(title);
h.addHTMLElement(head);
HTMLElement body=new HTMLElement();
body.setName("body");
h.addHTMLElement(body);
h.getHTMLElementByName("head").getHTMLElementByName("title").addValue("Our first Yahjf page");
ATag a=new ATag();
a.addValue("A link");
a.addParameter(new HTMLParameter("href","http://www.yahoo.com/"));
h.getHTMLElementByName("body").addHTMLElement(a);

%>
<%=h.getHTML()%>
---end of index.jsp---


Building a Yahjf application

For the rest of this section, we'll assume you are running Windows. 
We will make a small application that displays the content of a database. 

We will not close connexions and so on, it's only a quick example. 

We will use a very simple database with only one table, clients, and two fields, client_name  and client_description. 

Create a new directory in C:, named "MyProject".
In this directory, create another directory named "com".
In the "com" directory, create another directory named "myproject". 
In the "myproject" directory, create a file named "DbViewer.java". 

Copy and paste the following :

---begining of DbViewer.java---
package com.myproject;
import org.yahjf.*;
import java.sql.*;
public class DbViewer extends DivTag {
public DbViewer (Statement st,int offset){
	try{
	ResultSet rs;
	rs=st.executeQuery("SELECT client_name, client_description FROM clients");
	for (int i=0;i<=offset&&!rs.isAfterLast();i++){
		rs.next();
	}
	HTMLElement table=new HTMLElement();
	table.setName("table");
	HTMLElement tr1=new HTMLElement();
	tr1.setName("tr");
	table.addHTMLElement(tr1);
	HTMLElement tr2=new HTMLElement();
	tr2.setName("tr");
	table.addHTMLElement(tr2);
	HTMLElement tr3=new HTMLElement();
	tr3.setName("tr");
	table.addHTMLElement(tr3);
	HTMLElement td1=new HTMLElement();
	td1.setName("td");
	tr1.addHTMLElement(td1);
	HTMLElement td2=new HTMLElement();
	td2.setName("td");
	tr2.addHTMLElement(td2);
	HTMLElement td3=new HTMLElement();
	td3.setName("td");
	tr3.addHTMLElement(td3);
	PTag p2=new PTag();
	p2.addValue(rs.getString(1));
	td1.addHTMLElement(p2);
	PTag p3=new PTag();
	p3.addValue(rs.getString(2));
	td2.addHTMLElement(p3);
	FormTag f1=new FormTag();
	InputTag i1=new InputTag();
	i1.addParameter(new HTMLParameter("type","hidden"));
	i1.addParameter(new HTMLParameter("name","button"));
	i1.addParameter(new HTMLParameter("value","previous"));
	f1.addHTMLElement(i1);
	InputTag i2=new InputTag();
	i2.addParameter(new HTMLParameter("type","submit"));
	i2.addParameter(new HTMLParameter("value", "Previous"));
	f1.addHTMLElement(i2);
	td3.addHTMLElement(f1);
	FormTag f2=new FormTag();
	InputTag i3=new InputTag();
	i3.addParameter(new HTMLParameter("type","hidden"));
	i3.addParameter(new HTMLParameter("name","button"));
	i3.addParameter(new HTMLParameter("value","next"));
	f2.addHTMLElement(i3);
	InputTag i4=new InputTag();
	i4.addParameter(new HTMLParameter("type","submit"));
	i4.addParameter(new HTMLParameter("value", "Next"));
	f2.addHTMLElement(i4);
	td3.addHTMLElement(f2);
	addHTMLElement(table);
	}catch (SQLException e){
	PTag p=new PTag();
	p.addValue("SQLException ! ");
	addHTMLElement(p);
	}
}

}
---end of DbViewer.java---

Compile DbViewer.java :
In the start menu, click on "Execute". Type "cmd", click on "Execute". 
Enter the following commands : 

set CLASSPATH=c:<the directory in wich you unpacked Yahjf>;c:\MyProject
cd c:\MyProject\com\myproject
c:\Sun\SDK\jdk\bin\javac.exe DbViewer.java

In your Tomcat webapps\ROOT directory, create a new directory named MyProject.
In this directory, create a file named index.jsp
Copy and paste the following :

---begining of index.jsp---
<%@page import="org.yahjf.*"%>
<%@page import="com.myproject.*"%>
<%@page import="java.sql.*"%>
<%
int index=0;
if (request.getSession(true).getAttribute("offset" ) == null) {
	request.getSession(true).setAttribute("offset", new Integer(index));
}
else
{
	index=(Integer)request.getSession(true).getAttribute("offset" );
}
String command;
command=request.getParameter("button");
if (command!=null){
	if (command.equals("previous")){
		if (index>0){index--;}
	}else if (command.equals("next")){
		index++;
	}
	request.getSession(true).setAttribute("offset", new Integer(index));	
}
HtmlTag h=new HtmlTag();
HTMLElement title=new HTMLElement();
title.setName("title");
HTMLElement head=new HTMLElement();
head.setName("head");
head.addHTMLElement(title);
h.addHTMLElement(head);
HTMLElement body=new HTMLElement();
body.setName("body");
h.addHTMLElement(body);
h.getHTMLElementByName("head").getHTMLElementByName("title").addValue("DbViewer");

try {
	//Here we load a postgresql driver and connect to a base called mybase with username postgres and password postgres. Change this according to your configuration
	Class.forName("org.postgresql.Driver");
	String dbURL = "jdbc:postgresql://127.0.0.1/mybase";
	Connection dbCon;
	Statement stmt;
        dbCon = DriverManager.getConnection( dbURL, "postgres" , "postgres" );
	stmt = dbCon.createStatement();
	DbViewer d=new DbViewer(stmt, index);
	h.getHTMLElementByName("body").addHTMLElement(d);


   }
catch (SQLException e)
{
PTag p=new PTag();
p.addValue("SQLException !");
h.getHTMLElementByName("body").addHTMLElement(p);
}
%>
<%=h.getHTML()%>
---end of index.jsp---

In the system tray icon, right-click on the Tomcat icon. Click on Configure, then click on Java. In the 'Java Classpath' textfield, add ';c:\MyProject'.

Point your web browser to http://localhost/MyProject/index.jsp . It should display your database records. If you move after the last record a SQLException will be caught. We should take care of this, and put the processing in a method that returns the actual index to the jsp file, but this goes beyond the scope of this Readme file. 

Mixing Html and text :

For now, we had Html tags that contained a list of Html tags, then text. What if you want to mix text and Html like this :

<HTML>
<HEAD>
<TITLE>
a page
</TITLE>
</HEAD>
<BODY>
<P>
On the web you have many useful sites. <A HREF="http://www.google.com">Google</A> is a web search engine.
</P>
</BODY>
</HTML> 

You can use the addValue() method of HTMLElement to add either text or HTMLElement to the value (the text value) of an HTMLElement :

<%@page import="org.yahjf.*"%>
<%
HtmlTag h=new HtmlTag();
HTMLElement title=new HTMLElement();
title.setName("title");
HTMLElement head=new HTMLElement();
head.setName("head");
head.addHTMLElement(title);
h.addHTMLElement(head);
HTMLElement body=new HTMLElement();
body.setName("body");
h.addHTMLElement(body);
h.getHTMLElementByName("head").getHTMLElementByName("title").addValue("Mixing text and Html");
PTag p=new PTag();
p.addValue("On the web you have many useful sites. ");
ATag a=new ATag();
a.addValue("Google");
a.addParameter(new HTMLParameter("href","http://www.google.com/"));
p.addValue(a);
p.addValue(" is a web search engine.");
h.getHTMLElementByName("body").addHTMLElement(p);
%>
<%=h.getHTML()%>

Parsing HTML (this feature is full of bugs and should, in fact, not be used)

Yahjf comes with a tool to built Yahjf objects directly from an Html stream. Here comes an example of using HTMLParser:

---beginning of HTMLParserTest.java---
public class HTMLParserTest{
public static void main(String args[]){
	String html="<html><head><title>My title</title><p align=\"center\" id=\"apa\"></p>\n<p align=\"center\">This is a<A HREF=\"http://www.yahoo.com\">mixed<br> content</A></p></head></html>";
	System.out.println("parser created");
	HTMLParser h=new HTMLParser(html);
	System.out.println("HTML generation");	
	HTMLElement he=h.getHTMLElement();
	System.out.println(he.getHTML());
	System.out.println("over");
}

}
---end of HTMLParserTest.java---

The HTMLParser will ignore DOCTYPE and Meta tags. Extra carriage return may cause HTMLElement to be stored in the Value of the parent HTMLElement instead of the Content. This can be viewed as a feature, as it will preserve pre-formated text, but on the other hand this is a bug because HTMLElement that aren't in the mixed content of an HTMLElement should go in its Content. Please note that Html parsing is an experimental feature. I'd appreciate any feedback about the HTMLParser. 

There's also an HTML2Yahjf utility to convert HTML file to Yahjf source code using the parser. 

Misc. Q&A :

Why a getHTMLElementByHTMLParameter in the HTMLElement object ?

You can set an id parameter to your HTMLElement in your java file. This allows you to retrieve this element in your jsp file. 

I cannot subclass DivTag because I already inherits from another class. 

In a few word : implement the HTMLContent interface, create a new DivTag and add content within, implement getHTML() and return the return of your DivTag's getHTML(). 

User Feedback

If you use Yahjf please let me know. 

Authors

Yahjf (c) 2008-2011 Nicolas Chartoire (shg-l@hotmail.fr)