API/CodeSamples/AddForcedLeftJoin.md
... ...
@@ -0,0 +1,117 @@
1
+#AddForcedLeftJoin
2
+
3
+[[_TOC_]]
4
+
5
+##About
6
+
7
+Gets or sets the column names of tables that should always use a LEFT OUTER JOIN instead of a RIGHT INNER JOIN (the standard).
8
+
9
+##When should you use AddForcedLeftJoin
10
+
11
+Sometimes there are situations where some data sources should always be joined using a left join.
12
+This means that certain data source pairs will be always joined using a left join instead of a right inner join (by default). This will also override any user-defined joins in the Report Designer. This can aid in ease in report creation, as the user will not have to specify the join type with the menu controls every time he/she creates a report joining these data sources.
13
+
14
+##How to use AddForcedLeftJoin
15
+
16
+To force data source pairs to be joined using a left join, you should call the setting within your global.asax.
17
+
18
+```csharp
19
+//main class: inherits DatabaseAdHocConfig or FileSystemAdHocConfig
20
+public class CustomAdHocConfig : Izenda.AdHoc.DatabaseAdHocConfig
21
+{
22
+ // Configure settings
23
+ // Add custom settings after setting the license key and connection string by overriding the ConfigureSettings() method
24
+ public static void InitializeReporting() {
25
+ //Check to see if we've already initialized.
26
+ if (HttpContext.Current.Session == null || HttpContext.Current.Session["ReportingInitialized"] != null)
27
+ return;
28
+ AdHocSettings.LicenseKey = "INSERT_LICENSE_KEY_HERE";
29
+ //Creates a connection to Microsoft SQL Server
30
+ AdHocSettings.SqlServerConnectionString = "INSERT_CONNECTION_STRING_HERE";
31
+ Izenda.AdHoc.AdHocSettings.AdHocConfig = new CustomAdHocConfig();
32
+ AdHocContext.Driver.AddForcedLeftJoin("Order Details", "Orders"); //The relevant setting
33
+ HttpContext.Current.Session["ReportingInitialized"] = true;
34
+ }
35
+}
36
+```
37
+
38
+```visualbasic
39
+'main class: inherits DatabaseAdHocConfig or FileSystemAdHocConfig
40
+Public Class CustomAdHocConfig
41
+ Inherits Izenda.AdHoc.DatabaseAdHocConfig
42
+
43
+ Shared Sub InitializeReporting()
44
+ 'Check to see if we've already initialized
45
+ If HttpContext.Current.Session Is Nothing OrElse HttpContext.Current.Session("ReportingInitialized") IsNot Nothing Then
46
+ Return
47
+ 'Initialize System
48
+ AdHocSettings.LicenseKey = "INSERT_LICENSE_KEY_HERE"
49
+ AdHocSettings.SqlServerConnectionString = "INSERT_CONNECTION_STRING_HERE"
50
+ Izenda.AdHoc.AdHocSettings.AdHocConfig = New CustomAdHocConfig()
51
+ AdHocContext.Driver.AddForcedLeftJoin("Order Details", "Orders") 'The relevant setting
52
+ HttpContext.Current.Session("ReportingInitialized") = True
53
+ End Sub
54
+End Class
55
+```
56
+
57
+_**Note:** AddForcedLeftJoin will force tables to be joined using a left join. This means that even if you specify another join type in the Report Designer or manually in code, this setting will override the other join automatically._
58
+
59
+_**Note2:** The order of parameters in this method is important. (i.e. these tables will be joined with a left join only if the "Orders" table (left side) is joined to the "Order Details" table (right side) but not vice versa._
60
+
61
+So, the generated SQL will looks like this:
62
+
63
+```sql
64
+[dbo].[Northwind].[Order Details] LEFT OUTER JOIN [dbo].[Northwind].[Orders]
65
+```
66
+
67
+You can also use a single table parameter to force that table to be joined with all other tables using a left join:
68
+
69
+```csharp
70
+AdHocContext.Driver.AddForcedLeftJoin("Orders");
71
+```
72
+
73
+##AddForcedLeftJoin and Constraints
74
+
75
+You can join tables in two ways on the Report Designer: manually using Advanced mode, and automatically using check-boxes.
76
+
77
+**Advanced mode:** In this case, you will be able to specify the join order and conditions. make sure that the join order corresponds to the order that you specified when you invoked the AddForcedLeftJoin method.
78
+
79
+Below is an example of how to join tables using Advanced mode:
80
+
81
+![]()
82
+
83
+**[[Simple (check-box) mode|/API/CodeSamples/ShowDataSourcesAsCheckboxes]]:** In this case, tables will be joined using existing database constraints. If your database does not use constraints or the constraints you need do not exist, you will have to [[create them|/API/CodeSamples/AddConstraint]]. In our example database, the constraints are already present. So we will go ahead and call AddForcedLeftJoin.
84
+
85
+```csharp
86
+AdHocContext.Driver.AddForcedLeftJoin("Orders", "Order Details");
87
+```
88
+
89
+Next we will select our tables in the Report Designer
90
+
91
+![](http://wiki.izenda.us/API/CodeSamples/AddForcedLeftJoin/addforcedleftjoin.png)
92
+
93
+_**Note:** You need to pay even more attention to the constraints in case you use the single-parameter overload of the AddForcedLeftJoin method.
94
+
95
+_**Note2:** It is preferable to use check-box mode with the AddForcedLeftJoin method. This is because you will have full control of joining and joining rules in this case.
96
+
97
+This example will generate the following SQL (Note that "Orders" and "Order Details" have been joined using LEFT OUTER JOIN):
98
+
99
+```sql
100
+SELECT *
101
+FROM [dbo].[Customers]
102
+INNER JOIN [dbo].[Orders] ON [dbo].[Orders].[CustomerID]=[dbo].[Customers].[CustomerID]
103
+LEFT OUTER JOIN [dbo].[Order Details] ON [dbo].[Orders].[OrderID]=[dbo].[Order Details].[OrderID]
104
+ AND [dbo].[Order Details].[ProductID]=[dbo].[Orders].[ProductID]
105
+ AND [dbo].[Order Details].[OrderID]=[dbo].[Orders].[OrderID]
106
+INNER JOIN [dbo].[Products] ON [dbo].[Order Details].[ProductID]=[dbo].[Products].[ProductID];
107
+```
108
+
109
+##Advanced Example
110
+
111
+Here is a full example of how to use AddForcedLeftJoin and [[AddConstraints|/API/CodeSamples/AddConstraints]]:
112
+
113
+```csharp
114
+AdHocContext.Driver.AddForcedLeftJoin("Orders", "Order Details");
115
+AdHocContext.Driver.AddConstraint("[Orders].[OrderID]", "[Order Details].[OrderID]");
116
+AdHocContext.Driver.AddForcedLeftJoin("Employees");
117
+```
... ...
\ No newline at end of file