From 869f7dc652e49bae37dff57d8e91d0a88b9e0065 Mon Sep 17 00:00:00 2001 From: Alexander Fediachov Date: Wed, 7 Nov 2018 16:51:04 +0300 Subject: [PATCH 1/3] add Running Report --- Bands.md | 10 +-- CompilationInstallation.md | 33 +++++++++ ConfiguringEnvironment.md | 13 ++++ CreatingReportUsingCode.md | 2 +- Data.md | 133 +-------------------------------- Examples.md | 2 +- Exporting.md | 4 +- Fundamentals.md | 36 +-------- PassingCustomSQL.md | 20 +++++ PassingOwnConnectionString.md | 32 ++++++++ QueryParameters.md | 46 ++++++++++++ README.md | 24 ++++-- ReferenceReportObject.md | 27 +++++++ RegisteringData.md | 28 +++++++ Report.md | 21 ++++++ ReportObjects.md | 64 ++++++++-------- ReportParameters.md | 68 +++++++++++++++++ RunningReport.md | 17 +++++ Script.md | 136 +++++++++++++++++----------------- StoringLoadingReport.md | 47 ++++++++++++ SystemVariables.md | 21 ++++++ Totals.md | 24 ++++++ UsingReport.md | 26 +++++++ WebReport.md | 2 +- 24 files changed, 556 insertions(+), 280 deletions(-) create mode 100644 CompilationInstallation.md create mode 100644 ConfiguringEnvironment.md create mode 100644 PassingCustomSQL.md create mode 100644 PassingOwnConnectionString.md create mode 100644 QueryParameters.md create mode 100644 ReferenceReportObject.md create mode 100644 RegisteringData.md create mode 100644 ReportParameters.md create mode 100644 RunningReport.md create mode 100644 StoringLoadingReport.md create mode 100644 SystemVariables.md create mode 100644 Totals.md create mode 100644 UsingReport.md diff --git a/Bands.md b/Bands.md index 4ebb5a5..1db8630 100644 --- a/Bands.md +++ b/Bands.md @@ -40,11 +40,11 @@ Every band has several useful properties, which affect the printing process. | Property | Description | |:-|:-| -| CanGrow, CanShrink | These properties determine whether a band can grow or shrink depending on the size of the objects contained in the band. If both properties are disabled, the band will always have the size specified in the designer. Read more about this in the "Report Creation" chapter. | -| CanBreak | If the property is enabled, FastReport tries to print a part of the band’s contents on the available space, that is, "break" the band. Read more about this in the "Report Creation" chapter. | -| StartNewPage | Printing a band with such property begins on a new page. This property is usually used when printing groups; that is, every group is printed on a new page. | -| PrintOnBottom | A band with this property is printed at the bottom of the page, before the "Page Footer" band .This can be useful when printing certain documents, where the total sum is supposed to be printed at the bottom of the page. | -| RepeatOnEveryPage | The bands - "Data Header", "Data Footer", "Group Header" and "Group Footer" - have got this property. This type of band will be printed on each new page, when data printing is being done. Read more about this in the "Report Creation" chapter. | +| `CanGrow`, `CanShrink` | These properties determine whether a band can grow or shrink depending on the size of the objects contained in the band. If both properties are disabled, the band will always have the size specified in the designer. Read more about this in the "Report Creation" chapter. | +| `CanBreak` | If the property is enabled, FastReport tries to print a part of the band’s contents on the available space, that is, "break" the band. Read more about this in the "Report Creation" chapter. | +| `StartNewPage` | Printing a band with such property begins on a new page. This property is usually used when printing groups; that is, every group is printed on a new page. | +| `PrintOnBottom` | A band with this property is printed at the bottom of the page, before the "Page Footer" band .This can be useful when printing certain documents, where the total sum is supposed to be printed at the bottom of the page. | +| `RepeatOnEveryPage` | The bands - "Data Header", "Data Footer", "Group Header" and "Group Footer" - have got this property. This type of band will be printed on each new page, when data printing is being done. Read more about this in the "Report Creation" chapter. | --- diff --git a/CompilationInstallation.md b/CompilationInstallation.md new file mode 100644 index 0000000..bef6c25 --- /dev/null +++ b/CompilationInstallation.md @@ -0,0 +1,33 @@ +## Compiling the source code + +1. Install latest .Net Core SDK for your OS from https://www.microsoft.com/net/download +2. Follow the commands + +```sh +# for windows users +git clone https://github.com/FastReports/FastReport.git +cd FastReport +Tools\pack.bat +``` + +```sh +# for linux users +git clone https://github.com/FastReports/FastReport.git +cd FastReport +chmod 777 Tools/pack.sh && ./Tools/pack.sh +``` + +The package is located at `fr_nuget` directory. + +## Installing from NuGet + +You can add FastReport to your current project via NuGet package manager: +``` +Install-Package FastReport.OpenSource +Install-Package FastReport.OpenSource.Web +``` + +## Compiling solution in Visual Studio + +Open the FastReport.OpenSource.sln file in Visual Studio and choice the Build -> Build Solution. +Then you can set as StartUp any project from Demos folder and run it. diff --git a/ConfiguringEnvironment.md b/ConfiguringEnvironment.md new file mode 100644 index 0000000..3ca9eaa --- /dev/null +++ b/ConfiguringEnvironment.md @@ -0,0 +1,13 @@ +# 7.3. Configuring the Environment + +Using the static object FastReport.Utils.Config you can control some FastReport environment settings. + +The FastReport.Utils.Config.ReportSettings property contains some report-related settings: + +| Property | Description | +|:-|:-| +| Language DefaultLanguage | The default script language for new reports. | + +--- + +[Running a Report](RunningReport.md) | [Top Page](README.md) | [Passing Own Connection String](PassingOwnConnectionString.md) \ No newline at end of file diff --git a/CreatingReportUsingCode.md b/CreatingReportUsingCode.md index 6706bdf..d72fb58 100644 --- a/CreatingReportUsingCode.md +++ b/CreatingReportUsingCode.md @@ -96,4 +96,4 @@ The prepared report looks as follows: --- -[Report Template File Structure](ReportTemplateFileStructure.md) | [Top Page](README.md) | [Exporting](Exporting.md) \ No newline at end of file +[Report Template File Structure](ReportTemplateFileStructure.md) | [Top Page](README.md) | [Using the Report](UsingReport.md) \ No newline at end of file diff --git a/Data.md b/Data.md index dfc4ffa..96cdcbb 100644 --- a/Data.md +++ b/Data.md @@ -15,49 +15,6 @@ Data source has one or several data columns. Each column has a definite data typ DB table content is not saved in a report file. Instead, the connection string and the data source schema are stored. A connection string can contain such data as login and password, that is why it is kept ciphered in a report file. When needed, you may increase the safety by using own key for data ciphering. In this case a report file can be opened correctly only in your program. -## Query parameters - -There can be parameters in a query text. Let us see the following query: - -```sql -select * from DVDs -where Title = @param1 -``` - -This is the query to MS SQL demonstration database. The parameter with "param1" name is defined in a query. Here it should be noted: method of describing parameters in a query differs for different DBMS. For MS SQL a parameter is marked by a "@" symbol, MS Access parameters do not have names and are marked by the "?" symbol. - -If your SQL query contains parameters, you have to declare them. It can be done in the third step of the "Query Wizard" which we have looked at above. To create a parameter, press the "Add parameter" button. - -The following parameter's properties should be set in the properties window: - -| Property | Description | -|:-|:-| -| Name | Parameter name. Here you need to indicate the same name which you use in the query text. Some DBMS (for example, MS Access) do not support named parameters. In this case do not change this property. | -| DataType | Parameter data type. | -| DefaultValue | Value which will be used if the "Expression" property is not specified, or if it is impossible to calculate it (for example, when operating with the query in the report design mode). | -| Expression | Expression which returns parameter's value. This expression will be processed when you run the report. You can indicate any expression in this property (see details in the "Expressions" chapter). | -| Size | Parameter data size. This property should be indicated if the parameter is of "string" data type. | - -## Passing a value to the parameter - -Parameters are often used to ask a value from the user. Let us look at two ways to pass a value to the query parameter. - -In the first way, you pass a value programmatically. Since there is no easy way to pass a value directly to the query parameter, you need to use the report parameter, which can be easily set via code. You should do the following: - -- Create the report parameter (we will discuss the report parameters later in this chapter). Set the same DataType for the report parameter, as it is used in the query parameter. - -- In the "Expression" property of the query parameter, refer to a report parameter, for example: - -``` -[MyReportParameter] -``` - -- Pass a value to the report parameter: - -```csharp -report1.SetParameterValue("MyReportParameter", 10); -``` - ## Aliases Every data element (data sources and columns) has got its own name. By default, this is the name defined in the database. In some cases, it can be difficult to understand what is hidden behind such name, for example, ProdID. @@ -87,94 +44,6 @@ The only way to add a hierarchical data source in your report is to register it This means that, these two data sources are related to each other and can be used in the "master-detail" report type. You can also use each of these data sources separately in a "simple list" report type. -## System Variables - -There is a list of system variables that can be used in a report: - -| Variable | Description | -|:-|:-| -| Date | Date and time of the report's start. | -| Page | Current page number. | -| TotalPages | Total number of pages in the report. To use this variable, you need to enable the report's double pass. You can do this in "Report|Properties..." menu. | -| PageN | Page number in the form: "Page N". | -| PageNofM | Page number in the form: "Page N of M". | -| Row# | Data row number inside the group. This value is reset at the start of a new group. | -| AbsRow# | Absolute number of data row. This value is never reset at the start of a new group. | -| Page# | Current page number. If you join several prepared reports into one package, this variable will return current page number in a package. This variable is actually a macro. It value is substituted when the component is viewed in the preview window. That means you cannot use it in an expression. | -| TotalPages# | Total number of pages in the report. If you join several prepared reports into one package, this variable will return the number of pages in a package. You don't need to use double pass to get the correct value. This variable is actually a macro. It value is substituted when the component is viewed in the preview window. That means you cannot use it in an expression. | -| HierarchyLevel | Current level of hierarchy in a hierarchical report (see "Printing hierarchy"). The top level is equal to 1. | -| HierarchyRow# | Full row number like "1.2.1" in a hierarchical report. | - -## Totals - -In many reports, we may need to show some total information: sum of the group, number of rows in the list, and many others. FastReport uses totals to perform this task. For the total, you need to indicate the following parameters: - -- The total function type; -- The expression, which is supposed to be calculated. For the "Count" function, you do not need to indicate the expression; -- The condition. The function will be calculated if the condition is met. It's not obligatory to set up the condition. -- The data band, for which the function will be processed; -- The band, in which the total value will be printed. - -The list of total functions is given below: - -| Function | Description | -|:-|:-| -| Sum | Calculates the sum of the expression. | -| Min | Calculates the minimum value of the expression. | -| Max | Calculates the maximum value of the expression. | -| Average | Calculates the average value of the expression. | -| Count | Returns the number of rows. | - -## Report parameters - -You can define parameters in a report. Parameter is a variable, the value of which can be defined both in a report itself and outside of it. A parameter can be used in expressions and be displayed in report objects like the "Text" object. - -Most common methods of using parameters: - -- data filtering by condition set in a parameter; -- printing parameter value in a report. - -A parameter has the following properties: - -| Property | Description | -|:-|:-| -| Name | Parameter's name can have any symbols except dot ".". | -| DataType | Parameter data type. | -| Expression | Expression which returns parameter's value. More details about expressions can be found in the "Expression" chapter. This expression will be processed when calling a parameter. | -| Value | Parameter value. This property is not available in the designer and can be filled programmatically. | - -You have to set up "Name" and "DataType" properties. The "Expression" property can be left empty. In this case parameter's value should be passed programmatically. - -You can refer to a parameter from an expression using square brackets: - -``` -[Parameter name] -``` - -To a nested parameter you need to refer using this method: - -``` -[Parent parameter.Child parameter] -``` - -Since a parameter has got a definite type (it is given in the DataType property), then with parameters, you can perform those actions which are allowed for data type. So, string type parameters can be used in an expression the following way: - -``` -[StringParameter].Substring(0, 2) -``` - -Let us see one example of using parameters. Assuming we have a report which prints "Employees" table. We want to modify the report to print information about an employee with an indicated number. To do this, we need to filter the data on the "EmployeeID" data column. Create a parameter with "EmployeeID" name. Indicate parameter's type - Int32, as exactly this type has the "EmployeeID" data column. To filter an employee with an indicated ID we need to enter "Data" band editor and indicate the following expression in "Filter" tab: - -``` -[Employees.EmployeeID] == [EmployeeID] -``` - -To pass parameter value from your program to the report, use the following code: - -```csharp -report1.SetParameterValue("EmployeeID", 2); -``` - --- -[Report Objects](ReportObjects.md) | [Top Page](README.md) | [Expressions](Expressions.md) \ No newline at end of file +[Report Objects](ReportObjects.md) | [Top Page](README.md) | [Registering Data](RegisteringData.md) \ No newline at end of file diff --git a/Examples.md b/Examples.md index fee2ab6..8b6f1aa 100644 --- a/Examples.md +++ b/Examples.md @@ -1,4 +1,4 @@ -# APPENDIX I: Examples +# Examples Under Construction diff --git a/Exporting.md b/Exporting.md index b0aeae2..9176018 100644 --- a/Exporting.md +++ b/Exporting.md @@ -1,4 +1,4 @@ -# 7. Exporting +# 8. Exporting FastReport Open Source can save documents in HTML, BMP, PNG, JPEG, GIF, TIFF, EMF. @@ -119,4 +119,4 @@ EC5F2B95E3DA517ED1244012D77901BC.jpeg --- -[Creating Report Using Code](CreatingReportUsingCode.md) | [Top Page](README.md) | [Reports in Web](WebReport.md) \ No newline at end of file +[Reference to a Report Object](ReferenceReportObject.md) | [Top Page](README.md) | [Reports in Web](WebReport.md) \ No newline at end of file diff --git a/Fundamentals.md b/Fundamentals.md index d8d6bce..ec01fca 100644 --- a/Fundamentals.md +++ b/Fundamentals.md @@ -1,40 +1,10 @@ # 2. Fundamentals -In this chapter we will learn the principles of working with a report in the FastReport. We will also take a close look at report elements such as report pages, bands, and report objects. +In this chapter we will learn the principles of working with a report in the FastReport. -## Compiling the source code +We will also take a close look at report elements such as report pages, bands, and report objects. -1. Install latest .Net Core SDK for your OS from https://www.microsoft.com/net/download -2. Follow the commands - -```sh -# for windows users -git clone https://github.com/FastReports/FastReport.git -cd FastReport -Tools\pack.bat -``` - -```sh -# for linux users -git clone https://github.com/FastReports/FastReport.git -cd FastReport -chmod 777 Tools/pack.sh && ./Tools/pack.sh -``` - -The package is located at `fr_nuget` directory. - -## Installing from NuGet - -You can add FastReport to your current project via NuGet package manager: -``` -Install-Package FastReport.OpenSource -Install-Package FastReport.OpenSource.Web -``` - -## Compiling solution in Visual Studio - -Open the FastReport.OpenSource.sln file in Visual Studio and choice the Build -> Build Solution. -Then you can set as StartUp any project from Demos folder and run it. +![FastReport Designer Community Edition](images/FastReportDesignerCE.png) --- diff --git a/PassingCustomSQL.md b/PassingCustomSQL.md new file mode 100644 index 0000000..1324f78 --- /dev/null +++ b/PassingCustomSQL.md @@ -0,0 +1,20 @@ +# 7.5. Passing Custom SQL + +The report may contain data sources that are added using the Data Wizard in Designer (via "Data|Add Data Source..." menu). + +Sometimes it is needed to pass custom SQL to that data source from your application. To do this, use the following code: + +```csharp +using FastReport.Data; +... +report1.Load(...); +// do it after loading the report, before running it +// find the table by its alias +TableDataSource table = report1.GetDataSource("MyTable") as TableDataSource; +table.SelectCommand = "new SQL text"; +report1.Show(); +``` + +--- + +[Passing Own Connection String](PassingOwnConnectionString.md) | [Top Page](README.md) | [Reference to a Report Object](ReferenceReportObject.md) diff --git a/PassingOwnConnectionString.md b/PassingOwnConnectionString.md new file mode 100644 index 0000000..4b3e07f --- /dev/null +++ b/PassingOwnConnectionString.md @@ -0,0 +1,32 @@ +# 7.4. Passing Own Connection String + +If you use data sources that are defined inside a report, you may need to pass an application-defined connection string to a report. +This can be done in three ways. + +**The first method:** you pass a connection string directly to the Connection object in a report. Do the following: + +```csharp +report1.Load(...); +// do it after loading the report, before running it +// assume we have one connection in the report +report1.Dictionary.Connections[0].ConnectionString = my_connection_string; +report1.Show(); +``` + +**The second method:** you pass a connection string using the report parameter. Do the following: + +- run the report designer; +- in the "Data" window, create a new report parameter (with "MyParameter" name, for example); +- in the "Data" window, select the "Connection" object that contains a data source; +- switch to the "Properties" window and set the ConnectionStringExpression property to the following: +``` +[MyParameter] +``` +- pass the connection string to the MyParameter parameter: +```csharp +report1.SetParameterValue("MyParameter", my_connection_string); +``` + +--- + +[Configuring the Environment](ConfiguringEnvironment.md) | [Top Page](README.md) | [Passing Custom SQL](PassingCustomSQL.md) \ No newline at end of file diff --git a/QueryParameters.md b/QueryParameters.md new file mode 100644 index 0000000..9e69a0e --- /dev/null +++ b/QueryParameters.md @@ -0,0 +1,46 @@ +# 3.3. Query parameters + +There can be parameters in a query text. Let us see the following query: + +```sql +select * from DVDs +where Title = @param1 +``` + +This is the query to MS SQL demonstration database. The parameter with "param1" name is defined in a query. Here it should be noted: method of describing parameters in a query differs for different DBMS. For MS SQL a parameter is marked by a "@" symbol, MS Access parameters do not have names and are marked by the "?" symbol. + +If your SQL query contains parameters, you have to declare them. It can be done in the third step of the "Query Wizard" which we have looked at above. To create a parameter, press the "Add parameter" button. + +The following parameter's properties should be set in the properties window: + +| Property | Description | +|:-|:-| +| Name | Parameter name. Here you need to indicate the same name which you use in the query text. Some DBMS (for example, MS Access) do not support named parameters. In this case do not change this property. | +| DataType | Parameter data type. | +| DefaultValue | Value which will be used if the "Expression" property is not specified, or if it is impossible to calculate it (for example, when operating with the query in the report design mode). | +| Expression | Expression which returns parameter's value. This expression will be processed when you run the report. You can indicate any expression in this property (see details in the "Expressions" chapter). | +| Size | Parameter data size. This property should be indicated if the parameter is of "string" data type. | + +## Passing a value to the parameter + +Parameters are often used to ask a value from the user. Let us look at two ways to pass a value to the query parameter. + +In the first way, you pass a value programmatically. Since there is no easy way to pass a value directly to the query parameter, you need to use the report parameter, which can be easily set via code. You should do the following: + +- Create the report parameter. Set the same DataType for the report parameter, as it is used in the query parameter. + +- In the "Expression" property of the query parameter, refer to a report parameter, for example: + +``` +[MyReportParameter] +``` + +- Pass a value to the report parameter: + +```csharp +report1.SetParameterValue("MyReportParameter", 10); +``` + +--- + +[Report Parameters](ReportParameters.md) | [Top Page](README.md) | [System Variables](SystemVariables.md) \ No newline at end of file diff --git a/README.md b/README.md index b0aad34..9d15bdd 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,11 @@ We wish to draw up your attention to the fact that Documentation is under constr #### 2.4. [Report Objects](ReportObjects.md) ### 3. [Data](Data.md) +#### 3.1. [Registering Data](RegisteringData.md) +#### 3.2. [Report Parameters](ReportParameters.md) +#### 3.3. [Query Parameters](QueryParameters.md) +#### 3.4. [System Variables](SystemVariables.md) +#### 3.5. [Totals](Totals.md) ### 4. [Expressions](Expressions.md) @@ -32,13 +37,22 @@ We wish to draw up your attention to the fact that Documentation is under constr #### 6.3. [Report Template File Structure](ReportTemplateFileStructure.md) #### 6.5. [Creating a Report by Using Code](CreatingReportUsingCode.md) -### 7. [Exporting](Exporting.md) +### 7. [Using the Report](UsingReport.md) +#### 7.1. [Storing and Loading a Report](StoringLoadingReport.md) +#### 7.2. [Running a Report](RunningReport.md) +#### 7.3. [Configuring the Environment](ConfiguringEnvironment.md) +#### 7.4. [Passing Own Connection String](PassingOwnConnectionString.md) +#### 7.5. [Passing Custom SQL](PassingCustomSQL.md) +#### 7.6. [Reference to a Report Object](ReferenceReportObject.md) -### 8. [Reports in Web](WebReport.md) +### 8. [Exporting](Exporting.md) -### [APPENDIX I: Examples](Examples.md) -### [APPENDIX II: Class Reference](https://fastreports.github.io/FastReport.Documentation/ClassReference/api/FastReport.html) -### [APPENDIX III: The Feature Comparison Table for FastReport Open Source, FastReport Core, FastReport .Net](COMPARISON.md) +### 9. [WebReport](WebReport.md) + +### [APPENDIX I: Compilation and Installation](CompilationInstallation.md) +### [APPENDIX II: Examples](Examples.md) +### [APPENDIX III: Class Reference](https://fastreports.github.io/FastReport.Documentation/ClassReference/api/FastReport.html) +### [APPENDIX IV: The Feature Comparison Table for FastReport Open Source, FastReport Core, FastReport .Net](COMPARISON.md) ### [LICENSE](LISCENSE.md) diff --git a/ReferenceReportObject.md b/ReferenceReportObject.md new file mode 100644 index 0000000..64238ab --- /dev/null +++ b/ReferenceReportObject.md @@ -0,0 +1,27 @@ +# 7.6. Reference to a Report Object + +When you work with a report as a class (see the ["Storing a report and loading it"](StoringLoadingReport.md)), +you may refer to the report objects directly. +The following example demonstrates how to change the font of the "Text1" object contained in a report: + +```csharp +SimpleListReport report = new SimpleListReport(); +report.Text1.Font = new Font("Arial", 12); +``` +In other cases, you have to use the FindObject method of the Report object, if you need to get a reference to an object: + +```csharp +TextObject text1 = report1.FindObject("Text1") as TextObject; +text1.Font = new Font("Arial", 12); +``` + +To reference to a data source defined in a report, use the GetDataSource method of the Report object. +This method takes a data source's alias as a parameter: + +```csharp +DataSourceBase ds = report1.GetDataSource("Products"); +``` + +--- + +[Passing Custom SQL](PassingCustomSQL.md) | [Top Page](README.md) | [Exporting](Exporting.md) \ No newline at end of file diff --git a/RegisteringData.md b/RegisteringData.md new file mode 100644 index 0000000..5c909ed --- /dev/null +++ b/RegisteringData.md @@ -0,0 +1,28 @@ +# 3.1. Registering Data + +If your report uses data from an application (for example, the typed dataset or a business-object), +you have to register such data in a report. This can be done using the RegisterData method of the Report object. + +The RegisterData method must be called after you have loaded the report: + +```csharp +report1 = new Report(); +report1.Load("report.frx"); +report1.RegisterData(dataSet1, "NorthWind"); +``` + +The RegisterData method is overloaded and allows to register the following data: + +| Method | Description | +|:-|:-| +| `void RegisterData(DataSet data)` | Registers the dataset. This method registers all tables, views and relations as well. Attention: if you register more than one dataset, use the RegisterData(DataSet data, string name) method instead. | +| `void RegisterData(DataSet data, string name)` | Registers the dataset. Specify any name in the name parameter (it must be persistent and unique if you register more than one dataset). | +| `void RegisterData(DataTable data, string name)` | Registers the data table. | +| `void RegisterData(DataView data, string name)` | Registers the data view. | +| `void RegisterDataAsp(IDataSource data, string name)` | Registers the ASP.NET data source such as AccessDataSource. | +| `void RegisterData(DataRelation data, string name)` | Registers the relation. | +| `void RegisterData(IEnumerable data, string name, BOConverterFlags flags, int maxNestingLevel)` | Registers the business object. Specify what items (properties, fields) should be used, in the flags parameter. Specify the maximum nesting level in the maxNestingLevel parameter (typically you need no more than 3 levels). Several nested objects may slow down the report. | + +--- + +[Data](Data.md) | [Top Page](README.md) | [Report Parameters](ReportParameters.md) \ No newline at end of file diff --git a/Report.md b/Report.md index 9701e2d..652f4fe 100644 --- a/Report.md +++ b/Report.md @@ -10,6 +10,27 @@ Data can be any: this is data, defined in the program, or data from DBMS, for ex Prepared Report - this is what we see in the preview window (for Desktop application) or in web browser. Prepared report can be previewed, printed, saved in one of the supported formats (.png, jpg, .docx, .xlsx, .pdf and others). +## Working with Report in a code + +To work with Report component in a code, you need to do the following: + +- create a report instance; +- load a report file into it; +- register the application-defined data in a report; +- pass the values into the report parameters, if needed; +- run the report. + +The following example demonstrates how to do this: + +```csharp +using (Report report = new Report()) +{ + report.Load("report1.frx"); + report.RegisterData(dataSet1, "NorthWind"); + report.Show(); +} +``` + --- [Fundamentals](Fundamentals.md) | [Top Page](README.md) | [Report Pages](ReportPages.md) \ No newline at end of file diff --git a/ReportObjects.md b/ReportObjects.md index baabf4d..eb64e0d 100644 --- a/ReportObjects.md +++ b/ReportObjects.md @@ -4,22 +4,22 @@ A wide variety of objects can be used in a report. | Name | Description | |:-|:-| -| TextObject | Displays one or several text lines. | -| PictureObject | Displays a picture. | -| LineObject | Displays a line. A line can be vertical, horizontal or diagonal. | -| ShapeObject | Displays one of the geometrical shapes - rectangle, ellipse, triangle and others. | -| BarcodeObject | Displays a barcode. | -| CheckBoxObject | Displays a checkbox which can have two states - "Enabled" or "Disabled". | -| TableObject | Displays a table containing rows, columns and cells. | -| MatrixObject | Displays a matrix (also known as "Cross-tab"). | -| ZipCodeObject | Displays a zip code. | -| CellularTextObject | Displays each character of a text in its individual cell. | -| PolyLineObject | Displays a composite line. | -| PolygonObject | Displays a polygon shape. | -| LinearGauge | Displays a linear gauge. | -| SimpleGauge | Displays a simple gauge. | -| RadialGauge | Displays a radial gauge. | -| SimpleProgressGauge | Displays a simple progress gauge. | +| `TextObject` | Displays one or several text lines. | +| `PictureObject` | Displays a picture. | +| `LineObject` | Displays a line. A line can be vertical, horizontal or diagonal. | +| `ShapeObject` | Displays one of the geometrical shapes - rectangle, ellipse, triangle and others. | +| `BarcodeObject` | Displays a barcode. | +| `CheckBoxObject` | Displays a checkbox which can have two states - "Enabled" or "Disabled". | +| `TableObject` | Displays a table containing rows, columns and cells. | +| `MatrixObject` | Displays a matrix (also known as "Cross-tab"). | +| `ZipCodeObject` | Displays a zip code. | +| `CellularTextObject` | Displays each character of a text in its individual cell. | +| `PolyLineObject` | Displays a composite line. | +| `PolygonObject` | Displays a polygon shape. | +| `LinearGauge` | Displays a linear gauge. | +| `SimpleGauge` | Displays a simple gauge. | +| `RadialGauge` | Displays a radial gauge. | +| `SimpleProgressGauge` | Displays a simple progress gauge. | An object can be used to display an information ("Text", etc objects) or to improve the report appearance ("Picture", "Line", "Shape" objects). Complex objects like "Table" and "Matrix" can contain other simple objects. @@ -31,22 +31,22 @@ You can change the value of properties with the help of the "Properties" window. | Property | Description | |:-|:-| -| Left, Top, Width, Height | A report object, as a rule, is a rectangle. It has coordinates (properties Left, Top) and size (properties Width, Height). | -| Anchor | This property determines how the object will be changing its position and/or its size when the container on which it is laying grows or shrinks. By using Anchor, it can be done in such a way that, the object expands or moves synchronously with container. Read more about this property in the "Dynamic layout" chapter. | -| Dock | This property determines on which side of the container the object will be docked. Read more about this property in the "Dynamic layout" chapter. | -| Border, Fill | These properties control the object's border and fill. They can be changed using the "Border and Fill" toolbar. | -| CanGrow, CanShrink | These properties allow fitting the height of the object in such a way that it fits the whole text. Read more about this property in the "Dynamic layout" chapter. | -| ShiftMode | An object, whose property is enabled, will be moving up and down, if the object above on can either grow or shrink. Read more about this property in the "Dynamic layout" chapter. | -| GrowToBottom | An object, whose property is enabled, will be stretched to the bottom of a band. Read more about this property in the "Dynamic layout" chapter. | -| CanBreak | Objects "Text" and "Rich Text" have this property. It determines whether the object’s contents can be broken into parts. | -| PrintOn | This property determines on which pages the object can be printed. Read more about this property in the "Booklet-type report" chapter. | -| Cursor | This property determines the type of mouse cursor when it is located over an object. The property works only in the preview window. | -| Visible | This property determines whether the object will be displayed in the report. Invisible object is never displayed in the preview window and is never printed on the printer as well. | -| Printable | This property determines whether the object will be printed on the printer. If this property is disabled, then the object will be visible in the preview window but it will not be printed. | -| Hyperlink | This property makes it possible to make the report object interactive. Read more about this property in the "Interactive reports" chapter. | -| Bookmark | This property is used together with the "Hyperlink" property. It can contain any expression. The expression will be calculated when the report will be working, and its value will be used as bookmark's name. -| Restrictions | This property restricts certain operations, such as moving, resizing, deleting the object. | -| Style | You can assign the style name to this property. When this is done, the object will become like it has been indicated in the style. If the parameters of the style changes, the appearance of the object changes as well. | +| `Left`, `Top`, `Width`, `Height` | A report object, as a rule, is a rectangle. It has coordinates (properties `Left`, `Top`) and size (properties `Width`, `Height`). | +| `Anchor` | This property determines how the object will be changing its position and/or its size when the container on which it is laying grows or shrinks. By using Anchor, it can be done in such a way that, the object expands or moves synchronously with container. Read more about this property in the "Dynamic layout" chapter. | +| `Dock` | This property determines on which side of the container the object will be docked. Read more about this property in the "Dynamic layout" chapter. | +| `Border`, `Fill` | These properties control the object's border and fill. They can be changed using the "Border and Fill" toolbar. | +| `CanGrow`, `CanShrink` | These properties allow fitting the height of the object in such a way that it fits the whole text. Read more about this property in the "Dynamic layout" chapter. | +| `ShiftMode` | An object, whose property is enabled, will be moving up and down, if the object above on can either grow or shrink. Read more about this property in the "Dynamic layout" chapter. | +| `GrowToBottom` | An object, whose property is enabled, will be stretched to the bottom of a band. Read more about this property in the "Dynamic layout" chapter. | +| `CanBreak` | Objects "Text" and "Rich Text" have this property. It determines whether the object’s contents can be broken into parts. | +| `PrintOn` | This property determines on which pages the object can be printed. Read more about this property in the "Booklet-type report" chapter. | +| `Cursor` | This property determines the type of mouse cursor when it is located over an object. The property works only in the preview window. | +| `Visible` | This property determines whether the object will be displayed in the report. Invisible object is never displayed in the preview window and is never printed on the printer as well. | +| `Printable` | This property determines whether the object will be printed on the printer. If this property is disabled, then the object will be visible in the preview window but it will not be printed. | +| `Hyperlink` | This property makes it possible to make the report object interactive. Read more about this property in the "Interactive reports" chapter. | +| `Bookmark` | This property is used together with the `Hyperlink` property. It can contain any expression. The expression will be calculated when the report will be working, and its value will be used as bookmark's name. +| `Restrictions` | This property restricts certain operations, such as moving, resizing, deleting the object. | +| `Style` | You can assign the style name to this property. When this is done, the object will become like it has been indicated in the style. If the parameters of the style changes, the appearance of the object changes as well. | --- diff --git a/ReportParameters.md b/ReportParameters.md new file mode 100644 index 0000000..60908d5 --- /dev/null +++ b/ReportParameters.md @@ -0,0 +1,68 @@ +# 3.2. Report Parameters + +You can define parameters in a report. Parameter is a variable, the value of which can be defined both in a report itself and outside of it. A parameter can be used in expressions and be displayed in report objects like the "Text" object. + +Most common methods of using parameters: + +- data filtering by condition set in a parameter; +- printing parameter value in a report. + +A parameter has the following properties: + +| Property | Description | +|:-|:-| +| Name | Parameter's name can have any symbols except dot ".". | +| DataType | Parameter data type. | +| Expression | Expression which returns parameter's value. More details about expressions can be found in the "Expression" chapter. This expression will be processed when calling a parameter. | +| Value | Parameter value. This property is not available in the designer and can be filled programmatically. | + +You have to set up "Name" and "DataType" properties. The "Expression" property can be left empty. In this case parameter's value should be passed programmatically. + +You can refer to a parameter from an expression using square brackets: + +``` +[Parameter name] +``` + +To a nested parameter you need to refer using this method: + +``` +[Parent parameter.Child parameter] +``` + +Since a parameter has got a definite type (it is given in the DataType property), then with parameters, you can perform those actions which are allowed for data type. So, string type parameters can be used in an expression the following way: + +``` +[StringParameter].Substring(0, 2) +``` + +Let us see one example of using parameters. Assuming we have a report which prints "Employees" table. We want to modify the report to print information about an employee with an indicated number. To do this, we need to filter the data on the "EmployeeID" data column. Create a parameter with "EmployeeID" name. Indicate parameter's type - Int32, as exactly this type has the "EmployeeID" data column. To filter an employee with an indicated ID we need to enter "Data" band editor and indicate the following expression in "Filter" tab: + +``` +[Employees.EmployeeID] == [EmployeeID] +``` + +## Passing a Value to a Report Parameter + +To pass a value to the parameter, use the SetParameterValue method of the Report object: + +```csharp +report1.Load("report.frx"); +report1.SetParameterValue("MyParam", 10); +report1.Prepare(); +``` +This method is declared as follows: + +```csharp +public void SetParameterValue(string complexName, object value) +``` + +Specify the parameter's name in the complexName parameter. To access a nested parameter, use its full name, for example: + +```csharp +"ParentParameter.ChildParameter" +``` + +--- + +[Registering Data](RegisteringData.md) | [Top Page](README.md) | [Query Parameters](QueryParameters.md) \ No newline at end of file diff --git a/RunningReport.md b/RunningReport.md new file mode 100644 index 0000000..44956b2 --- /dev/null +++ b/RunningReport.md @@ -0,0 +1,17 @@ +# 7.2. Running a Report + +To run a report, use one of the following methods of the Report object: + +`bool Prepare()` - Runs a report. If the report was prepared successfully, returns true. + +`bool Prepare(bool append)` - Runs a report. If the append parameter is set to true, the prepared report will be added to the existing one. So you can build several reports and display them in the preview as one report: +```csharp +report1.Load("report1.frx"); +report1.Prepare(); +report1.Load("report2.frx"); +report1.Prepare(true); +``` + +--- + +[Storing and Loading a Report](StoringLoadingReport.md) | [Top Page](README.md) | [Configuring the Environment](ConfiguringEnvironment.md) \ No newline at end of file diff --git a/Script.md b/Script.md index 93afb77..f90e259 100644 --- a/Script.md +++ b/Script.md @@ -26,41 +26,41 @@ private void Text2_BeforePrint(object sender, EventArgs e) ## Report Events -In order to control the report with maximum flexibility, every report object has got several events. For example, in a handler, connected to the "Data" band, you can filter records, that is, hide or show the band depending on certain conditions. +In order to control the report with maximum flexibility, every report object has got several events. For example, in a handler, connected to the `Data` band, you can filter records, that is, hide or show the band depending on certain conditions. -Let us consider the events which are fired during the report generation process. As an example, we will take a simple report, containing one page, one "Data" band and two "Text" objects on the band: +Let us consider the events which are fired during the report generation process. As an example, we will take a simple report, containing one page, one `Data` band and two `Text` objects on the band: ![](images/scriptevents1.png) -In the beginning of the report, the "Report" object fires the StartReport event. Before formation of the report page, the StartPage event is fired. This event is fired once for every template page (do not confuse with prepared report page!). In our case, regardless of how many pages were in the prepared report - event is fired once, since the template report has got one page. +In the beginning of the report, the `Report` object fires the `StartReport` event. Before formation of the report page, the `StartPage` event is fired. This event is fired once for every template page (do not confuse with prepared report page!). In our case, regardless of how many pages were in the prepared report - event is fired once, since the template report has got one page. Further, printing of the "Data" band row starts. This happens in the following way: -1. the BeforePrint band event is fired; -2. the BeforePrint event of all objects lying on the band is fired; +1. the `BeforePrint` band event is fired; +2. the `BeforePrint` event of all objects lying on the band is fired; 3. all objects are filled with data; -4. the AfterData event of all objects lying on the band is fired; -5. the BeforeLayout band event is fired; +4. the `AfterData` event of all objects lying on the band is fired; +5. the `BeforeLayout` band event is fired; 6. objects are placed on the band, the height of the band is calculated and band is stretched (if it can); -7. the AfterLayout band event is fired; +7. the `AfterLayout` band event is fired; 8. if the band cannot fit on a free space on the page, a new page is formed; 9. the band and all its objects are displayed on a prepared report page; -10. the AfterPrint band event is fired; -11. the AfterPrint event of all the band objects is fired. +10. the `AfterPrint` band event is fired; +11. the `AfterPrint` event of all the band objects is fired. -Printing of the band row occurs as long as there is data in the source. After this, the formation of the report in our case ends. The FinishPage event of a page is fired and finally - the FinishReport event of the "Report" object. +Printing of the band row occurs as long as there is data in the source. After this, the formation of the report in our case ends. The `FinishPage` event of a page is fired and finally - the `FinishReport` event of the `Report` object. So, by using events of different objects, you can control every step of report formation. The key to correct use of events - full understanding of the band printing process, expound in the eleven steps above. So, a lot of operations can be done, by using only the BeforePrint band - any change, done to the object, will also be displayed. But in this event, it is not possible to analyze, on which page will the band be printed, if it stretches, because the height of the band will be calculated on step 6. This can be done with the help of the AfterLayout event in step 7 or AfterPrint in step 10, but in the latter case, the band is already printed and operations with objects do not give out anything. In one word, you must clearly state, at what moment each event is fired and use, those, which correspond with the given task. ## Reference to report objects -For referring to report objects (for example, "Text" object) use the name of the object. The following example returns the height of Text1 object: +For referring to report objects (for example, `Text` object) use the name of the object. The following example returns the height of `Text1` object: ```csharp float height = Text1.Height; ``` -Note that report's native unit of measurement is screen pixels. Keep it in mind when using such object's properties like Left, Top, Width, and Height. To convert pixels into centimeters and back, use the constants, defined in the "Units" class: +Note that report's native unit of measurement is screen pixels. Keep it in mind when using such object's properties like `Left`, `Top`, `Width`, and `Height`. To convert pixels into centimeters and back, use the constants, defined in the `Units` class: ```csharp float heightInPixels = Text1.Height; @@ -70,66 +70,66 @@ Text1.Height = Units.Centimeters * 5; // 5см ## Report and Engine objects -Apart from objects, which are contained in the report, there are two variables defined in the script: Report and Engine. +Apart from objects, which are contained in the report, there are two variables defined in the script: `Report` and `Engine`. -The Report variable refers to the current report. In the list below, a list of the report object's methods is given: +The `Report` variable refers to the current report. In the list below, a list of the report object's methods is given: | Method | Description | |:-|:-| -| object Calc(string expression) | Calculates an expression and returns the value. When calling this method the first time, an expression gets compiled, which needs some time. | -| object GetColumnValue(string complexName) | Returns the value of the data column. The name must be presented in the "DataSource.Column" form. If the column has got the null value, it is converted into a value by default (0, empty string, false). | -| object GetColumnValueNullable(string complexName) | Returns the value of the data column. Contrary to the previous method, it does not get converted into a default value and may be null. | -| Parameter GetParameter(string complexName) | Returns the reports parameter with the indicated name. Name can be compounded when referring to the nested parameter: "MainParam.NestedParam". | -| object GetParameterValue(string complexName) | Returns the value of the report parameter with the indicated name. | -| void SetParameterValue(string complexName, object value) | Sets the value of the report parameter with the indicated name. | -| object GetVariableValue(string complexName) | Returns the value of the system variable, for example, "Date". | -| object GetTotalValue(string name) | Returns the value of the total, defined in the "Data" window, by its name. | -| DataSourceBase GetDataSource(string alias) | Returns the data source, defined in the report, by its name. | - -The Engine object is an engine that controls the report creation. By using the methods and properties of the engine, you can manage the process of placing bands onto the page. You can use the following properties of the Engine object: -|:-|:-| +| `object Calc(string expression)` | Calculates an expression and returns the value. When calling this method the first time, an expression gets compiled, which needs some time. | +| `object GetColumnValue(string complexName)` | Returns the value of the data column. The name must be presented in the `DataSource.Column` form. If the column has got the null value, it is converted into a value by default (0, empty string, false). | +| `object GetColumnValueNullable(string complexName)` | Returns the value of the data column. Contrary to the previous method, it does not get converted into a default value and may be null. | +| `Parameter GetParameter(string complexName)` | Returns the reports parameter with the indicated name. Name can be compounded when referring to the nested parameter: "MainParam.NestedParam". | +| `object GetParameterValue(string complexName)` | Returns the value of the report parameter with the indicated name. | +| `void SetParameterValue(string complexName, object value)` | Sets the value of the report parameter with the indicated name. | +| `object GetVariableValue(string complexName)` | Returns the value of the system variable, for example, `Date`. | +| `object GetTotalValue(string name)` | Returns the value of the total, defined in the `Data` window, by its name. | +| `DataSourceBase GetDataSource(string alias)` | Returns the data source, defined in the report, by its name. | + +The `Engine` object is an engine that controls the report creation. By using the methods and properties of the engine, you can manage the process of placing bands onto the page. You can use the following properties of the `Engine` object: + | Property | Description | -| float CurX | Current coordinates on the X-axis. This property can be assigned a value, so as to shift the printed object. | -| float CurY | Current printing position on the Y-axis. To this property, a value can be assigned so as to shift the printed object. | -| int CurColumn | Number of the current column in a multicolumn report. The first column has the number 0. | -| int CurPage | Number of the page being printed. This value can be received from the "Page" system variable. | -| float PageWidth | Width of the page minus the size of the left and right margins. | -| float PageHeight | Height of the page minus the size of the top and bottom margins. | -| float PageFooterHeight | Height of the page footer (and all its child bands). | -| float ColumnFooterHeight | Height of the column footer (and all of its child bands). | -| float FreeSpace | Size of the free space on the page. | -| bool FirstPass | Returns true, if the first (or only) report pass is being executed. Number of passes can be obtained from the Report.DoublePass property. | -| bool FinalPass | Returns true, if the last (or only) report pass is being executed. | +|:-|:-| +| `float CurX` | Current coordinates on the X-axis. This property can be assigned a value, so as to shift the printed object. | +| `float CurY` | Current printing position on the Y-axis. To this property, a value can be assigned so as to shift the printed object. | +| `int CurColumn` | Number of the current column in a multicolumn report. The first column has the number 0. | +| `int CurPage` | Number of the page being printed. This value can be received from the `Page` system variable. | +| `float PageWidth` | Width of the page minus the size of the left and right margins. | +| `float PageHeight` | Height of the page minus the size of the top and bottom margins. | +| `float PageFooterHeight` | Height of the page footer (and all its child bands). | +| `float ColumnFooterHeight` | Height of the column footer (and all of its child bands). | +| `float FreeSpace` | Size of the free space on the page. | +| `bool FirstPass` | Returns true, if the first (or only) report pass is being executed. Number of passes can be obtained from the `Report.DoublePass` property. | +| `bool FinalPass` | Returns true, if the last (or only) report pass is being executed. | On the figure below, you can see the meaning of some properties listed above. ![](images/scriptexample5.png) -Engine.PageWidth and Engine.PageHeight properties determine the size of the printing area, which is almost always less than the actual size of the page. Size of the printed area is determined by the page margins, which is given by the LeftMargin, TopMargin, RightMargin and BottomMargin page properties. +`Engine.PageWidth` and `Engine.PageHeight` properties determine the size of the printing area, which is almost always less than the actual size of the page. Size of the printed area is determined by the page margins, which is given by the `LeftMargin`, `TopMargin`, `RightMargin` and `BottomMargin` page properties. -Engine.FreeSpace property determines the height of the free space on the page. If there is the "Page footer" band on the page, its height is considered when calculating the FreeSpace. Note that, after printing a band, free space is reduced. +`Engine.FreeSpace` property determines the height of the free space on the page. If there is the "Page footer" band on the page, its height is considered when calculating the FreeSpace. Note that, after printing a band, free space is reduced. -How does the formation of a prepared report page take place? FastReport engine displays bands on the page until there is enough space for band output. When there is no free space, the "Report footer" band is printed and a new empty page is formed. Displaying a band starts from the current position, which is determined by the X and Y coordinates. This position is retuned by the Engine.CurX and Engine.CurY properties. After printing a band, CurY automatically increases by the height of the printed band. After forming a new page, the position of the CurY is set to 0. The position of the CurX changes when printing a multicolumn report. +How does the formation of a prepared report page take place? FastReport engine displays bands on the page until there is enough space for band output. When there is no free space, the "Report footer" band is printed and a new empty page is formed. Displaying a band starts from the current position, which is determined by the X and Y coordinates. This position is retuned by the `Engine.CurX` and `Engine.CurY` properties. After printing a band, `CurY` automatically increases by the height of the printed band. After forming a new page, the position of the `CurY` is set to 0. The position of the `CurX` changes when printing a multicolumn report. -Engine.CurX and Engine.CurY properties are accessible not only for reading, but also for writing. This means that you can shift a band manually by using one of the suitable events. Examples of using these properties can be seen in the "Examples" section. +`Engine.CurX` and `Engine.CurY` properties are accessible not only for reading, but also for writing. This means that you can shift a band manually by using one of the suitable events. Examples of using these properties can be seen in the "Examples" section. When working with properties, which return the size or position, remember that, these properties are measured in the screen pixels. -In the Engine object, the following methods are defined: - +In the `Engine` object, the following methods are defined: | Method | Description | |:-|:-| -| void AddOutline(string text) | Adds an element into the report outline (read the chapter "Interactive reports") and sets the current position to the added element. | -| void OutlineRoot() | Sets the current position on the root of the outline. | -| void OutlineUp() | Shifts the current position to a higher-level outline element. | -| void AddBookmark(string name) | Adds a bookmark (read the chapter "Interactive reports"). | -| int GetBookmarkPage(string name) | Returns the page number on which the bookmark with the indicated name is placed. | -| void StartNewPage() | Starts a new page. If the report is multicolumn, a new column is started. | +| `void AddOutline(string text)` | Adds an element into the report outline and sets the current position to the added element. | +| `void OutlineRoot()` | Sets the current position on the root of the outline. | +| `void OutlineUp()` | Shifts the current position to a higher-level outline element. | +| `void AddBookmark(string name)` | Adds a bookmark. | +| `int GetBookmarkPage(string name)` | Returns the page number on which the bookmark with the indicated name is placed. | +| `void StartNewPage()` | Starts a new page. If the report is multicolumn, a new column is started. | -By using the AddOutline, OutlineRoot, OutlineUp methods, you can form the report outline manually. Usually, this is done automatically with the help of the OutlineExpression property, which every band and report page have got. +By using the `AddOutline`, `OutlineRoot`, `OutlineUp` methods, you can form the report outline manually. Usually, this is done automatically with the help of the `OutlineExpression` property, which every band and report page have got. -The AddOutline method adds a child element to the current outline element, and makes it current. The current report page and the current position on the page are associated with the new element. If you call the AddOutline method several times, then you will have the following structure: +The `AddOutline` method adds a child element to the current outline element, and makes it current. The current report page and the current position on the page are associated with the new element. If you call the `AddOutline` method several times, then you will have the following structure: ``` Item1 @@ -137,7 +137,7 @@ Item1 Item3 ``` -For controlling the current element, there are OutlineUp and OutlineRoot methods. The first method moves the pointer to the element, located on a higher level. So, the script +For controlling the current element, there are `OutlineUp` and `OutlineRoot` methods. The first method moves the pointer to the element, located on a higher level. So, the script ```csharp Engine.AddOutline("Item1"); @@ -156,7 +156,7 @@ Item1 Item4 ``` -The OutlineRoot method moves the current element to the root of the outline. For example, the following script: +The `OutlineRoot` method moves the current element to the root of the outline. For example, the following script: ```csharp Engine.AddOutline("Item1"); @@ -175,15 +175,15 @@ Item1 Item4 ``` -For working with bookmarks, the AddBookmark and GetBookmarkPage methods of the Engine object are used. Usually bookmarks are added automatically when using the Bookmark property, which all objects of the report have got. +For working with bookmarks, the `AddBookmark` and `GetBookmarkPage` methods of the `Engine` object are used. Usually bookmarks are added automatically when using the `Bookmark` property, which all objects of the report have got. -By using the Add Bookmark method, you can add a bookmark programmatically. This method creates a bookmark on the current page at the current printing position. +By using the `AddBookmark` method, you can add a bookmark programmatically. This method creates a bookmark on the current page at the current printing position. -The GetBookmarkPage method returns the page number on which the bookmark is placed. This method is often used when creating the table of contents, for displaying page numbers. In this case, the report must have a double pass. +The `GetBookmarkPage` method returns the page number on which the bookmark is placed. This method is often used when creating the table of contents, for displaying page numbers. In this case, the report must have a double pass. ## Reference to data sources -Contrary to the FastReport expressions (covered in the "Expressions" section), never use square brackets in script for referring to the data sources. Instead of this, use the GetColumnValue method of the Report object, which returns the value of the column: +Contrary to the FastReport expressions (covered in the "Expressions" section), never use square brackets in script for referring to the data sources. Instead of this, use the `GetColumnValue` method of the `Report` object, which returns the value of the column: ```csharp string productName = (string)Report.GetColumnValue("Products.Name"); @@ -195,13 +195,13 @@ As seen, you need to indicate the name of the source and its column. The name of string categoryName = (string)Report.GetColumnValue("Products.Categories.CategoryName"); ``` -For referring to the data source itself, use the GetDataSource method of the Report object: +For referring to the data source itself, use the `GetDataSource` method of the `Report` object: ```csharp DataSourceBase ds = Report.GetDataSource("Products"); ``` -Help on properties and methods of the DataSourceBase class can be received from the FastReport.Net Class Reference help system. As a rule, this object is used in the script in the following way: +Help on properties and methods of the `DataSourceBase` class can be received from the FastReport.Net Class Reference help system. As a rule, this object is used in the script in the following way: ```csharp // get a reference to the data source @@ -220,23 +220,23 @@ while (ds.HasMoreRows) } ``` -## Rererence to system variables +## Rererence to System Variables -For reference to system variables, use the GetVariableValue method of the Report object: +For reference to system variables, use the `GetVariableValue` method of the `Report` object: ```csharp DateTime date = (DateTime)Report.GetVariableValue("Date"); ``` -## Reference to total values +## Reference to Total Values -For reference to the total value, use the GetTotalValue method of the Report object: +For reference to the total value, use the `GetTotalValue` method of the `Report` object: ```csharp float sales = Report.GetTotalValue("TotalSales"); ``` -Total value has got the FastReport.Variant type. It can be used directly in any expression, because the FastReport.Variant type is automatically converted to any type. For example: +Total value has got the `FastReport.Variant` type. It can be used directly in any expression, because the `FastReport.Variant` type is automatically converted to any type. For example: ```csharp float tax = Report.GetTotalValue("TotalSales") * 0.2f; @@ -246,7 +246,7 @@ Reference to the total value can be done at that time when, it is being processe ## Reference to report parameters -For referring to report parameters, use the GetParameterValue method of the Report object: +For referring to report parameters, use the `GetParameterValue` method of the `Report` object: ```csharp int myParam = (int)Report.GetParameterValue("MyParameter"); @@ -258,9 +258,9 @@ Parameters can be nested. In this case, indicate the name of the parent paramete Report.GetParameterValue("ParentParameter.ChildParameter") ``` -Parameters have got a definite data type. It is given in the DataType property of the parameter. You must take this into account when referring to parameters. +Parameters have got a definite data type. It is given in the `DataType` property of the parameter. You must take this into account when referring to parameters. -For changing the value of the parameter, use the SetParameterValue method of the report object: +For changing the value of the parameter, use the `SetParameterValue` method of the report object: ```csharp Report.SetParameterValue("MyParameter", 10); diff --git a/StoringLoadingReport.md b/StoringLoadingReport.md new file mode 100644 index 0000000..92462f2 --- /dev/null +++ b/StoringLoadingReport.md @@ -0,0 +1,47 @@ +# 7.1. Storing and Loading a Report + +You may store a report in the following ways: + + +## In the .FRX file + +To load the report from a file, use the `Load` method of the `Report` object: + +```csharp +report1.Load("filename.frx"); +``` + +## In the database + +You may store a report in the database, either as a string or in a blob-stream. +To load the report from a string, use the `LoadFromString` method of the `Report` object. +To load the report from a stream, use the overloaded version of the Load method: + +```csharp +report1.Load(stream); +``` + +## As a C#/VB.NET class +To work with a report as a class, design your report and save in to the .cs/.vb file. +To do this, select "file type" in the "Save" dialog. The file type maybe either .cs or .vb - it depends on the script language in the report (it may be changed in the "Report|Options..." menu). +Include that file into your project. This method has the following Pros: + +- you can work with a report as a class; +- you may debug a report; +- this is the only way to use a report in ASP.NET project running on medium trust environment; + +and Cons: + +- you cannot edit such a report. To do this, you need the original .FRX file; +- if you need to change a report, you have to recompile your application. + +To work with a report, create an instance of the report's class: + +```csharp +SimpleListReport report = new SimpleListReport(); +report.Show(); +``` + +--- + +[Using the Report](UsingReport.md) | [Top Page](README.md) | [Running a Report](RunningReport.md) diff --git a/SystemVariables.md b/SystemVariables.md new file mode 100644 index 0000000..ecf2589 --- /dev/null +++ b/SystemVariables.md @@ -0,0 +1,21 @@ +# 3.4. System Variables + +There is a list of system variables that can be used in a report: + +| Variable | Description | +|:-|:-| +| `Date` | Date and time of the report's start. | +| `Page` | Current page number. | +| `TotalPages` | Total number of pages in the report. To use this variable, you need to enable the report's double pass. You can do this in "Report|Properties..." menu. | +| `PageN` | Page number in the form: "Page N". | +| `PageNofM` | Page number in the form: "Page N of M". | +| `Row#` | Data row number inside the group. This value is reset at the start of a new group. | +| `AbsRow#` | Absolute number of data row. This value is never reset at the start of a new group. | +| `Page#` | Current page number. If you join several prepared reports into one package, this variable will return current page number in a package. This variable is actually a macro. It value is substituted when the component is viewed in the preview window. That means you cannot use it in an expression. | +| `TotalPages#` | Total number of pages in the report. If you join several prepared reports into one package, this variable will return the number of pages in a package. You don't need to use double pass to get the correct value. This variable is actually a macro. It value is substituted when the component is viewed in the preview window. That means you cannot use it in an expression. | +| `HierarchyLevel` | Current level of hierarchy in a hierarchical report. The top level is equal to 1. | +| `HierarchyRow#` | Full row number like "1.2.1" in a hierarchical report. | + +--- + +[Query Parameters](QueryParameters.md) | [Top Page](README.md) | [Totals](Totals.md) diff --git a/Totals.md b/Totals.md new file mode 100644 index 0000000..867ed5a --- /dev/null +++ b/Totals.md @@ -0,0 +1,24 @@ +# 3.5. Totals + +In many reports, we may need to show some total information: sum of the group, number of rows in the list, and many others. FastReport uses totals to perform this task. For the total, you need to indicate the following parameters: + +- The total function type; +- The expression, which is supposed to be calculated. For the "Count" function, you do not need to indicate the expression; +- The condition. The function will be calculated if the condition is met. It's not obligatory to set up the condition. +- The data band, for which the function will be processed; +- The band, in which the total value will be printed. + +The list of total functions is given below: + +| Function | Description | +|:-|:-| +| `Sum` | Calculates the sum of the expression. | +| `Min` | Calculates the minimum value of the expression. | +| `Max` | Calculates the maximum value of the expression. | +| `Average` | Calculates the average value of the expression. | +| `Count` | Returns the number of rows. | + + +--- + +[System Variables](SystemVariables.md) | [Top Page](README.md) | [Expressions](Expressions.md) \ No newline at end of file diff --git a/UsingReport.md b/UsingReport.md new file mode 100644 index 0000000..b574d75 --- /dev/null +++ b/UsingReport.md @@ -0,0 +1,26 @@ +# 7. Using the Report + +## Working with Report in a code + +To work with Report component in a code, you need to do the following: + +- create a report instance; +- load a report file into it; +- register the application-defined data in a report; +- pass the values into the report parameters, if needed; +- run the report. + +The following example demonstrates how to do this: + +```csharp +using (Report report = new Report()) +{ + report.Load("report1.frx"); + report.RegisterData(dataSet1, "NorthWind"); + report.Show(); +} +``` + +--- + +[Creating a Report by Using Code](CreatingReportUsingCode.md) | [Top Page](README.md) | [Storing and Loading a Report](StoringLoadingReport.md) \ No newline at end of file diff --git a/WebReport.md b/WebReport.md index 7323da0..3020fc8 100644 --- a/WebReport.md +++ b/WebReport.md @@ -1,4 +1,4 @@ -# 8. Reports in Web +# 9. Reports in Web ## Inside WebReport From 1e1a84e66b067a31c34994169ab72967d40a2667 Mon Sep 17 00:00:00 2001 From: Alexander Fediachov Date: Wed, 7 Nov 2018 16:54:10 +0300 Subject: [PATCH 2/3] fix char in SystemVariables.md --- SystemVariables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SystemVariables.md b/SystemVariables.md index ecf2589..ff088e0 100644 --- a/SystemVariables.md +++ b/SystemVariables.md @@ -6,7 +6,7 @@ There is a list of system variables that can be used in a report: |:-|:-| | `Date` | Date and time of the report's start. | | `Page` | Current page number. | -| `TotalPages` | Total number of pages in the report. To use this variable, you need to enable the report's double pass. You can do this in "Report|Properties..." menu. | +| `TotalPages` | Total number of pages in the report. To use this variable, you need to enable the report's double pass. You can do this in "Report\|Properties..." menu. | | `PageN` | Page number in the form: "Page N". | | `PageNofM` | Page number in the form: "Page N of M". | | `Row#` | Data row number inside the group. This value is reset at the start of a new group. | From 940fb21f78a0b22b657c514eb6e503eb2a409b17 Mon Sep 17 00:00:00 2001 From: Alexander Fediachov Date: Wed, 7 Nov 2018 16:57:05 +0300 Subject: [PATCH 3/3] update Report.md --- Report.md | 21 --------------------- 1 file changed, 21 deletions(-) diff --git a/Report.md b/Report.md index 652f4fe..9701e2d 100644 --- a/Report.md +++ b/Report.md @@ -10,27 +10,6 @@ Data can be any: this is data, defined in the program, or data from DBMS, for ex Prepared Report - this is what we see in the preview window (for Desktop application) or in web browser. Prepared report can be previewed, printed, saved in one of the supported formats (.png, jpg, .docx, .xlsx, .pdf and others). -## Working with Report in a code - -To work with Report component in a code, you need to do the following: - -- create a report instance; -- load a report file into it; -- register the application-defined data in a report; -- pass the values into the report parameters, if needed; -- run the report. - -The following example demonstrates how to do this: - -```csharp -using (Report report = new Report()) -{ - report.Load("report1.frx"); - report.RegisterData(dataSet1, "NorthWind"); - report.Show(); -} -``` - --- [Fundamentals](Fundamentals.md) | [Top Page](README.md) | [Report Pages](ReportPages.md) \ No newline at end of file