====== Render ======
Rendering framework is an extension of [[products:convert:start|converting framework]]. It defines several rendering interfaces, their implementations and also features documentation/report generator.

===== License =====
[[wp>LGPL]]
===== Version =====
[[http://www.hammurapi.com/mantis/changelog_page.php?project_id=6|1.3.0]]

===== Requirements =====
[[http://java.sun.com/javase/6/|Java 6]]
===== Resources and downloads =====
  * [[http://www.hammurapi.com/products/render/com.hammurapi.render.zip|Jar files]]
  * [[http://www.hammurapi.com/products/render/com.hammurapi.render-src.zip|Sources]], includes Javadoc and jar files.
  * [[http://www.hammurapi.com/products/render/doc/api/index.html|Javadoc]]
  * [[http://www.hammurapi.com/bb/viewforum.php?f=8|Discussion forum]]
  * [[http://www.hammurapi.com/mantis/|Issue tracking]]
  * [[http://www.hammurapi.com/mantis/roadmap_page.php?project_id=6|Roadmap]]



===== Rendering =====
==== Example ====
Let's start with an example:
<code java>
OutputStreamRenderer renderer = ConvertingService.convert("33", OutputStreamRenderer.class);
renderer.render(System.out, null, Context.INSTANCE, null, null, null);
</code>
Console output:
  Type: class java.lang.String <P/>
  Value: 33
This output was produced with the following template:
<code html>
Type: <%=toRender.getClass()%> <P/>
Value: <%=toRender%>
</code>
The template was found in ''com.hammurapi.render.jar'' file in ''META-INF/com.hammurapi.render/java/lang/Object.jxp''.
==== How it works ====
  - ''[[http://www.hammurapi.com/products/convert/doc/api/com/hammurapi/convert/ConvertingService.html|ConvertingService]]'' searches for a converter from ''java.lang.String'' to ''[[http://www.hammurapi.com/products/render/doc/api/com/hammurapi/render/OutputStreamRenderer.html|OutputStreamRenderer]]'' by traversing source object (String) class hierarchy.
  - It finds ''[[http://www.hammurapi.com/products/render/doc/api/com/hammurapi/render/OutputStreamRendererAtomicConverter.html|OutputStreamRendererAtomicConverter]]'' at ''java.lang.Object'' level. This converter uses ''[[http://www.hammurapi.com/products/render/doc/api/com/hammurapi/render/JxpRenderer.html|JxpRenderer]]'' for rendering.
  - JxpRenderer traverses source object class hierarchy and looks for a template resource with class name and .jxp extension. 
    - JxpRenderer looks up JxpPageSource service and finds ''[[http://www.hammurapi.com/products/render/doc/api/com/hammurapi/render/DefaultRenderingPageSource.html|DefaultRenderingPageSource]]'' 
    - DefaultPageSource searches for pages in classloader under ''/META-INF/com.hammurapi.render''. 
  - JxpRenderer finds ''java/lang/Object.jxp'' template in the page source.
  - JxpRenderer evaluates the template using [[http://jxp.sourceforge.net/|JXP]] template engine, and sends results to System.out
==== Customization points ====
This section lists different ways to customize the framework.
  * Define type-specific renderer implementation. Register converter from the source type to the renderer as described in the [[products:convert:start|Convert]] framework documentation.
  * When using JxpRenderer, define type-specific templates.
  * Define different page source, e.g. page source loading templates from URL. For this either modify service registration in ''com.hammurapi.render.jar'' or place your own jar with a new registration before ''com.hammurapi.render.jar'' in classpath.
  * Set ''com.hammurapi.render.DefaultRenderingPageSource:prefix'' property to load pages from a different location. Default location is ''/META-INF/com.hammurapi.render''.
===== Report generation =====
The framework features ''[[http://www.hammurapi.com/products/render/doc/api/com/hammurapi/render/ReportGenerator.html|ReportGenerator]]'' class. This class is used to create report/documentation generators which have structure as shown on the picture below.

{{:products:render:reportstructure.png|}}

  * **Outline frame** - displays top level structure of the object model being reported/documented.
  * **Details frame** - displays detailed view of the current model component.
  * **Contents frame** - displays structure of the current model component.

ReportGenerator creates index.html file, necessary scripts, images, and style sheets. Then it uses other classes in the rendering framework to generate outline view, detail pages and contents pages. 

Report generator uses ''outline'' template profile to generate outline items, ''contents'' profile to generate contents files, and no profile for details. E.g. for class MyClass JXP templates shall have the following names:
  * Details - MyClass.jxp
  * Outline - MyClass!outline.jxp
  * Contents - MyClass!contents.jxp

The outline view uses [[http://www.dhtmlgoodies.com/index.html?whichScript=folder_tree_static|static folder tree script]] from [[http://www.dhtmlgoodies.com]]. When outline is generated, the framework generates details and contents views automatically.

The details frame is loaded when a node in the outline view is clicked. The contents frame is loaded by ''onLoad'' event of the details frame. By convention, content's file name shall be the same as details file name with ''_contents'' postfix before the extension. E.g. if details file name is ''myObject.html'', then contents file name shall be ''myObject_contents.html''.
==== Sample output ====
[[http://www.hammurapi.com/products/Config/doc/model/|Configurator model]] was generated by [[products:model_documenter:start]], which is based on the Render framework.

==== Outline items ====
This section shows how to create templates to render outline items. The code below is a fragment from the Model Documenter.
<code html>
<li class="<%=renderHelper.getImageName(toRender)%>">
	<a 
		href="e<%=renderHelper.getId(toRender)%>.html" 
		target="detailsFrame" 
		id="e<%=renderHelper.getId(toRender)%>">
		
		<%=toRender.getName()%>
	</a>
	
	<% if (renderHelper.hasChildren(toRender)) { %>
		<ul>
			<% 
				for (EPackage cpkg: renderHelper.sort(toRender.getESubpackages())) {
					renderHelper.renderOutline(cpkg, jxp_writer); 
			   	}
			%>
			
		</ul>
	<% } %>
</li>
</code>
<li> and <a> tags render individual tree node. If the node has sub-nodes, then <ul> is rendered and outline for sub-items is rendered using ''renderHelper.renderOutline()'' method.
==== Contents ====
This section shows how to construct tree view for the contents frame. The contents tree can use outline templates for sub-items.
<code html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
	<title>Package contents</title>
	<link rel="stylesheet" href="css/folder-tree-static.css" type="text/css">
	<link rel="stylesheet" href="css/context-menu.css" type="text/css">
	<script type="text/javascript" src="js/ajax.js"></script>
	<script type="text/javascript" src="js/folder-tree-static.js"></script>
</head>
<body>
<% 
import org.eclipse.emf.ecore.EPackage;
import org.eclipse.emf.ecore.EClassifier;
%>
	<ul id="dhtmlgoodies_tree" class="dhtmlgoodies_tree">
	<% 
		for (EClassifier classifier: renderHelper.sort(toRender.getEClassifiers())) {
			renderHelper.renderOutline(classifier, jxp_writer);
		}
	%>
	</ul>
	<a href="#" onclick="expandAll('dhtmlgoodies_tree');return false">Expand all</a>
	<a href="#" onclick="collapseAll('dhtmlgoodies_tree');return false">Collapse all</a>
</body>
</html>
</code>
===== Use =====
Report generator is used by [[products:model_documenter:start]] and documentation generators for other products.