001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.console.views;
018
019import static org.apache.juneau.commons.utils.Shorts.*;
020
021import java.util.*;
022
023import org.apache.juneau.commons.bean.*;
024import org.apache.juneau.console.widgets.Op;
025
026/**
027 * A per-row action descriptor in the {@code VIEW_META} wire contract (the transport-agnostic
028 * "row-action intent" model).
029 *
030 * <p>
031 * An FTL {@code <@card type="datatables">} {@code VIEW_META} catalog declares zero or more of these via
032 * {@code rowActions}; the
033 * {@code juneau-views.js} runtime renders each as a row-menu item and, on activation, submits the declared
034 * {@link #endpoint} with the declared {@link #method} as a JSON request carrying the process's CSRF token.
035 *
036 * <h2 class='section'>The frozen wire schema</h2>
037 * <p>
038 * This is the <b>complete</b> set of wire fields; it is pinned in full now so that later waves (a future declarative
039 * modal/form + typed result) can rely on it verbatim without forcing another fail-loud
040 * contract bump.  Only {@link #id} is required; every other field is optional and is omitted from the serialized
041 * form when unset (null-valued properties are dropped).
042 * <table class='styled'>
043 *    <caption>Row action fields</caption>
044 *    <tr><th>Field</th><th>Type / tokens</th><th>Meaning</th></tr>
045 *    <tr><td>{@code id}</td><td>string</td><td>Stable action id (menu-item key; also the submit's logical name).</td></tr>
046 *    <tr><td>{@code label}</td><td>string</td><td>The menu-item text.</td></tr>
047 *    <tr><td>{@code icon}</td><td>string</td><td>Optional glyph name (resolved by the shared icon registry).</td></tr>
048 *    <tr><td>{@code endpoint}</td><td>string</td><td>The URL the action submits to; may carry a {@code {property}}
049 *       token substituted from the current row - a value that cannot be resolved refuses the submission (see
050 *       {@link #endpoint(String) endpoint}).</td></tr>
051 *    <tr><td>{@code method}</td><td>{@code POST}|{@code PUT}|{@code PATCH}|{@code DELETE}</td>
052 *       <td>The non-safe HTTP method (see {@link Method}).</td></tr>
053 *    <tr><td>{@code confirm}</td><td>string</td><td>Optional confirmation prompt shown before the submit.</td></tr>
054 *    <tr><td>{@code form}</td><td>string</td><td>Optional form-source URL supplying the action's input fields;
055 *       may carry a {@code {property}} token substituted from the current row before the confirmation GET
056 *       (see {@link #form(String) form}).  Blank/absent {@code form} is the confirm-only local path.</td></tr>
057 *    <tr><td>{@code present}</td><td>{@code page}|{@code dialog}|{@code inline}</td>
058 *       <td>How the action's form/confirmation is presented (see {@link Present}); {@code inline} keeps it out of the row menu.</td></tr>
059 *    <tr><td>{@code onSuccess}</td><td>{@code redraw}|{@code mergeRow}|{@code navigate}</td>
060 *       <td>What the runtime does with a successful result (see {@link OnSuccess}).</td></tr>
061 *    <tr><td>{@code enabledWhen}</td><td>{@code [{field,op,value?,reason}, ...]}</td>
062 *       <td>Row-state disable-with-reason rules (see {@link #enabledWhen(String,Op,Object,String)}).</td></tr>
063 *    <tr><td>{@code visibleWhen}</td><td>{@code [{field,op,value?}, ...]}</td>
064 *       <td>Row-state visibility rules (see {@link #visibleWhen(VisibilityRule...)}).</td></tr>
065 *    <tr><td>{@code tone}</td><td>{@code default}|{@code danger}</td>
066 *       <td>Styling of the confirmation (see {@link Tone}); {@code danger} focuses Cancel first.</td></tr>
067 *    <tr><td>{@code confirmLabel}</td><td>string</td>
068 *       <td>Text of the confirm button; defaults to the action's {@code label}.</td></tr>
069 *    <tr><td>{@code confirmRenderer}</td><td>string</td>
070 *       <td>Name of a confirm renderer registered with the client runtime; absent means the built-in modal.
071 *       Like {@code confirm}, it is not consulted when an inline cell edit commits (that never prompts).</td></tr>
072 * </table>
073 *
074 * <p>
075 * {@code enabledWhen} was added after this schema was first frozen; like {@code ModalDef#barSlot}, it is
076 * additive-only (<jk>null</jk> when unset, omitted from the serialized form) and its presence does not bump
077 * {@code VIEW_META} &mdash; a {@link RowAction} that leaves it unset serializes
078 * unchanged, and old {@code juneau-views.js} ignores the unknown key.
079 *
080 * <h2 class='section'>Why {@link #method} cannot be a safe method</h2>
081 * <p>
082 * {@link Method} enumerates only {@code POST}/{@code PUT}/{@code PATCH}/{@code DELETE}, so a safe (CSRF-exempt)
083 * method cannot be declared at all &mdash; a build-time refusal by construction.  This mirrors the server boundary:
084 * {@link org.apache.juneau.rest.server.MethodSafety} fails any {@code @Mutating} operation bound to a safe method at
085 * startup, and {@link org.apache.juneau.rest.server.filter.LoopbackBoundary} applies its Origin/CSRF/JSON checks
086 * only to non-safe methods.  A mutating action bound to {@code GET} would be a CSRF-able write; the type system
087 * forbids expressing one.
088 *
089 * <h2 class='section'>Per-row {@code {property}} substitution in {@link #endpoint} and {@link #form}</h2>
090 * <p>
091 * {@link #endpoint(String) endpoint} and {@link #form(String) form} may each carry a {@code {property}} token
092 * (e.g. {@code {id}}, as in the example below) that the client-side runtime substitutes from the row &mdash; the
093 * SAME mechanism, same token grammar, and same per-value escaping as the {@code linked} cell renderer's
094 * {@code href} interpolation.  Unlike a rendered {@code href}, these URLs are <i>fetched</i> (form: confirmation GET) or
095 * <i>submitted</i> (endpoint: mutating write), so an unresolved substitution <b>refuses</b> instead of issuing a
096 * malformed request; see each setter's javadoc for the full contract.  A value with no token is unaffected and
097 * is used as declared.  A blank/absent {@code form} is the confirm-only local path (no
098 * GET), not a refusal.
099 *
100 * <h2 class='section'>Example:</h2>
101 * <p class='bjava'>
102 *    RowAction <jv>delete</jv> = RowAction.<jsm>create</jsm>(<js>"delete"</js>)
103 *       .label(<js>"Delete"</js>)
104 *       .endpoint(<js>"servlet:/incidents/{id}"</js>)
105 *       .method(RowAction.Method.<jsf>DELETE</jsf>)
106 *       .confirm(<js>"Delete incident {id}?"</js>)
107 *       .confirmLabel(<js>"Delete forever"</js>)
108 *       .tone(RowAction.Tone.<jsf>DANGER</jsf>)
109 *       .visibleWhen(VisibilityRule.<jsm>when</jsm>(<js>"locked"</js>).ne(<jk>true</jk>));
110 * </p>
111 *
112 * <h2 class='section'>See Also:</h2>
113 * <ul>
114 *    <li class='jc'>{@link Render}
115 * </ul>
116 *
117 * @since 10.0.0
118 */
119@BeanType(properties="id,label,icon,endpoint,method,confirm,confirmTitle,bulkMode,form,present,onSuccess,enabledWhen,visibleWhen,tone,confirmLabel,confirmRenderer,href")
120@SuppressWarnings({
121   "java:S1845" // Fluent-builder setters intentionally mirror field names (Juneau DSL convention).
122})
123public class RowAction {
124
125   /**
126    * The non-safe HTTP method a row action submits with.
127    *
128    * <p>
129    * Deliberately limited to the four non-safe methods.  A safe method (GET/HEAD/OPTIONS/TRACE) skips the
130    * Origin/CSRF/JSON checks at {@link org.apache.juneau.rest.server.filter.LoopbackBoundary}, so a mutating
131    * action bound to one would be CSRF-able; this enum makes that unexpressible.  Each constant's wire token is
132    * its uppercase name, which is exactly what the client sends as the request method.
133    */
134   public enum Method {
135
136      /** HTTP {@code POST}. */
137      POST,
138
139      /** HTTP {@code PUT}. */
140      PUT,
141
142      /** HTTP {@code PATCH}. */
143      PATCH,
144
145      /** HTTP {@code DELETE}. */
146      DELETE;
147
148      /**
149       * Returns the wire token for this method (its uppercase name).
150       *
151       * @return The wire token (e.g. {@code "POST"}).
152       */
153      public String wire() {
154         return name();
155      }
156   }
157
158   /**
159    * The visual tone of a row action's confirmation.
160    *
161    * <p>
162    * Each constant carries the lowercase wire token emitted for the {@code tone} field.  {@link #DANGER} styles the
163    * confirmation as destructive and focuses its Cancel button first.
164    */
165   public enum Tone {
166
167      /** The ordinary confirmation styling. */
168      DEFAULT("default"),
169
170      /** A destructive confirmation: danger styling, Cancel focused first. */
171      DANGER("danger");
172
173      private final String wire;
174
175      Tone(String wire) {
176         this.wire = wire;
177      }
178
179      /**
180       * Returns the lowercase wire token for this tone.
181       *
182       * @return The wire token (e.g. {@code "danger"}).
183       */
184      public String wire() {
185         return wire;
186      }
187   }
188
189   /**
190    * How a row action's form/confirmation is presented.
191    *
192    * <p>
193    * Each constant carries the lowercase wire token emitted for the {@code present} field.  {@link #INLINE} also
194    * keeps the action out of the row menu.
195    */
196   public enum Present {
197
198      /** Navigate to / render the action's form as a full page. */
199      PAGE("page"),
200
201      /** Render the action's form/confirmation in a modal dialog. */
202      DIALOG("dialog"),
203
204      /**
205       * The action is fired from its cell pill or edit cell, never from the row menu.
206       *
207       * <p>
208       * The row-action menu omits it; every other activation surface still runs it.
209       */
210      INLINE("inline");
211
212      private final String wire;
213
214      Present(String wire) {
215         this.wire = wire;
216      }
217
218      /**
219       * Returns the lowercase wire token for this presentation.
220       *
221       * @return The wire token (e.g. {@code "dialog"}).
222       */
223      public String wire() {
224         return wire;
225      }
226   }
227
228   /**
229    * What the runtime does with a successful action result.
230    *
231    * <p>
232    * Each constant carries the wire token emitted for the {@code onSuccess} field.  The behavior behind each
233    * token is implemented by a later wave; this type freezes the vocabulary.
234    */
235   public enum OnSuccess {
236
237      /** Redraw (reload) the whole table. */
238      REDRAW("redraw"),
239
240      /** Merge the returned row into the table in place. */
241      MERGE_ROW("mergeRow"),
242
243      /** Navigate away using the result. */
244      NAVIGATE("navigate");
245
246      private final String wire;
247
248      OnSuccess(String wire) {
249         this.wire = wire;
250      }
251
252      /**
253       * Returns the wire token for this success behavior.
254       *
255       * @return The wire token (e.g. {@code "mergeRow"}).
256       */
257      public String wire() {
258         return wire;
259      }
260   }
261
262   /**
263    * How an action behaves when driven from a bulk-mutate toolbar.
264    *
265    * @since 10.0.0
266    */
267   public enum BulkMode {
268
269      /** One call per selected row. */
270      PER_ROW("perRow"),
271
272      /** A single call carrying every selected id. */
273      AGGREGATE("aggregate");
274
275      private final String wire;
276
277      BulkMode(String wire) {
278         this.wire = wire;
279      }
280
281      /**
282       * Returns the wire token for this mode.
283       *
284       * @return The wire token ({@code "perRow"} or {@code "aggregate"}).
285       */
286      public String wire() {
287         return wire;
288      }
289   }
290
291   /** The stable action id (menu-item key; also the submit's logical name). */
292   public String id;
293
294   /** The menu-item text. */
295   public String label;
296
297   /** Optional glyph/icon name (resolved by the shared icon registry). */
298   public String icon;
299
300   /**
301    * The URL this action submits to (see {@link #endpoint(String) endpoint} for the {@code {property}}
302    * substitution grammar).
303    */
304   public String endpoint;
305
306   /**
307    * The same-origin path template of a link action (see {@link #link(String,String)}); {@code {id}} and
308    * {@code {property}} are replaced from the row.
309    */
310   public String href;
311
312   /** The non-safe HTTP method wire token (see {@link Method#wire()}). */
313   public String method;
314
315   /** Optional confirmation prompt shown before the submit, or literal <jk>false</jk> for none (see {@link #noConfirm()}). */
316   public Object confirm;
317
318   /** Optional confirm-dialog title when this action is driven in bulk. */
319   public String confirmTitle;
320
321   /** Optional bulk-mode wire token (see {@link BulkMode#wire()}); <jk>null</jk> means {@code perRow}. */
322   public String bulkMode;
323
324   /** Optional form-source URL supplying the action's input fields. */
325   public String form;
326
327   /** Optional presentation hint wire token (see {@link Present#wire()}). */
328   public String present;
329
330   /** Optional success-behavior hint wire token (see {@link OnSuccess#wire()}). */
331   public String onSuccess;
332
333   /**
334    * The row-state rules that must all match for this action to render enabled.
335    *
336    * <p>
337    * <jk>null</jk> or empty means "never gated" &mdash; the action renders exactly as it does today.  See
338    * {@link #enabledWhen(String,Op,Object,String)} for the semantics, which mirror
339    * {@code ActionRef.enabledWhen} on the detail-panel {@code ActionBar} (widgets module): presentation only,
340    * disabled never hidden, first-declared-rule-wins, and a field the row does not carry fails closed.
341    */
342   public List<RowActionEnabledRule> enabledWhen;
343
344   /**
345    * The rules that must all match for this action to render at all.  <jk>null</jk> or empty means always visible.
346    *
347    * <p>
348    * Unlike {@link #enabledWhen}, which disables but never hides, a row whose data does not satisfy every rule
349    * here has this action hidden entirely (re-evaluated on every draw).  Prefer {@code enabledWhen}, which tells
350    * the user why an action is unavailable, and hide only when the action is irrelevant to the row.  Still
351    * presentation only &mdash; the endpoint must authorize independently.  The evaluation map is the row, plus the
352    * page's {@code facts} under a {@code facts.} prefix, so a rule can test either {@code "status"} or
353    * {@code "facts.viewer.roles"}.
354    */
355   public List<VisibilityRule> visibleWhen;
356
357   /** Optional confirmation tone wire token (see {@link Tone#wire()}). */
358   public String tone;
359
360   /** Optional text of the confirm button; <jk>null</jk> means the action's {@link #label}. */
361   public String confirmLabel;
362
363   /** Optional name of a confirm renderer registered with the client runtime; <jk>null</jk> means the built-in modal. */
364   public String confirmRenderer;
365
366   /**
367    * Starts a new {@link RowAction} with the specified stable action id.
368    *
369    * @param id The stable action id.  Must not be <jk>null</jk> or blank.
370    * @return A new mutable {@link RowAction} to chain builder calls on.
371    * @throws IllegalArgumentException If {@code id} is <jk>null</jk> or blank.
372    */
373   public static RowAction create(String id) {
374      if (ib(id))
375         throw iaex("RowAction id must not be null or blank.");
376      var a = new RowAction();
377      a.id = id;
378      return a;
379   }
380
381   /**
382    * Starts a link action: a header button that navigates to a same-origin page instead of submitting.
383    *
384    * <p>
385    * A link action has no endpoint, method, form or confirmation.  Row menus ignore it; it shows in a tabbed row
386    * detail's header.
387    *
388    * @param id The stable action id.  Must not be blank.
389    * @param urlTemplate A same-origin path template; {@code {id}} and {@code {property}} are replaced from the row.
390    * @return A new link {@link RowAction}.
391    * @throws IllegalArgumentException If {@code id} is blank or the template is not a same-origin path.
392    */
393   public static RowAction link(String id, String urlTemplate) {
394      return create(id).href(urlTemplate);
395   }
396
397   /**
398    * Sets the link target, making this a link action.
399    *
400    * @param urlTemplate A same-origin path template starting with {@code /}.
401    * @return This object.
402    * @throws IllegalArgumentException If the template is not a same-origin path.
403    */
404   public RowAction href(String urlTemplate) {
405      if (urlTemplate == null || ! urlTemplate.startsWith("/") || ! RegionDef.isSafeDetailEndpoint(urlTemplate))
406         throw iaex("RowAction '%s' href '%s' must be a same-origin path starting with '/'.", id, urlTemplate);
407      href = urlTemplate;
408      return this;
409   }
410
411   /**
412    * Checks that this action is coherent: a link action carries nothing a submit would.
413    *
414    * @throws IllegalArgumentException If a link action also sets an endpoint, method, form or confirmation.
415    */
416   void validateLink() {
417      if (href == null)
418         return;
419      if (endpoint != null || method != null || form != null || confirm != null)
420         throw iaex("RowAction '%s' is a link and cannot also set endpoint, method, form or confirm.", id);
421   }
422
423   /**
424    * Sets the menu-item text.
425    *
426    * @param value The new value.
427    * @return This object.
428    */
429   public RowAction label(String value) {
430      label = value;
431      return this;
432   }
433
434   /**
435    * Sets the glyph/icon name.
436    *
437    * @param value The new value.
438    * @return This object.
439    */
440   public RowAction icon(String value) {
441      icon = value;
442      return this;
443   }
444
445   /**
446    * Sets the URL this action submits to.
447    *
448    * <p>
449    * May contain one or more {@code {property}} tokens (e.g. {@code "servlet:/incidents/{id}/ack"}), substituted
450    * from the CURRENT ROW's own already-fetched data at submit time &mdash; the client-side ({@code
451    * juneau-views.js}) runtime, not this Java layer, performs the substitution, by delegating to the identical
452    * {@code interpolateHref} helper the {@code linked} cell renderer uses
453    * (juneau-renders.js): the SAME token grammar (any {@code {property}}, not a hardcoded {@code {id}}) and the
454    * SAME per-value {@code encodeURIComponent} escaping &mdash; unchanged.
455    *
456    * <p>
457    * <b>Divergence from a rendered {@code href} is deliberate:</b> because this URL is <i>submitted</i>
458    * rather than merely rendered, the runtime <b>refuses the submission</b> (renders a visible refusal; issues no
459    * request; never a request-time exception) instead of firing a malformed or undeclared write, when:
460    * <ul>
461    *    <li>a {@code {property}} token's row value is absent, <jk>null</jk>, or blank;
462    *    <li>the resolved URL still carries an unsubstituted {@code {property}} token (e.g. the page shipped
463    *       {@code juneau-views.js} without its {@code juneau-renders.js} peer);
464    *    <li>the resolved URL contains a {@code ..} path segment (which browser URL resolution would otherwise
465    *       normalize into a different, undeclared endpoint); or
466    *    <li>no {@code endpoint} is declared at all.
467    * </ul>
468    * {@code Column.href} keeps substituting to an empty string in each of these cases, because a rendered link is
469    * not a write.
470    *
471    * <p>
472    * <b>Backward compatible, narrowed:</b> an {@code endpoint} with no {@code {...}} token is still
473    * issued as declared (three of the four guards above cannot fire on it; the fourth,
474    * the {@code ..} check, only fires on an author-declared {@code ..}).  An {@code endpoint} WITH a token now
475    * refuses in cases that previously submitted a malformed URL (e.g. {@code "servlet:/incidents//ack"} for a
476    * row with no {@code id}) rather than issuing it.
477    *
478    * @param value The new value.
479    * @return This object.
480    */
481   public RowAction endpoint(String value) {
482      endpoint = value;
483      return this;
484   }
485
486   /**
487    * Sets the non-safe HTTP method this action submits with.
488    *
489    * <p>
490    * Only a {@link Method} (POST/PUT/PATCH/DELETE) can be passed, so a safe method can never be declared &mdash;
491    * the build-time half of the safe-method refusal.
492    *
493    * @param value The method.  Must not be <jk>null</jk>.
494    * @return This object.
495    */
496   public RowAction method(Method value) {
497      method = value.wire();
498      return this;
499   }
500
501   /**
502    * Sets the confirmation prompt shown before the submit.
503    *
504    * <p>
505    * The prompt is shown whatever {@link #present(Present) present} says: without {@link Present#DIALOG} the action
506    * opens a confirm-only dialog (or its {@link #confirmRenderer(String) confirmRenderer}) and submits only on
507    * Confirm.  Use {@link #noConfirm()} for an action that never prompts.
508    *
509    * <p>
510    * One surface never prompts: committing an inline cell edit (the {@code edit} renderer's pencil) submits the action
511    * directly on Enter or blur even when the action declares a confirm or a
512    * {@link #confirmRenderer(String) confirmRenderer}, because a dialog opening on Enter or blur is awkward.  Do not
513    * wire a confirm-guarded action to an inline editor.
514    *
515    * @param value The new value.
516    * @return This object.
517    */
518   public RowAction confirm(String value) {
519      confirm = value;
520      return this;
521   }
522
523   /**
524    * Sets how this action behaves when driven from a bulk-mutate toolbar: one call per selected row
525    * ({@link BulkMode#PER_ROW}, the default) or a single call carrying every selected id
526    * ({@link BulkMode#AGGREGATE}).
527    *
528    * @param value The new mode. A <jk>null</jk> value clears it (the default, {@link BulkMode#PER_ROW}).
529    * @return This object.
530    */
531   public RowAction bulkMode(BulkMode value) {
532      bulkMode = value == null ? null : value.wire();
533      return this;
534   }
535
536   /**
537    * Sets the confirm dialog's title when this action is driven in bulk (e.g. {@code "Abort {count} pending changes"}).
538    *
539    * @param value The title template. May be <jk>null</jk>.
540    * @return This object.
541    */
542   public RowAction confirmTitle(String value) {
543      confirmTitle = value;
544      return this;
545   }
546
547   /**
548    * Marks this action as never requiring a confirm dialog, in bulk or otherwise &mdash; writes a literal
549    * <jk>false</jk> onto the same {@link #confirm} wire key a confirm message would otherwise occupy.
550    *
551    * @return This object.
552    */
553   public RowAction noConfirm() {
554      confirm = Boolean.FALSE;
555      return this;
556   }
557
558   /**
559    * Sets the form-source URL supplying the action's input fields.
560    *
561    * <p>
562    * May contain one or more {@code {property}} tokens (e.g. {@code "/data/alerts/{id}/ack-form"}), substituted
563    * from the CURRENT ROW's own already-fetched data before the confirmation GET &mdash; the client-side
564    * ({@code juneau-views.js}) runtime, not this Java layer, performs the substitution, by delegating to the
565    * identical {@code interpolateHref} helper the {@code linked} cell renderer
566    * uses (juneau-renders.js): the SAME token grammar (any {@code {property}}, not a hardcoded {@code {id}}) and
567    * the SAME per-value {@code encodeURIComponent} escaping.
568    *
569    * <p>
570    * <b>Divergence from a rendered {@code href}:</b> because this URL is <i>fetched</i> (the confirmation GET) rather
571    * than merely rendered, the runtime <b>refuses the open</b> (renders a visible refusal; issues no {@code
572    * fetch}) instead of GETting a malformed or undeclared path, when:
573    * <ul>
574    *    <li>a {@code {property}} token's row value is absent, <jk>null</jk>, or blank;
575    *    <li>the resolved URL still carries an unsubstituted {@code {property}} token (e.g. the page shipped
576    *       {@code juneau-views.js} without its {@code juneau-renders.js} peer); or
577    *    <li>the resolved URL contains a {@code ..} path segment (which browser URL resolution would otherwise
578    *       normalize into a different, undeclared endpoint).
579    * </ul>
580    * {@code href} keeps substituting to an empty string in each of these cases, because a rendered link is
581    * not a fetch.
582    *
583    * <p>
584    * <b>Divergence from {@link #endpoint(String) endpoint}:</b> a blank/absent {@code form} is still the
585    * confirm-only local path (no GET), not a {@code no-endpoint} refusal.  A token-less {@code form} is fetched
586    * as declared.
587    *
588    * @param value The new value.  Can be <jk>null</jk> or blank for a confirm-only dialog.
589    * @return This object.
590    */
591   public RowAction form(String value) {
592      form = value;
593      return this;
594   }
595
596   /**
597    * Sets the presentation hint.
598    *
599    * @param value The presentation.  Must not be <jk>null</jk>.
600    * @return This object.
601    */
602   public RowAction present(Present value) {
603      present = value.wire();
604      return this;
605   }
606
607   /**
608    * Sets the success-behavior hint.
609    *
610    * @param value The success behavior.  Must not be <jk>null</jk>.
611    * @return This object.
612    */
613   public RowAction onSuccess(OnSuccess value) {
614      onSuccess = value.wire();
615      return this;
616   }
617
618   /**
619    * Gates this action on the row's own state, comparing one field against one value.
620    *
621    * <p>
622    * Mirrors {@code ActionRef.enabledWhen(String,Op,Object,String)} on the detail-panel {@code ActionBar}
623    * (widgets module).  This is presentation only, never the authorization gate: the endpoint behind this
624    * action must still perform its own real check and refuse on its own authority.  A row whose field does
625    * not satisfy every declared rule renders this action present but disabled, carrying {@code reason} as its
626    * explanation; disabled, never hidden.  Call this more than once to declare more than one rule &mdash; all
627    * of them must match, and when several fail, the runtime shows the first-declared failing reason.
628    *
629    * @param field The row field to test.  Must not be <jk>null</jk> or blank.
630    * @param op The comparison operator.  Must be {@link Op#EQ} or {@link Op#NE}.
631    * @param value The comparison value.  Must not be <jk>null</jk>.
632    * @param reason Why the action is unavailable when this rule does not match.  Must not be <jk>null</jk> or
633    *    blank.
634    * @return This object.
635    */
636   public RowAction enabledWhen(String field, Op op, Object value, String reason) {
637      return addEnabledRule(RowActionEnabledRule.of(field, op, value, reason));
638   }
639
640   /**
641    * Gates this action on the presence or absence of a row field.
642    *
643    * <p>
644    * The presence-based counterpart of {@link #enabledWhen(String,Op,Object,String)}, which carries the full
645    * semantics.
646    *
647    * @param field The row field to test.  Must not be <jk>null</jk> or blank.
648    * @param op The comparison operator.  Must be {@link Op#PRESENT} or {@link Op#ABSENT}.
649    * @param reason Why the action is unavailable when this rule does not match.  Must not be <jk>null</jk> or
650    *    blank.
651    * @return This object.
652    */
653   public RowAction enabledWhen(String field, Op op, String reason) {
654      return addEnabledRule(RowActionEnabledRule.of(field, op, reason));
655   }
656
657   private RowAction addEnabledRule(RowActionEnabledRule rule) {
658      if (enabledWhen == null)
659         enabledWhen = l();
660      enabledWhen.add(rule);
661      return this;
662   }
663
664   /**
665    * Hides this action, per row, unless every rule matches (see {@link #visibleWhen} for the semantics).
666    *
667    * @param rules The rules; all must match.  Replaces any rules set by an earlier call.
668    * @return This object.
669    */
670   public RowAction visibleWhen(VisibilityRule...rules) {
671      visibleWhen = l(rules);
672      return this;
673   }
674
675   /**
676    * Sets the confirmation tone.
677    *
678    * @param value The tone.  Must not be <jk>null</jk>.
679    * @return This object.
680    */
681   public RowAction tone(Tone value) {
682      tone = value.wire();
683      return this;
684   }
685
686   /**
687    * Sets the text of the confirm button.
688    *
689    * @param value The label.  Can be <jk>null</jk> to fall back to {@link #label}.
690    * @return This object.
691    */
692   public RowAction confirmLabel(String value) {
693      confirmLabel = value;
694      return this;
695   }
696
697   /**
698    * Sets the name of the confirm renderer to use for this action's confirmation.
699    *
700    * <p>
701    * The name must be registered on the client with {@code JuneauViews.rowActions.registerConfirmRenderer}; an
702    * unregistered name refuses the confirmation.
703    *
704    * <p>
705    * A renderer on its own, with no {@link #confirm(String) confirm} text, is enough to prompt: the action asks the
706    * renderer before it submits even without {@code present(DIALOG)}, and the prompt is titled with the action's name.
707    *
708    * @param value The renderer name.  Can be <jk>null</jk> for the built-in modal.
709    * @return This object.
710    */
711   public RowAction confirmRenderer(String value) {
712      confirmRenderer = value;
713      return this;
714   }
715}