[doc] First version of basic tutorial to create a new report on NavalPlan.

doc/src/technical/howto-create-a-new-report-in-navalplan.rst

@@ -0,0 +1,446 @@
+.. sectnum::
+
+How To Create A New Report In NavalPlan
+=======================================
+
+.. contents::
+
+NavalPlan uses **JasperReports** [1]_ to create reports in the application. This
+document tries to explain how to create a new report in NavalPlan.
+
+During this tutorial you are going to create a report that will show the list of
+resources in NavalPlan.
+
+
+Add entry on NavalPlan menu
+---------------------------
+
+First of all, you are going to add a new entry on *Reports* menu in NavalPlan,
+this option will link to a new ``.zul`` file inside
+``navalplanner-webapp/src/main/webapp/reports/`` that will be the basic
+interface for users before generate the report.
+
+Steps:
+
+* Modify ``CustomMenuController.java`` to add a new ``subItem`` inside the
+  ``topItem`` *Reports*::
+
+    subItem(_("Resources List"),
+        "/reports/resourcesListReport.zul",
+        "15-informes.html")
+
+You will see the new entry if you run NavalPlan, but the link is not going to
+work as ``.zul`` page still does not exist.
+
+
+Create basic HTML interface
+---------------------------
+
+You need an interface were users could specify some parameters (if needed) for
+the report and then generate the expected result. This interface will be
+linked from the menu entry added before. For the moment, you are going to create
+a very basic interface, copying some parts from other reports.
+
+Steps:
+
+* Create a new file ``resourcesListReport.zul`` in
+  ``navalplanner-webapp/src/main/webapp/reports/``. With the following content:
+
+::
+
+ <!--
+     This file is part of NavalPlan
+
+     Copyright (C) 2011 Igalia
+
+     This program is free software: you can redistribute it and/or modify
+     it under the terms of the GNU Affero General Public License as published by
+     the Free Software Foundation, either version 3 of the License, or
+     (at your option) any later version.
+
+     This program is distributed in the hope that it will be useful,
+     but WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+     GNU Affero General Public License for more details.
+
+     You should have received a copy of the GNU Affero General Public License
+     along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ -->
+
+ <?page title="${i18n:_('NavalPlan: Resources List')}" id="reports"?>
+ <?init class="org.zkoss.zkplus.databind.AnnotateDataBinderInit" ?>
+ <?init class="org.zkoss.zk.ui.util.Composition" arg0="/common/layout/template.zul"?>
+
+ <?link rel="stylesheet" type="text/css" href="/common/css/navalplan.css"?>
+ <?link rel="stylesheet" type="text/css" href="/common/css/navalplan_zk.css"?>
+
+ <?variable-resolver class="org.zkoss.zkplus.spring.DelegatingVariableResolver"?>
+
+ <?component name="combobox_output_format" macroURI="combobox_output_format.zul"
+     class="org.navalplanner.web.reports.ComboboxOutputFormat" ?>
+
+ <?component name="extendedjasperreport"
+     class="org.navalplanner.web.common.components.ExtendedJasperreport"
+     extends="jasperreport" ?>
+
+ <zk id="resourcesList" xmlns:n="http://www.zkoss.org/2005/zk/native">
+
+     <window self="@{define(content)}"
+         apply="org.navalplanner.web.reports.ResourcesListController"
+         title="${i18n:_('Resources List')}"
+         border="normal" >
+
+         <!-- Select output format -->
+         <panel title="${i18n:_('Format')}" border="normal"
+             style="overflow:auto">
+             <panelchildren>
+                 <grid width="700px">
+                     <columns>
+                         <column width="200px" />
+                         <column />
+                     </columns>
+                     <rows>
+                         <row>
+                             <label value="${i18n:_('Output format:')}" />
+                             <combobox_output_format id="outputFormat" />
+                         </row>
+                     </rows>
+                 </grid>
+             </panelchildren>
+         </panel>
+
+         <hbox style="display: none" id="URItext">
+             <label value="${i18n:_('Click on ')}" />
+             <toolbarbutton id="URIlink" class="z-label" zclass="z-label"
+                     label="${i18n:_('direct link')}" />
+             <label value="${i18n:_(' to go to output directly')}" />
+         </hbox>
+
+         <separator spacing="10px" orient="horizontal" />
+
+         <button label="Show" onClick="controller.showReport(report)" />
+
+         <extendedjasperreport style="display: none" id="report" />
+
+     </window>
+
+ </zk>
+
+This will create a basic interface for report with a combo to select the desired
+output format for it and a button to generate the report. As we can see it uses
+``resourcesListController`` that will be created in the next point.
+
+
+Create a controller for new report
+----------------------------------
+
+As you can see previous ``.zul`` file defined uses a controller that will be in
+charge to manage users interaction with report interface and call the proper
+methods to generate the report itself and show it to the user.
+
+There is already a controller called ``NavalplannerReportController`` which
+implements most of the stuff needed for report controllers. So, controllers for
+new reports are going to extend this class and re-implement some methods.
+
+Steps:
+
+* Create a new file ``ResourcesListController.java`` in
+  ``navalplanner-webapp/src/main/java/org/navalplanner/web/reports/`` with the
+  following content:
+
+::
+
+ /*
+  * This file is part of NavalPlan
+  *
+  * Copyright (C) 2011 Igalia, S.L.
+  *
+  * This program is free software: you can redistribute it and/or modify
+  * it under the terms of the GNU Affero General Public License as published by
+  * the Free Software Foundation, either version 3 of the License, or
+  * (at your option) any later version.
+  *
+  * This program is distributed in the hope that it will be useful,
+  * but WITHOUT ANY WARRANTY; without even the implied warranty of
+  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  * GNU Affero General Public License for more details.
+  *
+  * You should have received a copy of the GNU Affero General Public License
+  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+  */
+
+ package org.navalplanner.web.reports;
+
+ import net.sf.jasperreports.engine.JRDataSource;
+ import net.sf.jasperreports.engine.JREmptyDataSource;
+
+ import org.zkoss.zk.ui.Component;
+
+ /**
+  * Controller for UI operations of Resources List report.
+  *
+  * @author Manuel Rego Casasnovas <mrego@igalia.com>
+  */
+ public class ResourcesListController extends NavalplannerReportController {
+
+     private static final String REPORT_NAME = "resourcesListReport";
+
+     @Override
+     public void doAfterCompose(Component comp) throws Exception {
+         super.doAfterCompose(comp);
+         comp.setVariable("controller", this, true);
+     }
+
+     @Override
+     protected String getReportName() {
+         return REPORT_NAME;
+     }
+
+     @Override
+     protected JRDataSource getDataSource() {
+         return new JREmptyDataSource();
+     }
+
+ }
+
+Now if you run NavalPlan and access to the new menu entry you will see the
+simple form allowing you to choose the output format for the report and also the
+button to show it (that will not work yet).
+
+
+Create a DTO
+------------
+
+As usually reports show information extracted from database but with some
+specific modifications, for example, merging data from different database
+tables; you will need to define a DTO (Data Transfer Object) with the fields
+that you want to show in the report.
+
+In your case the DTO is pretty simple, you will show for each resource: code and
+name.
+
+Steps:
+
+* Create a new file ``ResourcesListDTO.java`` in
+  ``navalplanner-business/src/main/java/org/navalplanner/business/reports/dtos/``
+  with the following content:
+
+::
+
+ /*
+  * This file is part of NavalPlan
+  *
+  * Copyright (C) 2011 Igalia, S.L.
+  *
+  * This program is free software: you can redistribute it and/or modify
+  * it under the terms of the GNU Affero General Public License as published by
+  * the Free Software Foundation, either version 3 of the License, or
+  * (at your option) any later version.
+  *
+  * This program is distributed in the hope that it will be useful,
+  * but WITHOUT ANY WARRANTY; without even the implied warranty of
+  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  * GNU Affero General Public License for more details.
+  *
+  * You should have received a copy of the GNU Affero General Public License
+  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+  */
+
+ package org.navalplanner.business.reports.dtos;
+
+ /**
+  * DTO for Resources List report data.
+  *
+  * @author Manuel Rego Casasnovas <mrego@igalia.com>
+  */
+ public class ResourcesListDTO {
+
+     private String code;
+
+     private String name;
+
+     public ResourcesListDTO(String code, String name) {
+         this.code = code;
+         this.name = name;
+     }
+
+     public String getCode() {
+         return code;
+     }
+
+     public String getName() {
+         return name;
+     }
+
+ }
+
+A list of DTOs will be passed to JasperReports in order to generate the report
+with the data.
+
+
+Define report layout (iReport)
+------------------------------
+
+Now that you know which data you are going to show in the report (check DTOs
+attributes) you should define the JasperReports format with a XML.
+
+You need to install **iReport** [2]_, it is a tool used to define and design
+report layouts, which provides a visual interface to define ``.jrxml`` file.
+
+Steps:
+
+* Download iReport **3.7.0** (``tar.gz``) from SourceForge.net:
+  https://sourceforge.net/projects/ireport/files/iReport/
+
+* Uncompress file::
+
+    tar -xvzf iReport-3.7.0.tar.gz
+
+* Launch iReport::
+
+    cd iReport-3.7.0/
+    ./bin/ireport
+
+* Open some existent NavalPlan report (e.g.
+  ``hoursWorkedPerWorkerInAMonthReport.jrxml``) under
+  ``navalplanner-webapp/src/main/jasper`` to use as template to keep the same
+  layout and save it with the name of the new report
+  ``resourcesListReport.jrxml`` in the same folder.
+
+  This will allow us to keep coherence between reports in regard to design,
+  header, footer, etc.
+
+* Set report name to ``resourcesList``.
+
+* Set resource bundle to ``resourcesList``.
+
+* Remove following parameters:
+
+  * ``startingDate``
+  * ``endingDate``
+  * ``showNote``
+
+* Remove all the fields and add the following:
+
+  * Name: ``code``, class: ``java.lang.String``
+  * Name: ``name``, class: ``java.lang.String``
+
+* Remove following variables:
+
+  * ``sumHoursPerDay``
+  * ``sumHoursPerWorker``
+
+* Remove following elements in *Title* band:
+
+  * ``$R{date.start}``
+  * ``$R{date.end}``
+  * ``$P{startingDate}``
+  * ``$P{endingDate}``
+  * ``$R{note1}``
+  * Label: ``*``
+
+* Remove group *Worker group Group Header 1*.
+
+* Remove group *Date group Group Header 1*.
+
+* Remove columns in *Detail 1* band in order to leave only 2 columns:
+  ``$F{code}`` and ``$F{name}``.
+
+Now you have defined a very basic report layout using some common elements
+with other NavalPlan reports like header and footer. The result in iReport would
+be something similar to the screenshot.
+
+.. figure:: ireport-resources-list-report.png
+   :alt: iRerpot screenshot for Resources List report
+   :width: 100%
+
+   iReport screenshot for Resources List report
+
+
+Add report bundle for translation strings
+-----------------------------------------
+
+Once defined the report format with *iReport* you need to create an special
+directory to put there translation files related with report strings.
+
+Steps:
+
+* Create directory called ``resourcesList_Bundle`` in
+  ``navalplanner-webapp/src/main/jasper/``::
+
+    mkdir navalplanner-webapp/src/main/jasper/resourcesList_Bundle
+
+  You can check bundle folders of other reports in the same directory to see
+  more   examples, but it basically contains the properties files with different
+  translations for the project.
+
+* Create a file called ``resourcesList.properties`` inside the new directory
+  with the following content:
+
+::
+
+ # Locale for resourcesListReport.jrxml
+ title = Resources List Report
+ subtitle = List of resources
+ page = page
+ of = of
+
+* Copy this file to a new one for English locale::
+
+    cp resourcesList.properties resourcesList_en_US.properties
+
+* Add the following lines in main ``pom.xml`` file at project root folder,
+  in ``Report bundle directories`` section::
+
+    <resource>
+        <directory>../navalplanner-webapp/src/main/jasper/resourcesList_Bundle/</directory>
+    </resource>
+
+Now jun can run NavalPlan and see the report already working, but as you are not
+sending it any data (currently you are using ``JREmptyDataSource``) the report
+will appear empty but you can see header and footer.
+
+
+Create some example data and see your first report
+--------------------------------------------------
+
+At that point you have everything ready to generate your first report, but you
+need to show some data in the report. So, you are going to add some example data
+manually created to see the final result.
+
+Steps:
+
+* Modify ``getDataSource`` method in ``ResourcesListController`` created before
+  and use the following content as example:
+
+::
+
+     @Override
+     protected JRDataSource getDataSource() {
+         // Example data
+         ResourcesListDTO resource1 = new ResourcesListDTO("1", "Jonh Doe");
+         ResourcesListDTO resource2 = new ResourcesListDTO("2", "Richard Roe");
+
+         List<ResourcesListDTO> workersListDTOs = Arrays.asList(resource1,
+                 resource2);
+
+         return new JRBeanCollectionDataSource(workersListDTOs);
+     }
+
+* Compile NavalPlan with the following command from project root folder::
+
+    mvn -DskipTests -P-userguide clean install
+
+* Launch Jetty from ``navalplanner-webapp`` directory::
+
+    cd navalplanner-webapp
+    mvn -P-userguide jetty:run
+
+  Then if you go to the new menu entry called *Resources List* in *Reports* you
+  will be able to generate a report with the resources added as example data.
+  The report still lacks a good design and format, but at least you are able to
+  see how the basic functionality of JasperReports in NavalPlan is integrated.
+
+
+.. [1] http://jasperforge.org/jasperreports
+.. [2] http://jasperforge.org/projects/ireport