From 650e69ed7202f4d419b78fba267c6ff937ccebf8 Mon Sep 17 00:00:00 2001 From: Alexander Fediachov Date: Thu, 25 Oct 2018 12:43:24 +0300 Subject: [PATCH 1/2] update Data.md --- Data.md | 86 ++++++++++++++++++++++++++++++++++++++ images/businessobject.png | Bin 0 -> 4125 bytes 2 files changed, 86 insertions(+) create mode 100644 images/businessobject.png diff --git a/Data.md b/Data.md index 2c455b7..57bbc97 100644 --- a/Data.md +++ b/Data.md @@ -1,4 +1,90 @@ # Data +Any report prints some data. In FastReport, you can operate with the following data: + +- data sources; +- system variables; +- total values; +- report parameters; +- expressions, containing any of the above mentioned data. +## Data sources + +Ordinarily, the data source represents a DB table or SQL query. There can be several data sources in a report. For most of reports, only one data source is needed. A report like Master-Detail needs two data sources which are connected to each other using a relation. + +Data source has one or several data columns. Each column has a definite data type. Column type is indicated in the "DataType" property. + +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: + +``` +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: + +``` +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. + +Data elements have got a second name - alias. By using an alias, you can rename an element. For example, if we have got a data source CATEGORY_TABLE with a column called "PROD_ID", you can give the following alias: + +``` +CATEGORY_TABLE --> Categories +PROD_ID --> Product ID +``` + +You can refer to such a data column in the following way: + +``` +[Categories.Product ID] +``` + +When referring to the data element, you must use the alias, if it has been defined. Never refer to an element by using its original name in this case. + +## Hierarchical data sources + +The data sources we have looked at, are relational, that is, they come from a relational DBMS (often called RDBMS). FastReport also supports other kinds of data - the hierarchical data sources. Such data sources come from so-called business objects, which are often used in applications to represent a relational data sources as a .Net classes. + +The only way to add a hierarchical data source in your report is to register it programmatically. It will be discussed in the "Programmer's manual". Now we will look at some differences between ordinal and hierarchical data sources. In the figure below you can see two data sources, "Categories BusinessObject" and "Products". As you can see, the "Products" data source is contained within its parent, "Categories BusinessObject": + +![](images/businessobject.png) + +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. [Next Page](Expressions.md) \ No newline at end of file diff --git a/images/businessobject.png b/images/businessobject.png new file mode 100644 index 0000000000000000000000000000000000000000..0e9c322d79b7c0b6efdf369b78e61014ea28cf37 GIT binary patch literal 4125 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 Date: Thu, 25 Oct 2018 14:01:21 +0300 Subject: [PATCH 2/2] update Data.md, Expressions.md, README.md --- Data.md | 88 ++++++++++++++++++++ Expressions.md | 216 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 + 3 files changed, 306 insertions(+) diff --git a/Data.md b/Data.md index 57bbc97..fa5d6f4 100644 --- a/Data.md +++ b/Data.md @@ -87,4 +87,92 @@ 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: + +``` +report1.SetParameterValue("EmployeeID", 2); +``` + [Next Page](Expressions.md) \ No newline at end of file diff --git a/Expressions.md b/Expressions.md index cfd2f57..9686ddb 100644 --- a/Expressions.md +++ b/Expressions.md @@ -1,4 +1,220 @@ # Expressions +In many places in FastReport, expressions are used. For example, the "Text" object can contain expressions in square brackets. + +An expression is a code in C# or VB.Net language, which returns any value. For example: + +``` +2 + 2 +``` + +An expression should be written in a language chosen as a script in a report. By default, it is C#. + +## Reference to report objects + +For referring to report objects, use the object's name. The following example will return the height of the Text1 object: + +``` +Text1.Height +``` + +For referring to report properties, use Report variable. The following example returns file name from which a report was loaded. + +``` +Report.FileName +``` + +Besides, you can refer to nested object properties. The following example will return a report name: + +``` +Report.ReportInfo.Name +``` + +## Using .Net functions + +You can use any.Net objects in expressions. The following example demonstrates Max function use: + +``` +Math.Max(5, 10) +``` + +By default a report uses the following .Net assemblies: + +``` +System.dll +System.Drawing.dll +System.Windows.Forms.dll +System.Data.dll +System.Xml.dll +``` + +You have access to all .Net objects declared in these assemblies. If you need to have access to another assembly, add its name in report assemblies list. + +For example, if you want to use a function in your report which was declared in your application, add application assembly (.exe or .dll) in a report assemblies list. After that you can call the function by using namespace of your application. For example, if the following function is defined in application: + +``` +namespace Demo +{ + public static class MyFunctions + { + public static string Func1() + { + return "Hello!"; + } + } +} +``` + +You can use it in your report in the following way: + +``` +Demo.MyFunctions.Func1() +``` + +## Reference to data elements + +Apart from standard language elements, you can use the following report elements in expressions: + +- data source columns; +- system variables; +- total values; +- report parameters. + +All these elements are contained in the "Data" window. See more details in the "Data" chapter. Any of these elements can be used in an expression, by including it in square brackets. For example: + +``` +[Page] + 1 +``` + +This expression returns next printed page number. A system variable "Page", which returns current report page number, is used in the expression. It is enclosed in square brackets. + +## Reference to data sources + +For reference to data source columns, the following format is used: + +``` +[DataSource.Column] +``` + +Source name is separated from column name by a period, for example: + +``` +[Employees.FirstName] +``` + +Source name can be compound in case, if we refer to a data source by using a relation. See more details in the "Data" section. For example, this is how you can refer to a related data source column: + +``` +[Products.Categories.CategoryName] +``` + +Let us look at the following example of using columns in an expression: + +``` +[Employees.FirstName] + " " + [Employees.LastName] +``` + +Here it should be noted that: every column has a definite data type, which is set in the "DataType" property (you can see it in the "Properties" window if to choose data column in the "Data" window beforehand). How a column can be used in an expression depends on its type. For instance, in above mentioned example, both columns - first name and last name - have got a string type and that is why they can be used in such a way. In the following example, we will try to use "Employees.Age" column of numeric type, which will lead to an error: + +``` +[Employees.FirstName] + " " + [Employees.Age] +``` + +The error occurs because, you never mix strings with numbers. For this, you need to convert the number into a string: + +``` +[Employees.FirstName] + " " + [Employees.Age].ToString() +``` + +In this case, we refer to the "Employees.Age" column as if it is an integer variable. And it is so. We know that all expressions are compiled. All non-standard things (like referring to data columns) from a compiler's point of view are converted into another type, which is understandable to a compiler. So, the last expression will be turned into the following form: + +``` +(string)(Report.GetColumnValue("Employees.FirstName")) + " " + +(int)(Report.GetColumnValue("Employees.Age")).ToString() +``` + +As seen, FastReport changes reference to data columns in the following way: + +``` +[Employees.FirstName] --> (string)(Report.GetColumnValue("Employees.FirstName")) +[Employees.Age] --> (int)(Report.GetColumnValue("Employees.Age")) +``` + +That is, we can use data column in an expressions as if it is a variable having a definite type. For example, the following expression will return the first symbol of an employee's name: + +``` +[Employees.FirstName].Substring(0, 1) +``` + +## Reference to system variables + +You can use the following system variables in expressions: + +| Variable | .Net data type | Description +|:-|:-|:-| +| Date | DateTime | Date and time of the report's start. | +| Page | int | Current page number. | +| TotalPages | int | 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 | string | Page number in the form: "Page N". | +| PageNofM | string | Page number in the form: "Page N of M". | +| Row# | int | Data row number inside the group. This value is reset at the start of a new group. | +| AbsRow# | int | Absolute number of data row. This value is never reset at the start of a new group. | + + +Every variable has a definite data type. And on this, depends how it will be used in the expression. Here is an example of an expression where date is being used: + +``` +[Date].Year +``` + +This expression returns the current year. As "Date" variable has DateTime type, we can refer to its "Year" property. We can get the current month similarly ([Date].Month). + +FastReport converts reference to system variable into the following form (for example, the "Date" variable): + +``` +((DateTime)Report.GetVariableValue("Date")) +``` + +## Reference to total values + +In order to refer to a total value, use its name: + +``` +[TotalSales] +``` + +FastReport converts reference to totals into the following form: + +``` +Report.GetTotalValue("TotalSales") +``` + +As you can see, the data type is not used here. It is so, because the total value is of FastReport.Variant type. It can be used directly in any expressions because it is automatically converted to any type. For example: + +``` +[TotalSales] * 0.2f +``` + +## Reference to report parameters + +In order to refer to report parameters, you should use its name: + +``` +[Parameter1] +``` + +Parameters can be nested. In this case, you should use both parent and child parameter names in the following form: + +``` +[ParentParameter.ChildParameter] +``` + +Parameters have a definite data type. It is set in the "DataType" property of the parameter. The way it can be used in an expression depends on parameter's data type. + +FastReport converts reference to a report parameter into the following way: + +``` +((string)Report.GetParameterValue("Parameter1")) +``` [Next Page](Script.md) diff --git a/README.md b/README.md index fb26508..a7c3cbd 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,8 @@ FastReport provides open source report generator for .NET Core 2.x/.Net Framewor Here is the FastReport Open Source Documentation. +We wish to draw up your attention to the fact that Documentation is under construction. + ## Table of Contents ### [Introduction](Introduction.md)