Spring/spring-shell
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update docs

Browse Source
This commit is contained in:
Janne Valkealahti
2022-05-14 09:02:37 +01:00
parent 751c9e213e
commit 3599182536
8 changed files with 294 additions and 244 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
spring-shell-docs/src/main/asciidoc/using-shell-components-ui-confirmation.adoc Normal file
View File

@@ -0,0 +1,29 @@
[[using-shell-components-ui-confirmation]]
===== Confirmation
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Used to ask a simple confirmation from a user and essentially is
yes/no question.
====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet5]
----
====
image::images/component-confirmation-1.svg[text input]
Context object is `ConfirmationInputContext`.
[[confirmationinputcontext-template-variables]]
.ConfirmationInputContext Template Variables
|===
|Key |Description
|defaultValue
|Default value, either true or false.
|model
|Parent context variables <<textcomponentcontext-template-variables>>
|===

31
spring-shell-docs/src/main/asciidoc/using-shell-components-ui-multiselect.adoc Normal file
View File

@@ -0,0 +1,31 @@
[[using-shell-components-ui-multiselect]]
===== Multi Select
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Used to ask an items from a list.
====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet7]
----
====
image::images/component-multi-select-1.svg[text input]
Context object is `MultiItemSelectorContext`.
[[multiitemselectorcontext-template-variables]]
.MultiItemSelectorContext Template Variables
|===
|Key |Description
|values
|Returned values when component exists.
|rows
|Visible items where rows list contains maps of name, selected, onrow and enabled items.
|model
|Parent context variables <<selectorcomponentcontext-template-variables>>
|===

25
spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathinput.adoc Normal file
View File

@@ -0,0 +1,25 @@
[[using-shell-components-ui-pathinput]]
===== Path Input
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Used to ask a `Path` from a user and gives additional info about a path itself.
====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet4]
----
====
image::images/component-path-input-1.svg[text input]
Context object is `PathInputContext`.
[[pathinputcontext-template-variables]]
.PathInputContext Template Variables
|===
|Key |Description
|model
|Parent context variables <<textcomponentcontext-template-variables>>
|===

91
spring-shell-docs/src/main/asciidoc/using-shell-components-ui-render.adoc Normal file
View File

@@ -0,0 +1,91 @@
[[using-shell-components-ui-render]]
===== Component Render
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
There are two ways to implement component rendering, firstly fully
programmatically or secondly using a _ANTLR Stringtemplate_. Though
strictly speaking there is just a simple `Function` renderer interface
which takes `Context` as an input and outputs a list of `AttributedString`
but this allows to choose between _templating_ and _code_.
Templating is a good choice if you don't need to anything complex or
you just want to slightly modify existing component layouts. Rendering
via code then gives you flexibility to do whatever you need.
Programmatic way to render is simple as to create a `Function`:
====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet1]
----
====
And then hook it with a component:
====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet2]
----
====
Component have their own context but usually shares some functionality
from a parent component types, those context variables are shown below.
[[textcomponentcontext-template-variables]]
.TextComponentContext Template Variables
|===
|Key |Description
|resultValue
|Value after component renders its result.
|name
|Name of a component, aka its title.
|message
|Possible message set for component.
|messageLevel
|Level of a message, either INFO, WARN or ERROR
|hasMessageLevelInfo
|Return true if level is INFO, false otherwise.
|hasMessageLevelWarn
|Return true if level is WARN, false otherwise.
|hasMessageLevelError
|Return true if level is ERROR, false otherwise.
|input
|Raw user input.
|===
[[selectorcomponentcontext-template-variables]]
.SelectorComponentContext Template Variables
|===
|Key |Description
|name
|Name of a component, aka title.
|input
|Raw user input, mostly for filter.
|itemStates
|Full list of item states.
|itemStateView
|Visible list of item states.
|isResult
|Return if context is in a result mode.
|cursorRow
|Current cursor row in a selector
|===

42
spring-shell-docs/src/main/asciidoc/using-shell-components-ui-singleselect.adoc Normal file
View File

