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;
018
019import java.util.*;
020
021/**
022 * Mixin for element builders that can carry a client object-model block: handler actions, lifecycle bindings and
023 * handler subscriptions.  Implementers supply {@link #modelBlock()} and {@link #self()}.
024 *
025 * <h2 class='section'>Example:</h2>
026 * <p class='bjava'>
027 *   CardSpec.<jsm>of</jsm>(<js>"html"</js>, <js>"orders"</js>)
028 *     .action(<js>"archive"</js>, <js>"archive"</js>, <js>"orders.archive"</js>)
029 *     .on(<js>"rendered"</js>, <js>"orders.wire"</js>)
030 *     .subscribe(<js>"selection:orders"</js>, <js>"orders.onSelect"</js>);
031 * </p>
032 *
033 * @param <T> The builder type.
034 * @since 10.0.0
035 */
036public interface Handled<T> {
037
038   /**
039    * Returns the element's model block.
040    *
041    * @return The block; never <jk>null</jk>.
042    */
043   ModelBlock modelBlock();
044
045   /**
046    * Returns this builder.
047    *
048    * @return This object.
049    */
050   T self();
051
052   /**
053    * Adds a click action calling a named handler.
054    *
055    * @param id The action id.
056    * @param icon The icon name.
057    * @param handler The handler name.
058    * @return This object.
059    */
060   default T action(String id, String icon, String handler) {
061      return action(ModelAction.of(id).icon(icon).handler(handler));
062   }
063
064   /**
065    * Adds a click action with a payload.
066    *
067    * @param id The action id.
068    * @param icon The icon name.
069    * @param handler The handler name.
070    * @param payload The payload.
071    * @return This object.
072    */
073   default T action(String id, String icon, String handler, Map<String,Object> payload) {
074      return action(ModelAction.of(id).icon(icon).handler(handler).payload(payload));
075   }
076
077   /**
078    * Adds a fully specified action.
079    *
080    * @param a The action.
081    * @return This object.
082    */
083   default T action(ModelAction a) {
084      modelBlock().action(a);
085      return self();
086   }
087
088   /**
089    * Binds a lifecycle event to a named handler.
090    *
091    * @param event The event.
092    * @param handler The handler name.
093    * @return This object.
094    */
095   default T on(String event, String handler) {
096      return on(event, HandlerRef.named(handler));
097   }
098
099   /**
100    * Binds a lifecycle event.
101    *
102    * @param event The event.
103    * @param handler The handler.
104    * @return This object.
105    */
106   default T on(String event, HandlerRef handler) {
107      modelBlock().on(event, handler);
108      return self();
109   }
110
111   /**
112    * Subscribes a named handler to a topic.
113    *
114    * @param topic The topic; may hold {@code {rowKey}}, {@code {tabId}}, {@code {cardId}}.
115    * @param handler The handler name.
116    * @return This object.
117    */
118   default T subscribe(String topic, String handler) {
119      return subscribe(topic, HandlerRef.named(handler));
120   }
121
122   /**
123    * Subscribes a handler to a topic.
124    *
125    * @param topic The topic.
126    * @param handler The handler.
127    * @return This object.
128    */
129   default T subscribe(String topic, HandlerRef handler) {
130      modelBlock().subscribe(topic, handler);
131      return self();
132   }
133}