HowTo develop a new report

Example

This page uses the "Partner by City" as an example.

Report Definition

• this is for the sql queries and instructions how to calculate and render the report
• create new xml report file in XmlReports/Partner/partnerbycity.xml
  • please use the new template in XmlReports/template.xml for the report definition file
• the documentation of the xml file is here: XML Report Definition files

• if there is no subdirectory for the module yet in XmlReports/Settings, please create it (eg. Partner). The file XmlReports/Settings/Partner/Partner by City/standard.xml can be created more easy once the GUI is running.

GUI Definition

• this is for defining how a screen should look like that presents all parameters of the report to the user
• create new yaml file for report in csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner/PartnerByCity.yaml
• there is no template or generator for such a yaml file. usually it helps to make a copy of a similar yaml file that is used for reports.
• documentation about the definition of winforms with yaml file is here: Documentation YAML for OpenPetra Forms

• • when you run nant generateWinform -D:file=MReporting/gui/MPartner/PartnerByCity.yaml, the files PartnerByCity.cs and PartnerByCity.Designer.cs will be regenerated and updated in the directory csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner.
  • you will need to manually add those 2 files to the project csharp\ICT\Petra\Client\lib\MReporting\gui\MPartner\Ict.Petra.Client.MReporting.Gui.MPartner.csproj which is quite easy to do in the SharpDevelop IDE. Perhaps we can even add this to a task in NAnt sometime in the future.
  • for some customized behaviour, you might also want to manually create a code file called csharp\ICT\Petra\Client\lib\MReporting\gui\MPartner\PartnerByCity.ManualCode.yaml, and add it to the csproj file as well. Again, we might do this automatically in the future. Have a look at csharp\ICT\Petra\Client\lib\MReporting\gui\MPartner\PublicationStatisticalReport.ManualCode.cs for the contents of that file.

Navigation

• Recommended: New OpenPetra navigation (Outlook Style):
  • modify the file csharp\ICT\Petra\Definitions\UINavigation.yml
    • if you are using a customized version of OpenPetra, this will be Customizing\gui\UINavigation.yml

 Reports: {Icon=printer.ico, Namespace=Ict.Petra.Client.MReporting.Gui.MPartner}
     PartnerByCity: {ActionOpenScreen=TFrmPartnerByCity}

• Old Petra 2.x navigation:
  • create new entries in existing yaml file in csharp/ICT/Petra/Client/lib/MPartner/gui/PartnerMain.yaml
  • in section:

          mniReports: 
              Label: &Reports...
              mniReportPartnerByCity: {Label=&Partner By City Report (experiment), ActionOpenScreen=Ict.Petra.Client.MReporting.Gui.MPartner.TFrmPartnerByCity)

• • when you run nant generateWinform -D:file=MPartner/gui/PartnerMain.yaml, the files PartnerMain.cs and PartnerMain.Designer.cs will be regenerated and updated in the directory csharp/ICT/Petra/Client/lib/MPartner/gui

Store default settings

Once you are able to run your Report GUI, you can enter and select the default values and then save the settings with the name "standard", and this should create the file XmlReports/Settings/Partner/Partner by City/standard.xml. Add this line of code to the standard file to make sure that your standard settings don't get overwritten by the user:

<Parameter id="systemsettings" value="True" />

Committing new files to git

You will usually have to add these files to git:

XmlReports/Partner/partnerbycity.xml
XmlReports/Settings/Partner/Partner by City/standard.xml
csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner/PartnerByCity.yaml
csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner/PartnerByCity.cs
csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner/PartnerByCity.Designer.cs
csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner/PartnerByCity.ManualCode.cs

There will be modified files as well, but TortoiseGit will show those anyways:

csharp\ICT\Petra\Definitions\UINavigation.yml (or Customizing\gui\UINavigation.yml)
csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner/Ict.Petra.Client.MReporting.Gui.MPartner.csproj

Files that the reports do depend on

• Most report yaml files refer to a base yaml file, eg. csharp\ICT\Petra\Client\lib\MReporting\gui\MPartner\PartnerReportingForm.yaml
  • this is useful to define general permissions, which are not implemented yet
  • also defines the way the user can select the columns

• on the report definition side (XML), the report depends on XmlReports\reports.dtd which is the schema DTD for the XML file, and on XmlReports\common.xml or other xml files to avoid similar basic functions or queries in several XML files.

NAnt commands related to reports

• nant generateGlue: this is only useful if you add new functions to the server, that are made public to the client. In relation to the reports, this could be needed if you add a function for example for the financial reports, that shows all available financial years.
• nant generateGTK: this was an experiment, to see if we can generate a GUI for GTK as an alternative to Windows.Forms. But in the end, Winforms are working quite alright with Mono on Linux, therefore generateGTK is probably deprecated.
• nant generateWinforms: this will generate all winforms files, that means it will go through the Petra/Client directories and regenerate the screens for each yaml file. This may take quite a long time.
• nant generateWinform: this will only generate one specific yaml file, and compile the project in that directory and attempt to start the Petra Client.
  • you need to specify the yaml file like this: nant generateWinform -D:file=MReporting/gui/MPartner/PartnerByCity.yaml
  • it is also possible to create all yaml files in a subdirectory, eg. nant generateWinform -D:file=MReporting/gui/MPartner. This will have problems compiling the correct csproj file though, I think.

Calling special functions

If you want to get some special data which you can't get from a sql querry then you can call functions on the server to retrieve those data. There are two ways to use the data in the report xml file.

• If you want to get just one value you call the function and assign the return value to a variable.
• If you want to get many different values, you have to store these values on the server side in the results.

Getting one value from the server

For example "GetFieldOfPartner". This function is implemented in Server/lib/MReporting/MPartner/Functions.cs and returns a string with the field name of the partner. The function is called from XmlReports/Personnel/passportexpiryreport.xml and assigned to a varible in the report.

Getting many values from the server

For example to get the best address of a partner use GetPartnerBestAddress. This function is implemented in Server/lib/MReporting/MPartner/Function.cs and returns the all the address details of the best address of a partner. The function is called from XmlReports/Personnel/emergencycontactreport.xml.

Each value is stored with a command like this:

situation.GetParameters().Add("SteetName", "81 London Road");

In the xml file there must be a definition for StreetName:

<calculation align="left" id="Street Name" returns="text" returnsFormat="text">

<value text="Street Name"></value> <query> <queryDetail> <value variable="StreetName"></value> </queryDetail> </query> </calculation>