@@ -0,0 +1,42 @@
[[using-shell-components-ui-singleselect]]
===== Single Select
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Used to ask an item from a list and is essentially similar to simple
dropbox implementation.
====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet6]
----
====
image::images/component-single-select-1.svg[text input]
Context object is `SingleItemSelectorContext`.
[[singleitemselectorcontext-template-variables]]
.SingleItemSelectorContext Template Variables
|===
|Key |Description
|value
|Returned value when component exists.
|rows
|Visible items where rows list contains maps of name and selected items.
|model
|Parent context variables <<selectorcomponentcontext-template-variables>>
|===
It's possible to pre-select an item by defining it to get exposed. This is
useful if default is known and user can then just hit enter.
====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet8]
----
====

42
spring-shell-docs/src/main/asciidoc/using-shell-components-ui-stringinput.adoc Normal file
View File

@@ -0,0 +1,42 @@
[[using-shell-components-ui-stringinput]]
===== String Input
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Used to ask a simple text input from a user, optionally masking values
if content contains something sensitive.
====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet3]
----
====
image::images/component-text-input-1.svg[text input]
Context object is `StringInputContext`.
[[stringinputcontext-template-variables]]
.StringInputContext Template Variables
|===
|Key |Description
|defaultValue
|Default value if set, null otherwise.
|maskedInput
|Masked input value
|maskedResultValue
|Masked result value
|maskCharacter
|Mask character if set, null otherwise.
|hasMaskCharacter
|Is true if mask character is set, false otherwise.
|model
|Parent context variables <<textcomponentcontext-template-variables>>
|===

247
spring-shell-docs/src/main/asciidoc/using-shell-components-ui.adoc
View File

@@ -24,249 +24,14 @@ Build-in components generally follow logic:
components which better suited for defining interactive command flows.
====
===== Component Render
include::using-shell-components-ui-render.adoc[]
There are two ways to implement component rendering, firstly fully
programmatically or secondly using a _ANTLR Stringtemplate_. Though
strictly speaking there is just a simple `Function` renderer interface
which takes `Context` as an input and outputs a list of `AttributedString`
but this allows to choose between _templating_ and _code_.
include::using-shell-components-ui-stringinput.adoc[]
Templating is a good choice if you don't need to anything complex or
you just want to slightly modify existing component layouts. Rendering
via code then gives you flexibility to do whatever you need.
include::using-shell-components-ui-pathinput.adoc[]
Programmatic way to render is simple as to create a `Function`:
include::using-shell-components-ui-confirmation.adoc[]
====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet1]
----
====
include::using-shell-components-ui-singleselect.adoc[]
And then hook it with a component:
====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet2]
----
====
Component have their own context but usually shares some functionality
from a parent component types, those context variables are shown below.
[[textcomponentcontext-template-variables]]
.TextComponentContext Template Variables
|===
|Key |Description
|resultValue
|Value after component renders its result.
|name
|Name of a component, aka its title.
|message
|Possible message set for component.
|messageLevel
|Level of a message, either INFO, WARN or ERROR
|hasMessageLevelInfo
|Return true if level is INFO, false otherwise.
|hasMessageLevelWarn
|Return true if level is WARN, false otherwise.
|hasMessageLevelError
|Return true if level is ERROR, false otherwise.
|input
|Raw user input.
|===
[[selectorcomponentcontext-template-variables]]
.SelectorComponentContext Template Variables
|===
|Key |Description
|name
|Name of a component, aka title.
|input
|Raw user input, mostly for filter.
|itemStates
|Full list of item states.
|itemStateView
|Visible list of item states.
|isResult
|Return if context is in a result mode.
|cursorRow
|Current cursor row in a selector
|===
===== Build-in Components
====== String Input
Used to ask a simple text input from a user, optionally masking values
if content contains something sensitive.
====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet3]
----
====
image::images/component-text-input-1.svg[text input]
Context object is `StringInputContext`.
[[stringinputcontext-template-variables]]
.StringInputContext Template Variables
|===
|Key |Description
|defaultValue
|Default value if set, null otherwise.
|maskedInput
|Masked input value
|maskedResultValue
|Masked result value
|maskCharacter
|Mask character if set, null otherwise.
|hasMaskCharacter
|Is true if mask character is set, false otherwise.
|model
|Parent context variables <<textcomponentcontext-template-variables>>
|===
====== Path Input
Used to ask a `Path` from a user and gives additional info about a path itself.
====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet4]
----
====
image::images/component-path-input-1.svg[text input]
Context object is `PathInputContext`.
[[pathinputcontext-template-variables]]
.PathInputContext Template Variables
|===
|Key |Description
|model
|Parent context variables <<textcomponentcontext-template-variables>>
|===
====== Confirmation
Used to ask a simple confirmation from a user and essentially is
yes/no question.
====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet5]
----
====
image::images/component-confirmation-1.svg[text input]
Context object is `ConfirmationInputContext`.
[[confirmationinputcontext-template-variables]]
.ConfirmationInputContext Template Variables
|===
|Key |Description
|defaultValue
|Default value, either true or false.
|model
|Parent context variables <<textcomponentcontext-template-variables>>
|===
====== Single Select
Used to ask an item from a list and is essentially similar to simple
dropbox implementation.
====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet6]
----
====
image::images/component-single-select-1.svg[text input]
Context object is `SingleItemSelectorContext`.
[[singleitemselectorcontext-template-variables]]
.SingleItemSelectorContext Template Variables
|===
|Key |Description
|value
|Returned value when component exists.
|rows
|Visible items where rows list contains maps of name and selected items.
|model
|Parent context variables <<selectorcomponentcontext-template-variables>>
|===
====== Multi Select
Used to ask an items from a list.
====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet7]
----
====
image::images/component-multi-select-1.svg[text input]
Context object is `MultiItemSelectorContext`.
[[multiitemselectorcontext-template-variables]]
.MultiItemSelectorContext Template Variables
|===
|Key |Description
|values
|Returned values when component exists.
|rows
|Visible items where rows list contains maps of name, selected, onrow and enabled items.
|model
|Parent context variables <<selectorcomponentcontext-template-variables>>
|===
include::using-shell-components-ui-multiselect.adoc[]

