diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-confirmation.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-confirmation.adoc new file mode 100644 index 00000000..45a5c8e6 --- /dev/null +++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-confirmation.adoc @@ -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 <> +|=== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-multiselect.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-multiselect.adoc new file mode 100644 index 00000000..c0ff9bdb --- /dev/null +++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-multiselect.adoc @@ -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 <> +|=== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathinput.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathinput.adoc new file mode 100644 index 00000000..ac0c631e --- /dev/null +++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathinput.adoc @@ -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 <> +|=== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-render.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-render.adoc new file mode 100644 index 00000000..8717809c --- /dev/null +++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-render.adoc @@ -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 + +|=== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-singleselect.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-singleselect.adoc new file mode 100644 index 00000000..8666c124 --- /dev/null +++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-singleselect.adoc @@ -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 <> +|=== + +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] +---- +==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-stringinput.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-stringinput.adoc new file mode 100644 index 00000000..c67a35c8 --- /dev/null +++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-stringinput.adoc @@ -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 <> +|=== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui.adoc index 4e4c653f..aa12eb07 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui.adoc +++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui.adoc @@ -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 <> -|=== - -====== 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 <> -|=== - -====== 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 <> -|=== - -====== 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 <> -|=== - -====== 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 <> -|=== +include::using-shell-components-ui-multiselect.adoc[] diff --git a/spring-shell-docs/src/test/java/org/springframework/shell/docs/UiComponentSnippets.java b/spring-shell-docs/src/test/java/org/springframework/shell/docs/UiComponentSnippets.java index 96ff4084..5530aa7e 100644 --- a/spring-shell-docs/src/test/java/org/springframework/shell/docs/UiComponentSnippets.java +++ b/spring-shell-docs/src/test/java/org/springframework/shell/docs/UiComponentSnippets.java @@ -130,9 +130,9 @@ public class UiComponentSnippets { @ShellMethod(key = "component single", value = "Single selector", group = "Components") public String singleSelector() { - List> items = new ArrayList<>(); - items.add(SelectorItem.of("key1", "value1")); - items.add(SelectorItem.of("key2", "value2")); + SelectorItem i1 = SelectorItem.of("key1", "value1"); + SelectorItem i2 = SelectorItem.of("key2", "value2"); + List> items = Arrays.asList(i1, i2); SingleItemSelector> 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 i1 = SelectorItem.of("key1", "value1"); + SelectorItem i2 = SelectorItem.of("key2", "value2"); + List> items = Arrays.asList(i1, i2); + SingleItemSelector> component = new SingleItemSelector<>(getTerminal(), + items, "testSimple", null); + component.setDefaultExpose(i2); + // end::snippet8[] + component.setResourceLoader(getResourceLoader()); + component.setTemplateExecutor(getTemplateExecutor()); + SingleItemSelectorContext> context = component + .run(SingleItemSelectorContext.empty()); + String result = context.getResultItem().flatMap(si -> Optional.ofNullable(si.getItem())).get(); + return "Got value " + result; + } + } + } + }