Merge pull request #19 from fediachov/master

Update a Documentation

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. |
 
 ---
 

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.

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)

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)
+[Report Template File Structure](ReportTemplateFileStructure.md) | [Top Page](README.md) | [Using the Report](UsingReport.md)

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)
+[Report Objects](ReportObjects.md) | [Top Page](README.md) | [Registering Data](RegisteringData.md)

Examples.md

@@ -1,4 +1,4 @@
-# APPENDIX I: Examples
+# Examples
 
 Under Construction
 

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)
+[Reference to a Report Object](ReferenceReportObject.md) | [Top Page](README.md) | [Reports in Web](WebReport.md)

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)
 
 ---
 

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)

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)

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)