Package org.apache.juneau.console.views

Class RibbonItem

java.lang.Object
org.apache.juneau.console.views.RibbonItem
public final class RibbonItem extends Object
One ribbon (toolbar) entry above a table.

The ribbon runtime (juneau-ribbon.js) implements every behavior; this type only names it and carries its parameters. toMap() produces the same {type, ...} entry the runtime reads from viewDef.ribbon.

Setters are not gated per item type, but toMap() fails loudly rather than emit a key the runtime ignores for that type (for example form on a refresh, or symbol on an optionGroup), and checks the invariants the runtime cannot: a top-level option needs column or param (exactly one) plus a value, and a group's default must name a member. Group members take only id, title, symbol, column, param and value.

Example:

table.ribbon( RibbonItem.collapseAll(), RibbonItem.export("copy", "csv").optional("excel", "pdf"), RibbonItem.option("dropped-only").title("Dropped only").column("status").value("$eq(DROPPED)").persist(true), RibbonItem.optionGroup("phase", RibbonItem.option("pending").column("phase").value("$in(Waiting)"), RibbonItem.option("done").column("phase").value("$in(Completed)") ).defaultOption("pending"), RibbonItem.dialog("add").title("Add repo").form("/rest/skill-repos/add-modal") .endpoint("/rest/skill-repos/new").method(RowAction.Method.POST) .onSuccess(RowAction.OnSuccess.REDRAW), RibbonItem.refresh()); RibbonItem.refresh().title("Refresh tasks").target("tasks"); RibbonItem.publish("Focus east", "app.region-picked", Map.of("region", "east"));

