plotly · kMutagene · Jun 28, 2024 · Jun 13, 2024 · Jun 13, 2024 · Jun 28, 2024
diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json
@@ -6,13 +6,15 @@
       "version": "5.2.2",
       "commands": [
         "fantomas"
-      ]
+      ],
+      "rollForward": false
     },
     "fsdocs-tool": {
-      "version": "19.1.1",
+      "version": "20.0.1",
       "commands": [
         "fsdocs"
-      ]
+      ],
+      "rollForward": false
     }
   }
 }
diff --git a/Plotly.NET.sln b/Plotly.NET.sln
@@ -42,14 +42,11 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{7B09CC0A-F
 		docs\Dockerfile = docs\Dockerfile
 		docs\index.fsx = docs\index.fsx
 		docs\NuGet.config = docs\NuGet.config
-		docs\_template.html = docs\_template.html
+		docs\_head.html = docs\_head.html
 		docs\_template.ipynb = docs\_template.ipynb
 	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "reference", "reference", "{5219BAC7-ACE6-435F-A983-BC63DD7B745E}"
-	ProjectSection(SolutionItems) = preProject
-		docs\reference\_template.html = docs\reference\_template.html
-	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "content", "content", "{60FB82C0-F472-494E-BCF7-7B3C54212406}"
 	ProjectSection(SolutionItems) = preProject
@@ -153,6 +150,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "01_chart-layout", "01_chart
 		docs\chart-layout\axis-styling.fsx = docs\chart-layout\axis-styling.fsx
 		docs\chart-layout\errorbars.fsx = docs\chart-layout\errorbars.fsx
 		docs\chart-layout\layout_images.fsx = docs\chart-layout\layout_images.fsx
+		docs\chart-layout\legends.fsx = docs\chart-layout\legends.fsx
 		docs\chart-layout\multiple-charts.fsx = docs\chart-layout\multiple-charts.fsx
 		docs\chart-layout\shapes.fsx = docs\chart-layout\shapes.fsx
 		docs\chart-layout\sliders.fsx = docs\chart-layout\sliders.fsx

diff --git a/docs/_head.html b/docs/_head.html
@@ -0,0 +1,25 @@
+<meta charset="utf-8">
+<title>{{fsdocs-page-title}}</title>
+<meta name="author" content="{{fsdocs-authors}}">
+<meta name="description" content="Plotly.NET documentation for: {{fsdocs-page-title}}. Plotly.NET is an Interactive charting library for .NET programming languages.">
+
+<!-- Opengraph properties (https://ogp.me/) -->
+<meta property="og:title" content="Plotly.NET documentation for: {{fsdocs-page-title}}" />
+<meta property="og:url" content="{{root}}{{fsdocs-source-basename}}.html">
+<meta property="og:type" content="website" />
+<meta property="og:site_name" content="Plotly.NET" />
+<meta property="og:description" content="Plotly.NET documentation for: {{fsdocs-page-title}}. Plotly.NET is an Interactive charting library for .NET programming languages.">
+<meta property="og:image" content="{{root}}img/logo_meta_tags.png">
+
+<!-- Twitter cards -->
+<meta name="twitter:card" content="summary_large_image">
+<meta property="twitter:domain" content="{{root}}{{fsdocs-source-basename}}.html">
+<meta property="twitter:url" content="https://plotly.net">
+<meta name="twitter:title" content="Plotly.NET documentation for: {{fsdocs-page-title}}">
+<meta name="twitter:description" content="Plotly.NET documentation for: {{fsdocs-page-title}}. Plotly.NET is an Interactive charting library for .NET programming languages.">
+<meta name="twitter:image" content="{{root}}img/logo_meta_tags.png">
+
+<link rel="shortcut icon" type="image/x-icon" href="{{root}}/img/favicon.ico">
+<script src="https://cdn.plot.ly/plotly-2.27.1.min.js"></script>
+<script>MathJax = { tex: { inlineMath: [['$', '$'], ['\\(', '\\)']] } };</script>
+<script src="https://cdn.jsdelivr.net/npm/mathjax@3.2.0/es5/tex-svg.js"></script>
diff --git a/docs/_template.html b/docs/_template.html
diff --git a/docs/chart-layout/legends.fsx b/docs/chart-layout/legends.fsx
@@ -0,0 +1,196 @@
+(**
+---
+title: Legends
+category: Chart Layout
+categoryindex: 2
+index: 9
+---
+*)
+
+(*** hide ***)
+
+(*** condition: prepare ***)
+#r "nuget: Newtonsoft.JSON, 13.0.1"
+#r "nuget: DynamicObj, 2.0.0"
+#r "nuget: Giraffe.ViewEngine.StrongName, 2.0.0-alpha1"
+#r "../../src/Plotly.NET/bin/Release/netstandard2.0/Plotly.NET.dll"
+
+Plotly.NET.Defaults.DefaultDisplayOptions <-
+    Plotly.NET.DisplayOptions.init (PlotlyJSReference = Plotly.NET.PlotlyJSReference.NoReference)
+
+(*** condition: ipynb ***)
+#if IPYNB
+#r "nuget: Plotly.NET, {{fsdocs-package-version}}"
+#r "nuget: Plotly.NET.Interactive, {{fsdocs-package-version}}"
+#endif // IPYNB
+
+(** 
+# Legends
+
+[![Binder]({{root}}img/badge-binder.svg)](https://mybinder.org/v2/gh/plotly/plotly.net/gh-pages?urlpath=/tree/home/jovyan/{{fsdocs-source-basename}}.ipynb)&emsp;
+[![Notebook]({{root}}img/badge-notebook.svg)]({{root}}{{fsdocs-source-basename}}.ipynb)
+
+*Summary:* This example shows how to create Legends and add them to the Charts in F#.
+
+Let's first create some data for the purpose of creating example charts:
+
+*)
+
+open Plotly.NET
+
+let x = [ 1.; 2.; 3.; 4.; 5.; 6.; 7.; 8.; 9.; 10. ]
+let y = [ 2.; 1.5; 5.; 1.5; 3.; 2.5; 2.5; 1.5; 3.5; 1. ]
+
+// note that legends are not shown on charts with only one trace, 
+// which is why we need to set the trace to visible manually on this chart
+let simple_chart = Chart.Point(x, y, ShowLegend = true, Name = "test_chart")
+
+(**
+## Creating a legend
+
+Legends are `LayoutObjects` that can be added to a chart's `Layout`. The `LayoutLegend.init` function is used to create a legend object, which can then be added to a chart using the `Chart.withLegend` function:
+*)
+open Plotly.NET.LayoutObjects
+
+let my_legend =
+    Legend.init (
+        Title = Title.init("my first legend!"),
+        BorderColor = Color.fromString "black",
+        BorderWidth = 1
+    )
+
+let first_legend_chart =
+    simple_chart
+    |> Chart.withLegend my_legend
+
+(*** condition: ipynb ***)
+#if IPYNB
+first_legend_chart
+#endif // IPYNB
+
+(***hide***)
+first_legend_chart |> GenericChart.toChartHTML
+(***include-it-raw***)
+
+(**
+## Styling existing legends
+
+The `Chart.withLegendStyle` function can be used to update the style of an existing legend. 
+The following code will move the existing legend to the center bottom of the chart:
+*)
+
+let styled_legend_chart =
+    first_legend_chart
+    |> Chart.withLegendStyle(
+        Orientation = StyleParam.Orientation.Horizontal,
+        X = 0.5,
+        XAnchor = StyleParam.XAnchorPosition.Center
+    )
+
+(*** condition: ipynb ***)
+#if IPYNB
+styled_legend_chart
+#endif // IPYNB
+
+(***hide***)
+styled_legend_chart |> GenericChart.toChartHTML
+(***include-it-raw***)
+
+(**
+## Grouping legend items
+
+You can group multiple traces as a single legend item by setting the `LegendGroup` property of the individual traces to the same value:
+*)
+
+let grouped_legend_chart =
+    [
+        Chart.Point(x, y)
+        |> GenericChart.mapTrace (
+            Trace2DStyle.Scatter(
+                LegendGroup = "Group A",
+                LegendGroupTitle = (Title.init (Text = "Group A"))
+            )
+        )
+        Chart.Point(y, x)
+        |> GenericChart.mapTrace (
+            Trace2DStyle.Scatter(
+                LegendGroup = "Group A"
+            )
+        )
+        Chart.Point(y, y)
+        |> GenericChart.mapTrace (
+            Trace2DStyle.Scatter(
+                LegendGroup = "Group B",
+                LegendGroupTitle = (Title.init (Text = "Group B"))
+            )
+        )
+    ]
+    |> Chart.combine
+
+(*** condition: ipynb ***)
+#if IPYNB
+grouped_legend_chart
+#endif // IPYNB
+
+(***hide***)
+grouped_legend_chart |> GenericChart.toChartHTML
+(***include-it-raw***)
+
+(**
+## Multiple legends
+
+Starting with Plotly.NET 5.0.0, the multiple legends feature from plotl.js v2.22+ is supported.
+
+However, plotly.js has a [regression bug starting from 2.24.3](https://github.com/plotly/plotly.js/issues/7023), which causes multiple legends to not display correctly
+
+This means that the referenced plotly.js version has to be changed to <2.24.3 to use this feature. Note that features introduced in plotly.js/.NET after this version will not work on a chart using that reference.
+Future versions of plotly.js will hopefully fix this issue.
+
+Similarily to how multiple axes are handled, multiple legends are added by providing an additional `Id` argument when using the `Chart.withLegend` function:
+
+To select which legend a trace should belong to, use `Chart.withLegendAnchor` with the corresponding `id` argument.
+*)
+
+
+let multi_legend_chart =
+    [
+        Chart.Point(x, y)
+        |> Chart.withLegendAnchor 1
+        Chart.Point(y, x)
+        |> Chart.withLegendAnchor 2
+    ]
+    |> Chart.combine
+    |> Chart.withLegend(
+        Legend.init(
+            BorderColor = Color.fromKeyword Blue,
+            BorderWidth = 2,
+            Title = Title.init(
+                Text = "Legend 1"
+            )
+        )
+    )
+    |> Chart.withLegend(
+        Legend.init(
+            X = 0.75,
+            Y = 0.75,
+            BorderColor = Color.fromKeyword Red,
+            BorderWidth = 2,
+            Title = Title.init(
+                Text = "Legend 2"
+            )
+        ),
+        Id = 2
+    )
+    // set lower plotly.js version to avoid regression bug
+    |> Chart.withDisplayOptionsStyle(
+        PlotlyJSReference = Plotly.NET.PlotlyJSReference.CDN "https://cdn.plot.ly/plotly-2.23.0.min.js"
+    )
+
+(*** condition: ipynb ***)
+#if IPYNB
+multi_legend_chart
+#endif // IPYNB
+
+(***hide***)
+multi_legend_chart |> GenericChart.toEmbeddedHTML
+(***include-it-raw***)