[DOCS] Canvas elements (#42473)

* [DOCS] Canvas elements content

* Data source build out

* Display options and actions

* Reorganization, cycle interval, and organization actions

* Reorganized content

* Reorganization and clean up

* Added images

* Review comments pt 1

* Review comments pt 2

* Review comments pt 2

* Review comments pt 3

* Change on to in

* xpack

* Comments from Catherine

* Export image

* Final clean up

docs/canvas.asciidoc

@@ -1,4 +1,3 @@
-
 [role="xpack"]
 [[canvas]]
 = Canvas
@@ -28,10 +27,18 @@ For a quick overview of Canvas, watch link:https://www.youtube.com/watch?v=ZqvF_
 
 --
 
-include::canvas/canvas-getting-started.asciidoc[]
+include::canvas/canvas-tutorial.asciidoc[]
 
 include::canvas/canvas-workpad.asciidoc[]
 
+include::canvas/canvas-elements.asciidoc[]
+
+include::canvas/canvas-present-workpad.asciidoc[]
+
+include::canvas/canvas-share-workpad.asciidoc[]
+
+//include::canvas/canvas-expressions.asciidoc[]
+
 include::canvas/canvas-function-reference.asciidoc[]
 
 include::canvas/canvas-tinymath-functions.asciidoc[]

docs/canvas/canvas-elements.asciidoc

@@ -0,0 +1,268 @@
+[role="xpack"]
+[[element-intro]]
+== Showcase your data with elements
+
+Canvas _elements_ are the building blocks of your workpad. With elements, you can combine images, text, and visualizations to tell a story about your data.
+
+When you add elements to your workpad, you can:
+
+* <<connect-element-data,Connect the elements to your live data>>
+
+* <<configure-display-options,Choose how you want the element to appear on your workpad>>
+
+* <<configure-auto-refresh-interval,Change the data refresh interval>>
+
+* <<organize-element,Move and arrange elements on your workpad>>
+
+* <<element-save,Save your elements>>
+
+[float]
+[[add-canvas-element]]
+=== Add elements to your workpad
+
+Choose the elements to display on your workpad, then familiarize yourself with the element using the preconfigured demo data.
+
+. Click *Add element*.
+
+. In the *Elements* window, select the element you want to use. 
++
+[role="screenshot"]
+image::images/canvas-element-select.gif[Canvas elements]
+
+. Play around with the default settings and see what the element can do. 
+
+TIP: Want to use a different element? You can delete the element by selecting it, clicking the *Element options* icon in the top right corner, then selecting *Delete*.
+
+[float]
+[[connect-element-data]]
+=== Connect the element to your data
+
+When you are ready to move on from the demo data, connect the element to your own data.
+
+. Make sure that the element is selected, then select *Data*.
+
+. Click *Change your data source*.
+
+[float]
+[[elasticsearch-sql-data-source]]
+==== Connect to Elasticsearch SQL
+
+Access your data in Elasticsearch using the Elasticsearch SQL syntax.
+
+Unfamiliar with writing Elasticsearch SQL queries? For more information, refer to {ref}/sql-spec.html[SQL language].
+
+. Click *Elasticsearch SQL*.
+
+. In the *Elasticearch SQL query* box, enter your query, then *Preview* it.
+
+. If everything looks correct, *Save* it. 
+
+[float]
+[[elasticsearch-raw-doc-data-source]]
+==== Connect to Elasticsearch raw data
+
+Use the Lucene query syntax to use your raw data in Elasticsearch.
+
+For for more information about the Lucene query string sytax, refer to <<lucene-query,Lucene Query Syntax>>.
+
+. Click *Elasticsearch raw documents*.
+
+. In the *Index* field, enter the index pattern that you want to display. 
+
+. From the *Fields* dropdown, select the associated fields you want to display.
+
+. To sort the data, select an option from the *Sort Field* and *Sort Order* dropdowns.
+
+. For more targeted queries, enter a *Query* using the Lucene query string syntax. 
+
+. *Preview* the query. 
+
+. If your query looks correct, *Save* it. 
+
+[float]
+[[timelion-data-source]]
+==== Connect to Timelion
+
+Use <<timelion,Timelion>> queries to use your time series data. 
+
+. Click *Timelion*.
+
+. Enter a *Query* using the Lucene query string syntax. 
++
+For for more information about the Lucene query string syntax, refer to <<lucene-query,Lucene Query Syntax>>.
+
+. Enter the *Interval*, then *Preview* the query.
+
+. If your query looks correct, *Save* it. 
+
+[float]
+[[configure-display-options]]
+=== Choose the display options
+
+Choose how you want the elements to appear on your workpad.
+
+[float]
+[[data-display]]
+==== Specify how to display the data
+
+When you connect your element to a data source, the element often appears as a warning. To remove the error, specify the display options.
+
+. Click *Display*
+
+. Change the display options for the element. 
+
+[float]
+[[element-display-container]]
+==== Change the appearance of the element container
+
+Further define the appearance of the element container and border.
+
+. Next to *Element style*, click *+*, then select *Container style*.
+
+. Expand *Container style*.
+
+. Change the *Appearance* and *Border* options.
+ 
+[float]
+[[apply-element-styles]]
+==== Apply a set of styles
+
+To make your element look exactly the way you want, apply CSS overrides.
+
+. Next to *Element style*, click *+*, then select *CSS*.
+
+. Enter the *CSS*. For example, to center the Markdown element, enter:
++
+[source,js]
+--------------------------------------------------
+.canvasRenderEl h1 {
+text.align: center;
+}
+--------------------------------------------------
+
+. Click *Apply stylesheet*.
+
+[float]
+[[configure-auto-refresh-interval]]
+==== Change the data auto-refresh interval
+
+Increase or decrease how often your data refreshes on your workpad.
+
+. In the top left corner, click the *Control settings* icon.
+
+. Under *Change auto-refresh interval*, select the interval you want to use.
++
+[role="screenshot"]
+image::images/canvas-refresh-interval.png[Element data refresh interval]
+
+TIP: To manually refresh the data, click the *Refresh data* icon. 
+
+[float]
+[[organize-element]]
+=== Organize the elements on your workpad
+
+Choose where you want the elements to appear on your workpad.
+
+[float]
+[[move-canvas-elements]]
+==== Move elements
+
+Move the element to a preferred location on your workpad. As you move the element, notice the alignment lines that appear to help you place the element exactly where you want it.
+
+* Click and drag the element to your preferred location.
+
+* To move the element by 1 pixel, select the element, press and hold Shift, then use your arrow keys.
+
+* To move the element by 10 pixels, select the element, then use your arrow keys.
+
+[float]
+[[resize-canvas-elements]]
+==== Resize elements
+
+Make your elements bigger or smaller than the default size.
+
+. Select the element.
+
+. Click and drag the resize handles to the size you want.
+
+[float]
+[[align-canvas-elements]]
+==== Align elements
+
+Align two or more elements on your workpad.
+
+. Press and hold Shift, then select the elements you want to align.
+
+. Click the *Element options* icon in the top right corner, then select *Align elements*.
+
+. From the *Alignment* menu, select how you want to align the elements on the workpad.
++
+[role="screenshot"]
+image::images/canvas-align-elements.gif[Align elements]
+
+[float]
+[[distribute-canvas-elements]]
+==== Distribute elements
+
+Distribute three or more elements on your workpad.
+
+. Press and hold Shift, then select the elements you want to distribute.
+
+. Click the *Element options* icon in the top right corner, then select *Distribute elements*.
+
+. From the *Distribution* menu, select how you want to distribute the elements on the workpad.
++
+[role="screenshot"]
+image::images/canvas-distribute-elements.gif[Distribute elements]
+
+[float]
+[[change-element-order]]
+==== Change the element order
+
+Change the order of how the elements are displayed on your workpad.
+
+. Select an element.
+
+. In the top right corder, click the *Element options* icon. 
+
+. Select *Order*, then select the order that you want the element to appear.
+
+[float]
+[[zoom-in-out]]
+=== Use the zoom options
+
+In the upper left corner, click the *Zoom controls* icon, then select one of the options.
+
+[role="screenshot"]
+image::images/canvas-zoom-controls.png[Zoom controls]
+
+[float]
+[[element-save]]
+=== Save elements
+
+After you have made changes to elements, save them so that you can reuse them across all of your workpads.
+
+. Select the element that you want to save.
++
+To save a group of elements, press and hold Shift, then select the elements you want to save.
+
+. Click the *Save as new element* icon.
+
+. In the *Create new element* window, enter a *Name*.
+
+. Enter an optional *Description*, then click *Save*.
+
+. To access the element, click *Add element*, then select *My elements*.
+
+[float]
+[[add-more-pages]]
+=== Add pages
+
+When you have run out of room on your workpad page, add more pages.
+
+. Click *Page 1*, then click *+*.
+
+. On the *Page* editor panel on the right, select the page transition from the *Transition* dropdown. 
++
+[role="screenshot"]
+image::images/canvas-add-pages.gif[Add pages]

docs/canvas/canvas-expressions.asciidoc

@@ -0,0 +1,39 @@
+[[canvas-expression-editor]]
+=== Customize your element with the expression editor
+
+Each element is backed by an expression that represents the element style and data. To further define the appearance and behavior of the element, use the expression editor.
+
+. In the lower right corner, click *Expression editor*.
+
+. Edit the style and data parts of the expression that you want to change. 
+
+. Click *Run*.
+
+. If you like what you see, click *Close*.
+
+For information about the Canvas expression language, see <<canvas-function-reference,Canvas function reference>>.
+
+//Insert expression video.
+
+[float]
+[[canvas-expression-editor-example]]
+=== Example: Using the expression editor
+
+Build a complex element using expressions. 
+
+```
+image mode="contain" dataurl={
+asset {
+filters | essql
+query="SELECT host,response
+FROM kibana_sample_data_logs
+WHERE host='artifacts.elastic.co'
+ORDER BY timestamp DESC
+LIMIT 1"|
+alterColumn "response" type="number" |
+getCell "response" |
+if {compare lt to=400} then="asset-0a807073-d056-4c7b-9bf4-225b71e47243" else="asset-1343672d-7c02-4402-929e-0f8fef69cddd"
+}
+} | render
+
+```

docs/canvas/canvas-present-workpad.asciidoc

@@ -0,0 +1,27 @@
+[role="xpack"]
+[[canvas-present-workpad]]
+== Present your workpad
+
+When you are ready to present your workpad, use and enable the presentation options.
+
+[float]
+[[view-fullscreen-mode]]
+=== View your workpad in fullscreen mode
+
+In the upper left corner, click the *Enter fullscreen mode* icon.
+
+[role="screenshot"]
+image::images/canvas-fullscreen.png[Fullscreen mode]
+
+[float]
+[[enable-autoplay]]
+=== Enable autoplay 
+
+Automatically cycle through your workpads pages in fullscreen mode.
+
+. In the upper left corner, click the *Control settings* icon.
+
+. Under *Change cycling interval*, select the interval you want to use.
++
+[role="screenshot"]
+image::images/canvas-refresh-interval.png[Element data refresh interval]

docs/canvas/canvas-share-workpad.asciidoc

@@ -0,0 +1,48 @@
+[role="xpack"]
+[[workpad-share-options]]
+== Share your workpad
+
+When you are ready to share your workpad, create a PDF, or export your workpad.
+
+[float]
+[[create-workpad-pdf]]
+=== Create a PDF
+
+To view your workpad outside of Kibana, generate a PDF. 
+
+. If you are using a Gold or Platinum license, enable reporting in your `config/kibana.yml` file.
+
+. From your workpad, click the *Share workpad* icon in the upper left corner, then select *PDF reports*.
+
+. Click *Generate PDF*. 
++
+[role="screenshot"]
+image::images/canvas-generate-pdf.gif[Generate PDF]
+
+[float]
+[[export-workpad]]
+=== Export your workpad
+
+To share your workpad with another author, export it as a JSON file.
+
+[float]
+[[export-single-workpad]]
+==== Export a single workpad
+
+. From your workpad, click the *Share workpad* icon in the upper left corner.
+
+. Select *Download as JSON*.
++
+[role="screenshot"]
+image::images/canvas-export-workpad.png[Export single workpad]
+
+[float]
+[[export-multiple-workpads]]
+==== Export multiple workpads
+
+. Go to the *Canvas workpads* page.
+
+. Select the workpads you want to export
+
+. Click *Export*.
+

docs/canvas/canvas-tutorial.asciidoc

@@ -1,6 +1,6 @@
 [role="xpack"]
-[[canvas-getting-started]]
-== Getting started with Canvas
+[[canvas-tutorial]]
+== Canvas tutorial
 
 To get up and running with Canvas, use the following tutorial where you'll create a display for monitoring sales at an eCommerce store.
 
@@ -38,8 +38,6 @@ image::images/canvas-image-element.png[]
 
 You'll notice that the image is tagged as an asset, which allows you to reuse the image from *Manage assets*.
 
-TIP: Want to delete an element? Select the element, then press the delete button on your keyboard.
-
 [float]
 === Customize your data with metrics
 
@@ -154,9 +152,10 @@ Here are some things to try:
 
 //* Learn more about:
 
-//** {kibana-ref}/canvas-workpad[Workpads]
+** {kibana-ref}/canvas-workpad[Workpads]
+
+** {kibana-ref}/canvas-elements[Elements]
 //** Assets
-//** Data sources
-//** Elements
+//** Expressions
 
 * Deep dive into the {kibana-ref}/canvas-function-reference.html[expression language and functions] that drive Canvas.

docs/canvas/canvas-workpad.asciidoc

@@ -1,72 +1,93 @@
 [role="xpack"]
-[[canvas-workpad]]
-=== Create a workpad
+[[create-canvas-workpad]]
+== Create a workpad
 
-When you create a workpad, you'll start with a blank page, or you can choose a workpad that is already started for you. 
+A Canvas _workpad_ provides you with a workspace where you can build presentations of your live data.
+
+To create a workpad, you can:
+
+* <<blank-canvas-workpad,Build fully customizable presentations of your own data>>
+
+* <<canvas-template-workpad,Choose from a set of preconfigured workpad templates>>
+
+* <<import-canvas-workpad,Import a workpad that someone else has already started>>
+
+* <<sample-data-workpad,Gather inspiration from the {kib} sample data workpads>>
+
+[float]
+[[blank-canvas-workpad]]
+=== Start with a blank page
+
+To use the background colors, images, and data of your choice, start with a blank workpad. 
 
 . Open *Canvas*.
 
-. Choose one of the following options:
+. On the *Canvas workpads* page, click *Create workpad*.
 
-* To start with a single, blank workpad, click *Create workpad*.
+. Add a *Name* to your workpad.
 
-* To create a workpad from a template, select *Templates*, then select a preconfigured template.
+. In the *Width* and *Height* fields, specify the size. 
 
-* To import an existing workpad, click and drag a workpad JSON file to the *Import workpad JSON file* field.
-
-For advanced workpad examples, add a <<add-sample-data, sample Kibana data set>>, then select *Canvas* from the *View Data* dropdown list.
-
-For more workpad inspiration, go to the link:https://www.elastic.co/blog/[Elastic Blog]. 
-
-[float]
-=== Personalize your workpad
-
-To personalize your workpad, use the editor on the right.
-
-. Add a *Name* to your workpad, for example, `My Canvas Workpad`.
-
-. In the *Width* and *Height* fields, specify the size of your workpad. 
-
-. Select the layout for your workpad. 
+. Select the layout. 
 +
 For example, click *720p* for a traditional presentation layout.
 
 . Click the *Background color* picker, then select the background color for your workpad.
 +
-image::images/canvas-background-color-picker.gif[]
-
-. If you already know that you want to apply styles to the entire workpad, use the *Global CCS overrides*.
-
-.. Expand *Global CCS overrides*.
-
-.. Enter the CCS, then click *Apply stylesheet*.
+[role="screenshot"]
+image::images/canvas-background-color-picker.gif[Canvas color picker]
 
 [float]
-=== Share your workpad
+[[canvas-template-workpad]]
+=== Create a workpad from a template
 
-When you are ready to share your workpad, create a PDF, or export your workpad to another author.
+If you're unsure about where to start, you can use one of the preconfigured templates that come with Canvas.
+
+. Open *Canvas*.
+
+. On the *Canvas workpads* page, select *Templates*.
+
+. Click the preconfigured template that you want to use.
+
+. Add your own *Name* to the workpad.
 
 [float]
-==== Create a PDF of your workpad
+[[import-canvas-workpad]]
+=== Import an existing workpad
 
-To view your workpad outside of Kibana, generate a PDF. 
+When you want to use a workpad that someone else has already started, import the JSON file into Canvas.
 
-. If you are using a basic license, enable reporting in your `config/kibana.yml` file.
+. Open *Canvas*.
 
-. From your workpad, click the *Share workpad* icon in the upper left corner, then select *PDF reports*.
+. On the *Canvas workpads* page, click and drag the file to the *Import workpad JSON file* field.
 
-. Click *Generate PDF*. 
+[float]
+[[sample-data-workpad]]
+=== Use a sample data workpad
+
+Each of the sample data sets comes with a Canvas workpad that you can use for your own workpad inspiration.
+
+. Add a {kibana-ref}/add-sample-data.html[sample data set]. 
+
+. On the *Add Data to Kibana* page, click the *View data* dropdown list, then select *Canvas*.
 +
-image::images/canvas-generate-pdf.gif[]
+Need some more workpad inspiration? Check out the link:https://www.elastic.co/blog/[Elastic Blog]. 
 
 [float]
-==== Export your workpad
+[[apply-workpad-styles]]
+== Apply a set of styles to the entire workpad
 
-To share your workpads with another author, export your workpads as JSON files.
+To make your workpad look exactly the way you want, use the editor on the right to apply CSS overrides.
 
-. Go to the *Canvas workpads* page. 
+. Expand *Global CSS overrides*.
 
-. Choose one of the following options:
-* To export a single workpad, click the *Export* icon next to the workpad you want to export.
+. Enter the CSS. For example, to change the background on every page, enter:
++
+[source,js]
+--------------------------------------------------
+.canvasPage {
+background-color: #3990e6;
+}
+--------------------------------------------------
 
-* To export multiple workpads, select the workpads you want to export, then click *Export*.
+. Click *Apply stylesheet*.