docs: add render interface details

go-echarts · May 21, 2024 · 3c733b0 · 3c733b0
1 parent faa30f0
commit 3c733b0
Show file tree

Hide file tree

Showing 3 changed files with 96 additions and 0 deletions.
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -4,6 +4,7 @@
     - [Dive into go-echarts](en-us/dive-into)
     - [Chart Container](en-us/chart-container)
     - [Event and Action](en-us/event-and-action)
+    - [Chart Render](en-us/render)
 - Advanced
     - [Render to Image](en-us/render-to-image)
 - Chart Configration

diff --git a/docs/en-us/render.md b/docs/en-us/render.md
@@ -0,0 +1,86 @@
+# Render
+
+Render is an interface for render charts, alias the `Renderer`.
+
+```go
+// Renderer
+// Any kinds of charts have their render implementation, and
+// you can define your own render logic easily.
+type Renderer interface {
+    Render(w io.Writer) error
+    RenderContent() []byte
+    RenderSnippet() ChartSnippet
+}
+```
+
+## `Render(w io.Writer) error`
+
+The `Render(w io.Writer) error` function aims to generate chart to target `io.Writer`.  
+Underlying, it depends on the `RenderContent() []byte` to generate the chart bytes streaming.
+
+## `RenderContent() []byte`
+
+The `RenderContent() []byte` uses templates to generate the chart bytes streaming.
+i.e.
+> The `BaseRender` is a base Render with default implementations of Renderer.
+> It helps you can only implement your own necessary functions of `Renderer`.
+
+```go
+type chartRender struct {
+    BaseRender
+    c interface{}
+    // before the pre-process functions for chart render, it only calls once to support multi renders
+    before []func ()
+}
+
+```
+
+!> You need run the `before` functions to make sure all the charts options set in place.
+
+## `RenderSnippet() ChartSnippet`
+
+The `RenderSnippet() ChartSnippet` function can extract the element(chart container), the script
+and the options from a chart.
+
+!> It only works for Chart, Page is unsupported.
+
+e.g.
+> Full Code: [examples/renderer.go](https://github.com/go-echarts/examples/blob/master/examples/renderer.go)
+```go
+	bar := charts.NewBar()
+	bar.SetGlobalOptions(charts.WithTitleOpts(opts.Title{
+		Title:    "Bar chart for Snippets",
+	}))
+
+	bar.SetXAxis([]string{"Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"}).
+		AddSeries("Category A", generateBarItems()).
+		AddSeries("Category B", generateBarItems())
+
+	// pure extracted snippets
+	chartSnippet := bar.RenderSnippet()
+
+	tmpl := "{{.Element}} {{.Script}} {{.Option}}"
+	t := template.New("snippet")
+	t, err := t.Parse(tmpl)
+	if err != nil {
+		panic(err)
+	}
+
+	data := struct {
+		Element template.HTML
+		Script  template.HTML
+		Option  template.HTML
+	}{
+		Element: template.HTML(chartSnippet.Element),
+		Script:  template.HTML(chartSnippet.Script),
+		Option:  template.HTML(chartSnippet.Option),
+	}
+
+	// rerender the snippets out
+	err = t.Execute(os.Stdout, data)
+	if err != nil {
+		panic(err)
+	}
+
+```
+
diff --git a/docs/index.html b/docs/index.html
@@ -9,6 +9,15 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
     <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
 </head>
+<!-- Google tag (gtag.js) -->
+<script async src="https://www.googletagmanager.com/gtag/js?id=G-8J06Y8KKE8"></script>
+<script>
+    window.dataLayer = window.dataLayer || [];
+    function gtag(){dataLayer.push(arguments);}
+    gtag('js', new Date());
+
+    gtag('config', 'G-8J06Y8KKE8');
+</script>
 <body>
 <div id="app">Loading ...</div>
 <script>