Merge pull request #237 from plotly/defaults

Author: kMutagene

Plotly.NET.sln

@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
-# Visual Studio Version 16
-VisualStudioVersion = 16.0.29709.97
+# Visual Studio Version 17
+VisualStudioVersion = 17.0.31903.59
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "project", "project", "{BF60BC93-E09B-4E5F-9D85-95A519479D54}"
 	ProjectSection(SolutionItems) = preProject
@@ -44,6 +44,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{7B09CC0A-F
 		docs\00_1_image-export.fsx = docs\00_1_image-export.fsx
 		docs\00_2_display-options.fsx = docs\00_2_display-options.fsx
 		docs\00_3_chart-config.fsx = docs\00_3_chart-config.fsx
+		docs\00_4_templates.fsx = docs\00_4_templates.fsx
+		docs\00_5_defaults.fsx = docs\00_5_defaults.fsx
 		docs\01_0_axis-styling.fsx = docs\01_0_axis-styling.fsx
 		docs\01_1_errorbars.fsx = docs\01_1_errorbars.fsx
 		docs\01_2_multiple-charts.fsx = docs\01_2_multiple-charts.fsx

docs/00_0_basics.fsx

@@ -77,7 +77,7 @@ let myTrace = Trace("scatter") // create a scatter trace
 myTrace?x <- [0;1;2] // set the x property (the x dimension of the data)
 myTrace?y <- [0;1;2] // set the y property (the y dimension of the data)
 
-GenericChart.ofTraceObject myTrace // create a generic chart (layout and config are empty objects)
+GenericChart.ofTraceObject false myTrace // create a generic chart (layout and config are empty objects. When using useDefaults = true, default styling will be applied.)
 |> Chart.show
 
 (**

docs/00_4_templates.fsx

@@ -0,0 +1,97 @@
+(**
+---
+title: Chart Templates
+category: General
+categoryindex: 1
+index: 5
+---
+*)
+
+(*** hide ***)
+
+(*** condition: prepare ***)
+#r "nuget: Newtonsoft.JSON, 12.0.3"
+#r "nuget: DynamicObj"
+#r "../bin/Plotly.NET/netstandard2.0/Plotly.NET.dll"
+
+(*** condition: ipynb ***)
+#if IPYNB
+#r "nuget: Plotly.NET, {{fsdocs-package-version}}"
+#r "nuget: Plotly.NET.Interactive, {{fsdocs-package-version}}"
+#endif // IPYNB
+
+(** 
+# Chart Templates
+
+[![Binder]({{root}}img/badge-binder.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath={{fsdocs-source-basename}}.ipynb) 
+[![Script]({{root}}img/badge-script.svg)]({{root}}{{fsdocs-source-basename}}.fsx) 
+[![Notebook]({{root}}img/badge-notebook.svg)]({{root}}{{fsdocs-source-basename}}.ipynb)
+
+## Using premade templates
+
+premade templates can be accessed via the `ChartTemplates` module. In fact, the `ChartTemplates.plotly` template is always active by default (see [global defaults](./005_defaults.html))
+*)
+open Plotly.NET
+
+let lightMirrored = 
+    Chart.Point([1,2])
+    |> Chart.withTemplate ChartTemplates.lightMirrored
+
+(*** condition: ipynb ***)
+#if IPYNB
+lightMirrored
+#endif // IPYNB
+
+(***hide***)
+lightMirrored |> GenericChart.toChartHTML
+(***include-it-raw***)
+
+(**
+
+here are then contents of the template `plotly` which is used by default for all charts:
+
+*)
+
+open DynamicObj
+
+(***include-output***)
+ChartTemplates.plotly
+|> DynObj.print
+
+(**
+
+## Creating custom templates
+
+Chart Templates consist of a `Layout` object and a collection of `Trace` objects. Both are used to set default values for all possible styling options:
+*)
+
+open Plotly.NET.TraceObjects
+
+let layoutTemplate = 
+    Layout.init(
+        Title = Title.init("I will always be there now!")
+    )
+
+let traceTemplates = 
+    [
+        Trace2D.initScatter(
+            Trace2DStyle.Scatter(
+                Marker = Marker.init(Symbol = StyleParam.MarkerSymbol.ArrowLeft, Size = 20)
+            )
+        )
+    ]
+
+let myTemplate = Template.init(layoutTemplate, traceTemplates)
+
+let myTemplateExampleChart =
+    Chart.Point([1,2])
+    |> Chart.withTemplate myTemplate
+
+(*** condition: ipynb ***)
+#if IPYNB
+myTemplateExampleChart
+#endif // IPYNB
+
+(***hide***)
+myTemplateExampleChart |> GenericChart.toChartHTML
+(***include-it-raw***)

docs/00_5_defaults.fsx

@@ -0,0 +1,89 @@
+(**
+---
+title: Global default values
+category: General
+categoryindex: 1
+index: 6
+---
+*)
+
+(*** hide ***)
+
+(*** condition: prepare ***)
+#r "nuget: Newtonsoft.JSON, 12.0.3"
+#r "nuget: DynamicObj"
+#r "../bin/Plotly.NET/netstandard2.0/Plotly.NET.dll"
+
+(*** condition: ipynb ***)
+#if IPYNB
+#r "nuget: Plotly.NET, {{fsdocs-package-version}}"
+#r "nuget: Plotly.NET.Interactive, {{fsdocs-package-version}}"
+#endif // IPYNB
+
+(** 
+# Global default values
+
+[![Binder]({{root}}img/badge-binder.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath={{fsdocs-source-basename}}.ipynb) 
+[![Script]({{root}}img/badge-script.svg)]({{root}}{{fsdocs-source-basename}}.fsx) 
+[![Notebook]({{root}}img/badge-notebook.svg)]({{root}}{{fsdocs-source-basename}}.ipynb)
+
+Plotly.NET provides mutable global default values in the `Defaults` module.
+
+These values are always used in Chart generation. The default values are:
+
+|Value name|Value|
+|---|---|
+| DefaultWidth | `600` |
+| DefaultHeight | `600` |
+| DefaultConfig | `Config.init(Responsive = true)` |
+| DefaultDisplayOptions | `DisplayOptions.init()` |
+| DefaultTemplate | `ChartTemplates.plotly` |
+
+## Changing default values
+
+The following code replaces the default template from the global defaults:
+*)
+open Plotly.NET
+
+let before = Chart.Point([1,2])
+
+(*** condition: ipynb ***)
+#if IPYNB
+before
+#endif // IPYNB
+
+(***hide***)
+before |> GenericChart.toChartHTML
+(***include-it-raw***)
+
+Defaults.DefaultTemplate <- ChartTemplates.lightMirrored
+
+let after = Chart.Point([1,2])
+
+(*** condition: ipynb ***)
+#if IPYNB
+after
+#endif // IPYNB
+
+(***hide***)
+after |> GenericChart.toChartHTML
+(***include-it-raw***)
+
+
+(**
+## Ignoring global defaults
+
+All Chart functions have a `UseDefaults` argument, which when set to `false` will ignore all global defaults:
+*)
+
+
+let noDefaults = Chart.Point([1,2], UseDefaults = false)
+
+(*** condition: ipynb ***)
+#if IPYNB
+noDefaults
+#endif // IPYNB
+
+(***hide***)
+noDefaults |> GenericChart.toChartHTML
+(***include-it-raw***)

docs/03_2_3d-mesh-plots.fsx

@@ -74,7 +74,7 @@ let mesh3d =
             mesh3d?contour <- Contours.initXyz(Show=true)
             mesh3d
             )
-    |> GenericChart.ofTraceObject 
+    |> GenericChart.ofTraceObject true
 
 (*** condition: ipynb ***)
 #if IPYNB

docs/09_1_parallel-coords.fsx

@@ -86,7 +86,7 @@ let parcoords =
     dyn?line <- Line.init(Color=Color.fromString "blue")
 
     dyn
-    |> GenericChart.ofTraceObject
+    |> GenericChart.ofTraceObject true
 
 (*** condition: ipynb ***)
 #if IPYNB

docs/index.fsx

@@ -277,7 +277,7 @@ let trace =
     tmp?name <- "Hello from F#"
     tmp
 
-GenericChart.ofTraceObject(trace)
+GenericChart.ofTraceObject true trace
 |> GenericChart.setLayout layout
 
 (**

global.json

@@ -1,6 +1,6 @@
 {
     "sdk": {
       "version": "5.0.100",
-      "rollForward": "latestFeature"
+      "rollForward": "latestMajor"
     }
   }

src/Plotly.NET/ChartAPI/Chart.fs

@@ -59,7 +59,7 @@ type Chart =
 
         let trace = Trace2D.initScatter(id)
         trace.Remove("type") |> ignore
-        GenericChart.ofTraceObject trace
+        GenericChart.ofTraceObject false trace
         |> GenericChart.mapLayout ( fun l ->
             l
             |> Layout.AddLinearAxis(StyleParam.SubPlotId.XAxis 1,hiddenAxis())
@@ -976,10 +976,9 @@ type Chart =
     static member withTemplate(template: Template) =
         (fun (ch:GenericChart) ->
             ch
-            |> GenericChart.mapLayout (fun l ->
-                template |> DynObj.setValue l "template"
-                l
-                )
+            |> GenericChart.mapLayout (
+                Layout.style(Template = (template :> DynamicObj))
+            )
         )
 
     // TODO: Include withLegend & withLegendStyle