Salt (Wireframe)

Salt is a subproject included in PlantUML that may help you to design graphical interface or Website Wireframe or Page Schematic or Screen Blueprint.

The goal of this tool is to discuss about simple and sample windows.

You can use either @startsalt keyword, or @startuml followed by a line with salt keyword.

Basic widgets

A window must start and end with brackets. You can then define:

  • Button using [ and ].

  • Radio button using ( and ).

  • Checkbox using [ and ].

  • User text area using ".

  • Droplist using ^.

@startsalt
{
  Just plain text
  [This is my button]
  ()  Unchecked radio
  (X) Checked radio
  []  Unchecked box
  [X] Checked box
  "Enter text here   "
  ^This is a droplist^
}
@endsalt

Text area

Here is an attempt to create a text area:

@startsalt
{+
   This is a long
   text in a textarea
   .
   "                         "
}
@endsalt

Note: * the dot (.) to fill up vertical space; * the last line of space ("  ") to make the area wider.

[Ref. QA-14765]

Then you can add link::salt#6b6xvjbaj4gpk362kjkx[scroll bar]:

@startsalt
{SI
   This is a long
   text in a textarea
   .
   "                         "
}
@endsalt
@startsalt
{S-
   This is a long
   text in a textarea
   .
   "                         "
}
@endsalt

Open, close droplist

You can open a droplist, by adding values enclosed by ^, as:

@startsalt
{
  ^This is a closed droplist^ |
  ^This is an open droplist^^ item 1^^ item 2^ |
  ^This is another open droplist^ item 1^ item 2^
}
@endsalt

[Ref. QA-4184]