Since:
10.0.0

  • Method Details

    • divider

      public static RibbonItem divider()
      A visual separator between ribbon items; it also closes any open item cluster.
      Returns:
      A new RibbonItem.

    • refresh

      public static RibbonItem refresh()
      The ribbon's reload-the-table button.
      Returns:
      A new RibbonItem.

    • collapseAll

      public static RibbonItem collapseAll()
      The ribbon's collapse-all-detail-rows button.
      Returns:
      A new RibbonItem.

    • pausePolling

      public static RibbonItem pausePolling()
      The ribbon's pause/resume auto-refresh toggle.
      Returns:
      A new RibbonItem.

    • export

      public static RibbonItem export(String... buttons)
      The ribbon's export menu, offering the named buttons.

      A button here is required: if its library is missing at runtime (JSZip for excel, pdfMake for pdf) it renders disabled and logs an error. Use optional(String...) for buttons that should simply be omitted when their library is absent. The menu may consist of optional buttons alone, but toMap() rejects one with no buttons at all.

      Parameters:
      buttons - The required buttons, each one of copy, csv, print, excel or pdf.
      Returns:
      A new RibbonItem.
      Throws:
      IllegalArgumentException - If buttons names a button not in that set.

    • dialog

      public static RibbonItem dialog(String actionId)
      A ribbon button that opens a modal dialog.
      Parameters:
      actionId - This item's stable id (also the dialog's logical name). Must not be null or blank.
      Returns:
      A new RibbonItem.
      Throws:
      IllegalArgumentException - If actionId is null or blank.

    • option

      public static RibbonItem option(String id)
      A server-query toggle button.

      Set exactly one of column(String) (a BeanQuery $-expression value against that column) or param(String) (a URL query parameter). Checked by toMap().

      Parameters:
      id - The toggle's stable id. Must not be null or blank.
      Returns:
      A new RibbonItem.
      Throws:
      IllegalArgumentException - If id is null or blank.

    • optionGroup

      public static RibbonItem optionGroup(String id, RibbonItem... members)
      A group of mutually exclusive option toggles.

      A member may omit column/param/value; selecting it then applies no filter (an "All" member).

      Parameters:
      id - The group's stable id. Must not be null or blank.
      members - The members, each created by option(String). Must not be empty.
      Returns:
      A new RibbonItem.
      Throws:
      IllegalArgumentException - If id is null or blank, or members is empty or holds anything other than an option.

    • publish

      public static RibbonItem publish(String title, String topic, Map<String,Object> payload)
      A ribbon button that publishes a message when clicked. The topic must be a custom topic declared in the page's topics or a card's publishes, or cmd:<cardId>; the console's wiring check enforces that. Rendered only on a console page (no bus, no button).
      Parameters:
      title - The button label.
      topic - The topic to publish.
      payload - A JSON-serializable payload, or null for {}.
      Returns:
      A new RibbonItem.
      Throws:
      IllegalArgumentException - If title or topic is null or blank.

    • target

      public RibbonItem target(String cardId)
      Sends this item's command to another card instead of its own table. Accepted on refresh, collapseAll, pausePolling, option and optionGroup; toMap() rejects it elsewhere.
      Parameters:
      cardId - The target card id; the console's wiring check verifies it names a card that handles the op.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If cardId is not a valid card id.

    • visibleWhen

      public RibbonItem visibleWhen(VisibilityRule... rules)
      Hides this item unless every rule matches the console's facts. Evaluated by the client; this only serializes the rules. Accepted on every item type; not on an optionGroup member.
      Parameters:
      rules - The rules, ANDed together. None clears them.
      Returns:
      This object.

    • id

      public RibbonItem id(String v)
      Sets this item's stable id.

      The id is emitted on the item's ribbon entry, where it is scoped to its card (it is not stamped as a DOM id). toMap() rejects an id on the types the runtime ignores it for (divider and export).

      Parameters:
      v - The id. Must not be null or blank.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If v is null or blank.

    • title

      public RibbonItem title(String v)
      Sets this item's title/label text.

      On an optionGroup the title is not drawn; it becomes the group's accessible name (role="group" with aria-label).

      Parameters:
      v - The title. Can be null to unset.
      Returns:
      This object.

    • group

      public RibbonItem group(String v)
      Clusters this item with adjacent items sharing the same group name.
      Parameters:
      v - The group name. Can be null to unset.
      Returns:
      This object.

    • appearance

      public RibbonItem appearance(String v)
      Sets how this item's button is drawn.
      Parameters:
      v - The appearance; currently only icon. Can be null to unset.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If v is not a known appearance.

    • symbol

      public RibbonItem symbol(String v)
      Sets the icon name overriding this item's default icon.
      Parameters:
      v - The icon name. Can be null to unset.
      Returns:
      This object.

    • form

      public RibbonItem form(String url)
      Sets the form-source URL supplying a dialog item's input fields.
      Parameters:
      url - The form URL. Can be null to unset.
      Returns:
      This object.

    • endpoint

      public RibbonItem endpoint(String url)
      Sets the URL a dialog item's form submits to.
      Parameters:
      url - The endpoint URL. Can be null to unset.
      Returns:
      This object.

    • method

      public RibbonItem method(RowAction.Method m)
      Sets the non-safe HTTP method a dialog item's form submits with.
      Parameters:
      m - The method. Must not be null.
      Returns:
      This object.

    • onSuccess

      public RibbonItem onSuccess(RowAction.OnSuccess s)
      Sets what the runtime does with a successful dialog submission.
      Parameters:
      s - The success behavior. Must not be null.
      Returns:
      This object.

    • optional

      public RibbonItem optional(String... names)
      Adds export buttons that are omitted, rather than rendered disabled, when their library is absent.
      Parameters:
      names - The buttons, each excel or pdf.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If a name is not one of those, or is already a required button.

    • column

      public RibbonItem column(String name)
      Scopes an option to a table column.
      Parameters:
      name - The row-data column name. Can be null to unset.
      Returns:
      This object.

    • param

      public RibbonItem param(String name)
      Scopes an option to a URL query parameter.
      Parameters:
      name - The parameter name. Can be null to unset.
      Returns:
      This object.

    • value

      public RibbonItem value(String v)
      Sets an option's value: a BeanQuery $-expression for a column-scoped option, or the raw parameter value for a param-scoped one.
      Parameters:
      v - The value. Can be null to unset.
      Returns:
      This object.

    • persist

      public RibbonItem persist(boolean v)
      Sets whether this option's (or group's) state is remembered across page loads.
      Parameters:
      v - Whether to persist.
      Returns:
      This object.

    • defaultOn

      public RibbonItem defaultOn()
      Marks an option as on until the user (or persisted state) says otherwise.
      Returns:
      This object.

    • defaultOption

      public RibbonItem defaultOption(String memberId)
      Selects an optionGroup member until the user (or persisted state) says otherwise.
      Parameters:
      memberId - The member's id; checked against the members by toMap().
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If this item is a plain option (use defaultOn()).

    • deselectable

      public RibbonItem deselectable(boolean v)
      Lets an optionGroup's selected member be clicked again to deselect it.
      Parameters:
      v - Whether the group is deselectable.
      Returns:
      This object.

    • toMap

      public JsonMap toMap()
      Builds this item's ribbon entry.
      Returns:
      The entry, type first, then only the keys that were set.
      Throws:
      IllegalArgumentException - If the item sets a key the runtime ignores for its type, a top-level option sets neither or both of column and param or no value, an export has no buttons, or a default does not suit the item (an option takes defaultOn(); an optionGroup takes defaultOption(String) naming a member), or a target is set on a type the runtime does not route.

    • validate

      public static void validate(Map<?,?> item)
      Validates an authored ribbon item map (for example from a JSON5 card body) with exactly the rules toMap() applies to a built item: a known type, only keys the runtime reads, an export with at least one valid button, an option with exactly one of column or param plus a value, a default that suits the item, a valid appearance and target, a well-formed visibleWhen (a list of field/op rules with a known op), and the same rules for each optionGroup member.
      Parameters:
      item - The authored item. Must not be null.
      Throws:
      IllegalArgumentException - If the item is not valid.