deploy/de-api.html - www.eclipse.org/birt - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 transitional//EN">
 <html>

 <head>
 <title>Deploying BIRT</title>
 <link rel="stylesheet" href="../style/compose.css" type="text/css"/>
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 </head>

 <body>

 <p class="head">Integrating BIRT</p>

 <p class="subhead">Using the Design Engine API</p>

 <h1>Concepts</h1>

 <p>A report design consist of three key concepts:</p>

 <dl class="break-list">
 <dt>Elements

 <dd>An &quot;object&quot; within the design such as the report itself, a data set, a style,
 a table, a label, etc.

 <dt>Property

 <dd>Properties customize an element. For example, a data set has a name and a
 query. A style has CSS-like style properties. A label has style properties and
 display text. Properties further divide into <i>property definitions</i>
 provided by BIRT's Report Object Model (ROM), and <i>property values</i> set by
 you as you create a report design.

 <dt>Slots

 <dd>A slot describes how elements assemble to form a report. A slot is a place
 where one element can contain other elements. For example, a report has slots
 for data sources, data sets, styles and the report body. A table has slots for
 the header, detail, footer and groups.
 </dl>

 <h1>API Services</h1>

 <p>The BIRT Design Engine API (DEAPI) provides a number of services to
 applications that work with report designs:</p>

 <ul>
   <li>Create report designs</li>
   <li>Read and write report design files</li>
   <li>Create and delete report elements</li>
   <li>Put report elements into a slot, or move them from slot to slot</li>
   <li>Get and set the value of parameters</li>
   <li>Retrieve metadata about report elements, properties and slots</li>
   <li>Support undo/redo of changes</li>
   <li>Perform semantic checks of report designs</li>
 </ul>

 <h1>DEAPI SDK</h1>

 <p>To create an application that uses the DEAPI, you'll need the design engine
 SDK.</p>

 <p>At present, you'll need to download the project source code and build the
 Javadoc yourself. In time, the Javadoc, and the model JARs, will be available as
 part of a BIRT download.</p>

 <ul>
   <li>See the
   <a href="../build/build_instr.html">BIRT build instructions</a> for
   information on how to access CVS and build the code. You only need to build
   the model and core projects.</li>
   <li>If you don't have access to CVS, you can also obtain the code from the web
   interface to the
 <a href="/birt/frameizer.php?page=http://dev.eclipse.org/viewcvs/index.cgi/source/org.eclipse.birt.report.model/?cvsroot=BIRT_Project">
 org.eclipse.birt.report.model</a> project.
 </ul>

 <p>This API is described in Javadoc in the <code>org.eclipse.birt.report.model.api</code>
 package within the <code>org.eclipse.birt.report.model project</code>. Read the package
 overview for general information about getting started with this API.</p>

 <h1>Example</h1>

 <p>The following code shows a simple example that creates a working report
 design. Here are the files you'll need:</p>

 <ul>
   <li><a href="DeDemo.java">Sample Java code</a></li>
   <li><a href="sample.rptdesign">Report produced by the example</a></li>
   <li><a target="_blank" href="sample.html">HTML output of the above report</a></li>
 </ul>

 <p>The first step is to create an instance of the design engine.</p>

 <pre class="code-block">SessionHandle session = DesignEngine.newSession( null );</pre>

 <p>Then, create a new report design.</p>

 <pre class="code-block">ReportDesignHandle design = session.createDesign( );</pre>
 </p>

 <p>Next, get the &quot;element factory&quot; that creates new elements within your design:</p>

 <pre class="code-block">ElementFactory factory = design.getElementFactory( );</pre>

 <p>Next, we add a page master that determines how the report will appear when
 printed:</p>

 <pre class="code-block">DesignElementHandle element = factory.newSimpleMasterPage( &quot;Page Master&quot; );
 design.getMasterPages( ).add( element );</pre>

 <p>Build S20050328 Note: BIRT will not open the report if you omit the master
 page.</p>

 <p>This design will contain a grid that contains an image and a label. Let's
 first create the grid and add it to the report's body slot.</p>

 <pre class="code-block">GridHandle grid = factory.newGridItem( null, 2 /* cols */, 1 /* row */ );
 design.getBody( ).add( grid );
 grid.setWidth( &quot;100%&quot; );</pre>

 <p>Next, create the image and add it to the first cell within the grid.</p>

 <pre class="code-block">RowHandle row = (RowHandle) grid.getRows( ).get( 0 );
 ImageHandle image = factory.newImage( null );
 CellHandle cell = (CellHandle) row.getCells( ).get( 0 );
 cell.getContent( ).add( image );
 image.setURI( &quot;http://www.eclipse.org/birt/tutorial/multichip-4.jpg&quot;
 );</pre>

 <p>Then, create a label and add it to the second cell.</p>

 <pre class="code-block">LabelHandle label = factory.newLabel( null );
 cell = (CellHandle) row.getCells( ).get( 1 );
 cell.getContent( ).add( label );
 label.setText( &quot;Hello, world!&quot; );</pre>

 <p>Finally, save and close the report design.</p>

 <pre class="code-block">design.saveAs( &quot;sample.rptdesign&quot; );
 design.close( );</pre>

 <p>You can now open the design within BIRT and preview it.</p>

 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 transitional//EN">
	<html>

	<head>
	<title>Deploying BIRT</title>
	<link rel="stylesheet" href="../style/compose.css" type="text/css"/>
	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
	</head>

	<body>

	<p class="head">Integrating BIRT</p>

	<p class="subhead">Using the Design Engine API</p>

	<h1>Concepts</h1>

	<p>A report design consist of three key concepts:</p>

	<dl class="break-list">
	<dt>Elements

	<dd>An "object" within the design such as the report itself, a data set, a style,
	a table, a label, etc.

	<dt>Property

	<dd>Properties customize an element. For example, a data set has a name and a
	query. A style has CSS-like style properties. A label has style properties and
	display text. Properties further divide into <i>property definitions</i>
	provided by BIRT's Report Object Model (ROM), and <i>property values</i> set by
	you as you create a report design.

	<dt>Slots

	<dd>A slot describes how elements assemble to form a report. A slot is a place
	where one element can contain other elements. For example, a report has slots
	for data sources, data sets, styles and the report body. A table has slots for
	the header, detail, footer and groups.
	</dl>

	<h1>API Services</h1>

	<p>The BIRT Design Engine API (DEAPI) provides a number of services to
	applications that work with report designs:</p>

	<ul>
	<li>Create report designs</li>
	<li>Read and write report design files</li>
	<li>Create and delete report elements</li>
	<li>Put report elements into a slot, or move them from slot to slot</li>
	<li>Get and set the value of parameters</li>
	<li>Retrieve metadata about report elements, properties and slots</li>
	<li>Support undo/redo of changes</li>
	<li>Perform semantic checks of report designs</li>
	</ul>

	<h1>DEAPI SDK</h1>

	<p>To create an application that uses the DEAPI, you'll need the design engine
	SDK.</p>

	<p>At present, you'll need to download the project source code and build the
	Javadoc yourself. In time, the Javadoc, and the model JARs, will be available as
	part of a BIRT download.</p>

	<ul>
	<li>See the
	<a href="../build/build_instr.html">BIRT build instructions</a> for
	information on how to access CVS and build the code. You only need to build
	the model and core projects.</li>
	<li>If you don't have access to CVS, you can also obtain the code from the web
	interface to the
	<a href="/birt/frameizer.php?page=http://dev.eclipse.org/viewcvs/index.cgi/source/org.eclipse.birt.report.model/?cvsroot=BIRT_Project">
	org.eclipse.birt.report.model</a> project.
	</ul>

	<p>This API is described in Javadoc in the <code>org.eclipse.birt.report.model.api</code>
	package within the <code>org.eclipse.birt.report.model project</code>. Read the package
	overview for general information about getting started with this API.</p>

	<h1>Example</h1>

	<p>The following code shows a simple example that creates a working report
	design. Here are the files you'll need:</p>

	<ul>
	<li><a href="DeDemo.java">Sample Java code</a></li>
	<li><a href="sample.rptdesign">Report produced by the example</a></li>
	<li><a target="_blank" href="sample.html">HTML output of the above report</a></li>
	</ul>

	<p>The first step is to create an instance of the design engine.</p>

	<pre class="code-block">SessionHandle session = DesignEngine.newSession( null );</pre>

	<p>Then, create a new report design.</p>

	<pre class="code-block">ReportDesignHandle design = session.createDesign( );</pre>
	</p>

	<p>Next, get the "element factory" that creates new elements within your design:</p>

	<pre class="code-block">ElementFactory factory = design.getElementFactory( );</pre>

	<p>Next, we add a page master that determines how the report will appear when
	printed:</p>

	<pre class="code-block">DesignElementHandle element = factory.newSimpleMasterPage( "Page Master" );
	design.getMasterPages( ).add( element );</pre>

	<p>Build S20050328 Note: BIRT will not open the report if you omit the master
	page.</p>

	<p>This design will contain a grid that contains an image and a label. Let's
	first create the grid and add it to the report's body slot.</p>

	<pre class="code-block">GridHandle grid = factory.newGridItem( null, 2 /* cols /, 1 / row */ );
	design.getBody( ).add( grid );
	grid.setWidth( "100%" );</pre>

	<p>Next, create the image and add it to the first cell within the grid.</p>

	<pre class="code-block">RowHandle row = (RowHandle) grid.getRows( ).get( 0 );
	ImageHandle image = factory.newImage( null );
	CellHandle cell = (CellHandle) row.getCells( ).get( 0 );
	cell.getContent( ).add( image );
	image.setURI( "http://www.eclipse.org/birt/tutorial/multichip-4.jpg"
	);</pre>

	<p>Then, create a label and add it to the second cell.</p>

	<pre class="code-block">LabelHandle label = factory.newLabel( null );
	cell = (CellHandle) row.getCells( ).get( 1 );
	cell.getContent( ).add( label );
	label.setText( "Hello, world!" );</pre>

	<p>Finally, save and close the report design.</p>

	<pre class="code-block">design.saveAs( "sample.rptdesign" );
	design.close( );</pre>

	<p>You can now open the design within BIRT and preview it.</p>

	</body>
	</html>