Using grid [\| and #, !, -, +]

A table is automatically created when you use an opening bracket {. And you have to use | to separate columns.

For example:

@startsalt
{
  Login    | "MyName   "
  Password | "****     "
  [Cancel] | [  OK   ]
}
@endsalt

Just after the opening bracket, you can use a character to define if you want to draw lines or columns of the grid :

Symbol Result

#

To display all vertical and horizontal lines

!

To display all vertical lines

-

To display all horizontal lines

+

To display external lines

@startsalt
{+
  Login    | "MyName   "
  Password | "****     "
  [Cancel] | [  OK   ]
}
@endsalt

Group box [^]

@startsalt
{^"My group box"
  Login    | "MyName   "
  Password | "****     "
  [Cancel] | [  OK   ]
}
@endsalt

[Ref. QA-5840]

Using separator [.., ==, ~~, --]

You can use several horizontal lines as separator.

@startsalt
{
  Text1
  ..
  "Some field"
  ==
  Note on usage
  ~~
  Another text
  --
  [Ok]
}
@endsalt

Tree widget [T]

To have a Tree, you have to start with {T and to use + to denote hierarchy.

@startsalt
{
{T
 + World
 ++ America
 +++ Canada
 +++ USA
 ++++ New York
 ++++ Boston
 +++ Mexico
 ++ Europe
 +++ Italy
 +++ Germany
 ++++ Berlin
 ++ Africa
}
}
@endsalt

Tree table [T]

You can combine trees with tables.

@startsalt
{
{T
+Region        | Population    | Age
+ World        | 7.13 billion  | 30
++ America     | 964 million   | 30
+++ Canada     | 35 million    | 30
+++ USA        | 319 million   | 30
++++ NYC       | 8 million     | 30
++++ Boston    | 617 thousand  | 30
+++ Mexico     | 117 million   | 30
++ Europe      | 601 million   | 30
+++ Italy      | 61 million    | 30
+++ Germany    | 82 million    | 30
++++ Berlin    | 3 million     | 30
++ Africa      | 1 billion     | 30
}
}
@endsalt

And add lines.

@startsalt
{
..
== with T!
{T!
+Region        | Population    | Age
+ World        | 7.13 billion  | 30
++ America     | 964 million   | 30
}
..
== with T-
{T-
+Region        | Population    | Age
+ World        | 7.13 billion  | 30
++ America     | 964 million   | 30
}
..
== with T+
{T+
+Region        | Population    | Age
+ World        | 7.13 billion  | 30
++ America     | 964 million   | 30
}
..
== with T#
{T#
+Region        | Population    | Age
+ World        | 7.13 billion  | 30
++ America     | 964 million   | 30
}
..
}
@endsalt

[Ref. QA-1265]

Enclosing brackets [{, }]

You can define subelements by opening a new opening bracket.

@startsalt
{
Name         | "                 "
Modifiers:   | { (X) public | () default | () private | () protected
                [] abstract | [] final   | [] static }
Superclass:  | { "java.lang.Object " | [Browse...] }
}
@endsalt

Adding tabs [/]

You can add tabs using {/ notation. Note that you can use HTML code to have bold text.

@startsalt
{+
{/ General | Fullscreen | Behavior | Saving }
{
{ Open image in: | ^Smart Mode^ }
[X] Smooth images when zoomed
[X] Confirm image deletion
[ ] Show hidden images
}
[Close]
}
@endsalt

Tab could also be vertically oriented:

@startsalt
{+
{/ General
Fullscreen
Behavior
Saving } |
{
{ Open image in: | ^Smart Mode^ }
[X] Smooth images when zoomed
[X] Confirm image deletion
[ ] Show hidden images
[Close]
}
}
@endsalt

Using menu [\*]

You can add a menu by using {* notation.

@startsalt
{+
{* File | Edit | Source | Refactor }
{/ General | Fullscreen | Behavior | Saving }
{
{ Open image in: | ^Smart Mode^ }
[X] Smooth images when zoomed
[X] Confirm image deletion
[ ] Show hidden images
}
[Close]
}
@endsalt

It is also possible to open a menu:

@startsalt
{+
{* File | Edit | Source | Refactor
 Refactor | New | Open File | - | Close | Close All }
{/ General | Fullscreen | Behavior | Saving }
{
{ Open image in: | ^Smart Mode^ }
[X] Smooth images when zoomed
[X] Confirm image deletion
[ ] Show hidden images
}
[Close]
}
@endsalt

Like it is possible to open a droplist:

@startsalt
{+
{* File | Edit | Source | Refactor }
{/ General | Fullscreen | Behavior | Saving }
{
{ Open image in: | ^Smart Mode^^Normal Mode^ }
[X] Smooth images when zoomed
[X] Confirm image deletion
[ ] Show hidden images
}
[Close]
}
@endsalt

[Ref. QA-4184]

Advanced table

You can use two special notations for table : * * to indicate that a cell with span with left * . to denotate an empty cell

@startsalt
{#
. | Column 2 | Column 3
Row header 1 | value 1 | value 2
Row header 2 | A long cell | *
}
@endsalt

Scroll Bars [S, SI, S-]

You can use {S notation for scroll bar like in following examples:

  • {S: for horizontal and vertical scrollbars

@startsalt
{S
Message
.
.
.
.
}
@endsalt
  • {SI : for vertical scrollbar only

@startsalt
{SI
Message
.
.
.
.
}
@endsalt
  • {S- : for horizontal scrollbar only

@startsalt
{S-
Message
.
.
.
.
}
@endsalt

Colors

It is possible to change text link::color[color] of widget.

@startsalt
{
  Just plain text
  [This is my default button]
  [This is my green button]
  [This is my disabled button]
  []  Unchecked box
  [X] Checked box
  "Enter text here   "
  ^This is a droplist^
  ^This is a disabled droplist^
  ^This is a red droplist^
}
@endsalt

[Ref. QA-12177]

Creole on Salt

You can use link::creole[Creole or HTML Creole] on salt:

@startsalt
{{^==Creole
  This is **bold**
  This is //italics//
  This is ""monospaced""
  This is --stricken-out--
  This is __underlined__
  This is ~~wave-underlined~~
  --test Unicode and icons--
  This is  long
  This is a <&code> icon
  Use image : 
}|
{^HTML Creole
 This is bold
  This is italics
  This is monospaced
  This is stroked
  This is underlined
  This is waved
  This is stroked
  This is underlined
  This is waved
  -- other examples --
  This is Blue
  This is Orange background
  This is big
}|
{^Creole line
You can have horizontal line

Or double line

Or strong line

Or dotted line ..My title.. Or dotted title ==Title== Or double-line title --Another title-- Or single-line title Enjoy! }| {^Creole list item test list 1 * Bullet list * Second item Sub item * Sub sub item * Third item

**test list 2**
# Numbered list
# Second item
## Sub item
## Another sub item
# Third item
}|
{^Mix on salt
  ==<color:Blue>Just plain text
  [This is my default button]
  [<b><color:green>This is my green button]
  [ ---<color:#9a9a9a>This is my disabled button-- ]
  []  <size:20><color:red>Unchecked box
  [X] <color:green>Checked box
  "//Enter text here//   "
  ^This is a droplist^
  ^<color:#9a9a9a>This is a disabled droplist^
  ^<b><color:red>This is a red droplist^
}}
@endsalt

== Pseudo sprite [<<, >>]

Using << and >> you can define a pseudo-sprite or sprite-like drawing and reusing it latter.

@startsalt
 {
 [X] checkbox|[] checkbox
 () radio | (X) radio
 This is a text|[This is my button]|This is another text
 "A field"|"Another long Field"|[A button]
 <>|other folder|<>
^Droplist^
}
@endsalt

[Ref. QA-5849]

== OpenIconic

OpenIconic is a very nice open source icon set. Those icons have been integrated into the link::creole[creole parser], so you can use them out-of-the-box. You can use the following syntax: <&ICON_NAME>.

@startsalt
{
  Login<&person> | "MyName   "
  Password<&key> | "****     "
  [Cancel <&circle-x>] | [OK <&account-login>]
}
@endsalt

The complete list is available on OpenIconic Website, or you can use the following special diagram:

@startuml
listopeniconic
@enduml

== Add title, header, footer, caption or legend

@startsalt
title My title
header some header
footer some footer
caption This is caption
legend
The legend
end legend

{+
  Login    | "MyName   "
  Password | "****     "
  [Cancel] | [  OK   ]
}

@endsalt

(See also: link::commons[Common commands])

== Zoom, DPI

=== Whitout zoom (by default)

@startsalt
{
  <&person> Login  | "MyName   "
  <&key> Password  | "****     "
  [<&circle-x> Cancel ] | [ <&account-login> OK   ]
}
@endsalt

=== Scale

You can use the scale command to zoom the generated image.

You can use either a number or a fraction to define the scale factor. You can also specify either width or height (in pixel). And you can also give both width and height: the image is scaled to fit inside the specified dimension.

@startsalt
scale 2
{
  <&person> Login  | "MyName   "
  <&key> Password  | "****     "
  [<&circle-x> Cancel ] | [ <&account-login> OK   ]
}
@endsalt

(See also: link::commons#zw5yrgax40mpk362kjbn[Zoom on Common commands])

=== DPI You can also use the `skinparam dpi`command to zoom the generated image.

@startsalt
skinparam dpi 200
{
  <&person> Login  | "MyName   "
  <&key> Password  | "****     "
  [<&circle-x> Cancel ] | [ <&account-login> OK   ]
}
@endsalt

== Include Salt "on activity diagram"

@startuml
(*) --> "
{{
salt
{+
an example
choose one option
()one
()two
[ok]
}
}}
" as choose

choose -right-> "
{{
salt
{+
please wait
operation in progress
<&clock>
[cancel]
}
}}
" as wait
wait -right-> "
{{
salt
{+
success
congratulations!
[ok]
}
}}
" as success

wait -down-> "
{{
salt
{+
error
failed, sorry
[ok]
}
}}
"
@enduml

It can also be combined with link::preprocessing#macro_definition[define macro].

@startuml
!unquoted procedure SALT($x)
"{{
salt
%invoke_procedure("_"+$x)
}}" as $x
!endprocedure

!procedure _choose()
{+
an example
choose one option
()one
()two
[ok]
}
!endprocedure

!procedure _wait()
{+
please wait
operation in progress
<&clock>
[cancel]
}
!endprocedure

!procedure _success()
{+
success
congratulations!
[ok]
}
!endprocedure

!procedure _error()
{+
error
failed, sorry
[ok]
}
!endprocedure

(*) --> SALT(choose)
-right-> SALT(wait)
wait -right-> SALT(success)
wait -down-> SALT(error)
@enduml

== Include salt "on while condition of activity diagram"

You can include salt on while condition of activity diagram.

@startuml
start
while (\n{{\nsalt\n{+\nPassword | "****     "\n[Cancel] | [  OK   ]}\n}}\n) is (Incorrect)
  :log attempt;
  :attempt_count++;
  if (attempt_count > 4) then (yes)
    :increase delay timer;
    :wait for timer to expire;
  else (no)
  endif
endwhile (correct)
:log request;
:disable service;
@enduml

[Ref. QA-8547]

== Include salt "on repeat while condition of activity diagram"

You can include salt on 'repeat while' condition of activity diagram.

@startuml
start
repeat :read data;
  :generate diagrams;
repeat while (\n{{\nsalt\n{^"Next step"\n  Do you want to continue? \n[Yes]|[No]\n}\n}}\n)
stop
@enduml

[Ref. QA-14287]

== Skinparam

You can use [only] some link::skinparam[skinparam] command to change the skin of the drawing.

Some example:

@startsalt
skinparam Backgroundcolor palegreen
{+
  Login    | "MyName   "
  Password | "****     "
  [Cancel] | [  OK   ]
}
@endsalt
@startsalt
skinparam handwritten true
{+
  Login    | "MyName   "
  Password | "****     "
  [Cancel] | [  OK   ]
}
@endsalt

[[#FFD700#FIXME]] 🚩 FYI, some other skinparam does not work with salt, as:

@startsalt
skinparam defaultFontName monospaced
{+
  Login    | "MyName   "
  Password | "****     "
  [Cancel] | [  OK   ]
}
@endsalt

== Style

You can use [only] some link::style-evolution[style] command to change the skin of the drawing.

Some example:

@startsalt

{+
  Login    | "MyName   "
  Password | "****     "
  [Cancel] | [  OK   ]
}
@endsalt

[[#FFD700#FIXME]] 🚩 FYI, some other style does not work with salt, as:

@startsalt

{+
  Login    | "MyName   "
  Password | "****     "
  [Cancel] | [  OK   ]
}
@endsalt

[Ref. QA-13460]

This page was built using the Antora default UI.

The source code for this UI is licensed under the terms of the MPL-2.0 license.