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} — 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 — 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 — 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" — 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 — 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 — 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 — 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 — 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 — 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 — 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 — 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}