Source code

001/*
002 *  Copyright 2012 Anyware Services
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.ametys.core.ui;
017
018import java.util.ArrayList;
019import java.util.HashMap;
020import java.util.List;
021import java.util.Map;
022
023import org.ametys.plugins.core.ui.util.ConfigurationHelper;
024
025/**
026 * Object binding of a client side element, ie something that is loaded and executed by the browser.<br>
027 * Such elements may be UI controls (buttons, menu, tools, ...) but also only JS or CSS files.<br><br>
028 * 
029 * This interface only covers files to be loaded, but its implementations are also meant to hold associated business-logic, if any.<br>
030 * To implement such logic, implementing classes should write any method, annotated with {@link Callable}, 
031 * that will be directly called by the kernel upon execution of the JavaScript method <code>serverCall('methodeName', params)</code>.<br><br>
032 * 
033 * All <code>Map&lt;String, Object&gt;</code> instances found in this class and its implementations 
034 * are directly converted from and to JSON to interact with browser-site JavaScript.
035 */
036public interface ClientSideElement
037{
038    /**
039     * Get the id of the element.
040     * @return the id. Can not be null.
041     */
042    public String getId();
043    
044    /**
045     * This method return the scripts that will be used on client side.
046     * This class will be parametrized by initial and current parameters.
047     * @param contextParameters Contextuals parameters transmitted by the environment.
048     * @return The list of scripts or an empty list.
049     */
050    public List<Script> getScripts(Map<String, Object> contextParameters);
051    
052    /**
053     * This method return the scripts that will be used on client side.
054     * This class will be parametrized by initial and current parameters.
055     * @param ignoreRights True to ignore the rights verification.
056     * @param contextParameters Contextuals parameters transmitted by the environment.
057     * @return The list of scripts or an empty list.
058     */
059    public List<Script> getScripts(boolean ignoreRights, Map<String, Object> contextParameters);
060    
061    /**
062     * This method return the right that will be needed on client side.
063     * This class will be parametrized by initial and current parameters.
064     * @param contextParameters Contextuals parameters transmitted by the environment.
065     * @return The rights in a Map of (rightId, context). Can be empty.
066     */
067    public Map<String, String> getRights(Map<String, Object> contextParameters);
068    
069
070    /**
071     * Get the plugin name where the control was declared
072     * @return The plugin name. Can not be null.
073     */
074    public String getPluginName();
075    
076    /**
077     * This method returns the list of dependencies, sorted by extension point. 
078     * @return a map of dependencies ids by extension point.
079     */
080    public Map<String, List<String>> getDependencies();
081
082    /**
083     * This class represents a script file
084     */
085    public class ScriptFile
086    {
087        private String _debugMode;
088        private String _rtlMode;
089        private boolean _langMode;
090        private String _path;
091        private Map<String, String> _langPaths;
092        private String _defaultLang;
093        
094        /**
095         * Default constructor. Create a new script only defined by its path.
096         * @param path The script path
097         */
098        public ScriptFile(String path)
099        {
100            _path = path;
101            _langMode = false;
102        }
103
104        /**
105         * Create a new script file that is not language aware.
106         * @param debug The debug mode. Can be null.
107         * @param rtl The rtl mode. Can be null.
108         * @param path The file path.
109         */
110        public ScriptFile(String debug, String rtl, String path)
111        {
112            _debugMode = debug;
113            _rtlMode = rtl;
114            _path = path;
115            _langMode = false;
116        }
117        
118        /**
119         * Create a new script file with a language specific configuration.
120         * @param debug The debug mode. Can be null.
121         * @param langPaths The list of languages with their paths.
122         * @param defaultLang The default language code. Can be null.
123         */
124        public ScriptFile(String debug, Map<String, String> langPaths, String defaultLang)
125        {
126            _debugMode = debug;
127            _langPaths = langPaths;
128            _defaultLang = defaultLang;
129            _langMode = true;
130        }
131        
132        /**
133         * Clone a script file
134         * @param scriptFile The script file to clone
135         */
136        public ScriptFile(ScriptFile scriptFile)
137        {
138            _debugMode = scriptFile._debugMode;
139            _defaultLang = scriptFile._defaultLang;
140            _langMode = scriptFile._langMode;
141            
142            _langPaths = new HashMap<>();
143            _langPaths.putAll(scriptFile._langPaths);
144        }
145        
146        /**
147         * Get the debug mode
148         * @return the debug mode
149         */
150        public String getDebugMode()
151        {
152            return _debugMode;
153        }
154        
155        /**
156         * Get the rtl mode
157         * @return the the rtl mode
158         */
159        public String getRtlMode()
160        {
161            return _rtlMode;
162        }
163        
164        /**
165         * Retrieve the language mode
166         * @return True if the script file is language specific
167         */
168        public boolean isLangSpecific()
169        {
170            return _langMode;
171        }
172        
173        /**
174         * Get the file path
175         * @return the path
176         */
177        public String getPath()
178        {
179            return _path;
180        }
181        
182        /**
183         * Get the path mapping by language
184         * @return the paths by languages
185         */
186        public Map<String, String> getLangPaths()
187        {
188            return _langPaths;
189        }
190        
191        /**
192         * Get the default language
193         * @return the the default language
194         */
195        public String getDefaultLang()
196        {
197            return _defaultLang;
198        }
199        
200        @Override
201        public String toString()
202        {
203            return _path;
204        }
205    }
206    
207    /**
208     * This class represents a script
209     */
210    public class Script
211    {
212        /** The id associated with this script */
213        protected String _id;
214        /** The script class name of the script */
215        protected String _classname;
216        /** The script files of the script (url is relative to webapp context) */
217        protected List<ScriptFile> _scriptFiles;
218        /** The css files of the script (url is relative to webapp context) */
219        protected List<ScriptFile> _cssFiles;
220        /** The parameters objects of the script */
221        protected Map<String, Object> _parameters;
222        /** The server element id for this script */
223        protected String _serverId;
224        
225        /**
226         * Creates a script
227         * @param id The script id
228         * @param classname The script classname. Can not be null nor empty.
229         * @param scriptFiles The list of files needed to execute the classname. Must not be null.
230         * @param cssFiles The list of css files needed to correctly display the script. Must not be null.
231         * @param parameters The parameters associated with this Script.
232         */
233        public Script(String id, String classname, List<ScriptFile> scriptFiles, List<ScriptFile> cssFiles, Map<String, Object> parameters)
234        {
235            this(id, id, classname, scriptFiles, cssFiles, parameters);
236        }
237        
238        /**
239         * Creates a script
240         * @param id The script id
241         * @param serverId The script server id
242         * @param classname The script classname. Can not be null nor empty.
243         * @param scriptFiles The list of files needed to execute the classname. Must not be null.
244         * @param cssFiles The list of css files needed to correctly display the script. Must not be null.
245         * @param parameters The parameters associated with this Script.
246         */
247        public Script(String id, String serverId, String classname, List<ScriptFile> scriptFiles, List<ScriptFile> cssFiles, Map<String, Object> parameters)
248        {
249            _id = id;
250            _serverId = serverId;
251            _classname = classname;
252            _scriptFiles = scriptFiles;
253            _cssFiles = cssFiles;
254            _parameters = parameters;
255        }
256        
257        /**
258         * Clone a script
259         * @param script The script to clone
260         */
261        public Script(Script script)
262        {
263            _id = script._id;
264            _serverId = script._serverId;
265            _classname = script._classname;
266            _scriptFiles = new ArrayList<>(script._scriptFiles);
267            _cssFiles = new ArrayList<>(script._cssFiles);
268            _parameters = ConfigurationHelper.clonePluginParameters(script._parameters);
269        }
270        
271        /**
272         * The script id.
273         * @return The script id. Can not be null nor empty.
274         */
275        public String getId()
276        {
277            return _id;
278        }
279        
280        /**
281         * The id server-side associated with this script
282         * @return The server id;
283         */
284        public String getServerId()
285        {
286            return _serverId;
287        }
288        
289        /**
290         * The script classname.
291         * @return The script classname. Can not be null nor empty.
292         */
293        public String getScriptClassname()
294        {
295            return _classname;
296        }
297        
298        /**
299         * The list of files needed to execute the classname.
300         * @return The list of files needed to execute the classname. Must not be null.
301         */
302        public List<ScriptFile> getScriptFiles()
303        {
304            return _scriptFiles;
305        }
306        
307        /**
308         * The list of css files needed to correctly display the script.
309         * @return The list of css files needed to correctly display the script. Must not be null.
310         */
311        public List<ScriptFile> getCSSFiles()
312        {
313            return _cssFiles;
314        }
315        
316        /**
317         * This method returns the parameters initially given to the control script class.
318         * Initial parameters must be sufficient to allow the script to render the control without waiting for a refresh by the current parameters.
319         * @return a map of parameters. Key represents ids of the parameters and values represents its values. Can not be null.
320         */
321        public Map<String, Object> getParameters()
322        {
323            return _parameters;
324        }
325    }
326}