31
spring-shell-docs/src/test/java/org/springframework/shell/docs/UiComponentSnippets.java
View File

@@ -130,9 +130,9 @@ public class UiComponentSnippets {
@ShellMethod(key = "component single", value = "Single selector", group = "Components")
public String singleSelector() {
List<SelectorItem<String>> items = new ArrayList<>();
items.add(SelectorItem.of("key1", "value1"));
items.add(SelectorItem.of("key2", "value2"));
SelectorItem<String> i1 = SelectorItem.of("key1", "value1");
SelectorItem<String> i2 = SelectorItem.of("key2", "value2");
List<SelectorItem<String>> items = Arrays.asList(i1, i2);
SingleItemSelector<String, SelectorItem<String>> component = new SingleItemSelector<>(getTerminal(),
items, "testSimple", null);
component.setResourceLoader(getResourceLoader());
@@ -171,4 +171,29 @@ public class UiComponentSnippets {
}
// end::snippet7[]
}
class Dump7 {
@ShellComponent
public class ComponentCommands extends AbstractShellComponent {
@ShellMethod(key = "component single", value = "Single selector", group = "Components")
public String singleSelector() {
// tag::snippet8[]
SelectorItem<String> i1 = SelectorItem.of("key1", "value1");
SelectorItem<String> i2 = SelectorItem.of("key2", "value2");
List<SelectorItem<String>> items = Arrays.asList(i1, i2);
SingleItemSelector<String, SelectorItem<String>> component = new SingleItemSelector<>(getTerminal(),
items, "testSimple", null);
component.setDefaultExpose(i2);
// end::snippet8[]
component.setResourceLoader(getResourceLoader());
component.setTemplateExecutor(getTemplateExecutor());
SingleItemSelectorContext<String, SelectorItem<String>> context = component
.run(SingleItemSelectorContext.empty());
String result = context.getResultItem().flatMap(si -> Optional.ofNullable(si.getItem())).get();
return "Got value " + result;
}
}
}
}