Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[skip-ci] Expression Lifecycle Docs #51494

Merged
merged 21 commits into from
Jan 2, 2020
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
adding shaun changes
  • Loading branch information
timductive committed Jan 2, 2020

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
commit 86e4f7a5c6f558f167fdca6fe984424b56db2958
29 changes: 29 additions & 0 deletions docs/canvas/canvas-expression-lifecycle.asciidoc
Original file line number Diff line number Diff line change
@@ -2,6 +2,35 @@
[[canvas-expression-lifecycle]]
== Canvas expression lifecycle

[[canvas-understanding-the-syntax]]
=== Understanding the Syntax

Elements in Canvas are all created using an *expression language* that defines how to retrieve, manipulate, and ultimately visualize data. The goal is to allow users to do most of what they need without having to edit or even know that it exists, but learning how it works unlocks a lot of the application’s power.

Learning a new language can be a chore, but the *expressions* in Canvas are intentionally readable, and once you understand the syntax, you will hopefully find them pretty approachable. The easiest way to explain how they work is by walking through an example expression and explaining what happens step by step.
timductive marked this conversation as resolved.
Show resolved Hide resolved

[[canvas-expressions-always-start-with-a-function]]
=== Expressions Always Start with a Function
timductive marked this conversation as resolved.
Show resolved Hide resolved

Expressions simply execute <<canvas-function-reference, functions>>, in a specific order, which produce some kind of output. That output can then be piped into another function, and another after that, until it produces the output you need. Let’s start with the following expression, which uses random data available in Canvas to produce a table.
timductive marked this conversation as resolved.
Show resolved Hide resolved

*[Note] You can follow along*
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since line 17 is implied, I would remove it.


You can run all of the following expressions to see the output yourself
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about simply:

Run the following expression:


[source,text]
----
filters
| demodata
| table
| render
----

This expression starts out with the <<filters_fn, function>> function, which provides the value of any time filters or dropdown filters in the workpad. This is then piped to <<demodata_fn, demodata>>, a function that returns exactly what you expect, demo data. Because the <<demodata_fn, demodata>> function receives the filter information from the <<filters_fn, filters>> function before it, it applies those filters to reduce the set of data it returns. We call the output from the previous function _context_.

The filtered <<demodata_fn, demodata>> then becomes the _context_ of the next function, <<table_fn, table>>, which creates a table visualization from this data set. This function isn’t strictly required, but by being explicit you also have the option of providing arguments to control things like the font used in the table. Finally, that output becomes the _context_ of the next function, <<render_fn, render>>, and like <<table_fn, table>> before it, this function isn’t required either. But, just like before, using it allows access to other arguments, such as styling the border of the element or injecting custom CSS.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

demodata > demo data

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would remove the then between >> and becomes

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the second sentence, I would replace This with The next function, or The second function.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would put a comma between explicit and you

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the last two sentences, how about:

The final output becomes the context of the next <<render_fn, render>> function. Like the <<table_fn, table>>, the render function isn't required either, but it allows access to the other arguments ...



[[canvas-function-can-take-arguments]]
=== Functions Can Take Arguments

2 changes: 2 additions & 0 deletions docs/user/canvas.asciidoc
Original file line number Diff line number Diff line change
@@ -42,3 +42,5 @@ include::{kib-repo-dir}/canvas/canvas-expression-lifecycle.asciidoc[]
include::{kib-repo-dir}/canvas/canvas-function-reference.asciidoc[]

include::{kib-repo-dir}/canvas/canvas-tinymath-functions.asciidoc[]

include::{kib-repo-dir}/canvas/canvas-expression-lifecycle.asciidoc[]