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 _rtlMode;
088        private boolean _langMode;
089        private String _path;
090        private Map<String, String> _langPaths;
091        private String _defaultLang;
092        
093        /**
094         * Default constructor. Create a new script only defined by its path.
095         * @param path The script path
096         */
097        public ScriptFile(String path)
098        {
099            _path = path;
100            _langMode = false;
101        }
102
103        /**
104         * Create a new script file that is not language aware.
105         * @param rtl The rtl mode. Can be null.
106         * @param path The file path.
107         */
108        public ScriptFile(String rtl, String path)
109        {
110            _rtlMode = rtl;
111            _path = path;
112            _langMode = false;
113        }
114        
115        /**
116         * Create a new script file with a language specific configuration.
117         * @param langPaths The list of languages with their paths.
118         * @param defaultLang The default language code. Can be null.
119         */
120        public ScriptFile(Map<String, String> langPaths, String defaultLang)
121        {
122            _langPaths = langPaths;
123            _defaultLang = defaultLang;
124            _langMode = true;
125        }
126        
127        /**
128         * Clone a script file
129         * @param scriptFile The script file to clone
130         */
131        public ScriptFile(ScriptFile scriptFile)
132        {
133            _defaultLang = scriptFile._defaultLang;
134            _langMode = scriptFile._langMode;
135            
136            _langPaths = new HashMap<>();
137            _langPaths.putAll(scriptFile._langPaths);
138        }
139        
140        /**
141         * Get the rtl mode
142         * @return the the rtl mode
143         */
144        public String getRtlMode()
145        {
146            return _rtlMode;
147        }
148        
149        /**
150         * Retrieve the language mode
151         * @return True if the script file is language specific
152         */
153        public boolean isLangSpecific()
154        {
155            return _langMode;
156        }
157        
158        /**
159         * Get the file path
160         * @return the path
161         */
162        public String getPath()
163        {
164            return _path;
165        }
166        
167        /**
168         * Get the path mapping by language
169         * @return the paths by languages
170         */
171        public Map<String, String> getLangPaths()
172        {
173            return _langPaths;
174        }
175        
176        /**
177         * Get the default language
178         * @return the the default language
179         */
180        public String getDefaultLang()
181        {
182            return _defaultLang;
183        }
184        
185        @Override
186        public String toString()
187        {
188            return _path;
189        }
190    }
191    
192    /**
193     * This class represents a script
194     */
195    public class Script
196    {
197        /** The id associated with this script */
198        protected String _id;
199        /** The script class name of the script */
200        protected String _classname;
201        /** The script files of the script (url is relative to webapp context) */
202        protected List<ScriptFile> _scriptFiles;
203        /** The css files of the script (url is relative to webapp context) */
204        protected List<ScriptFile> _cssFiles;
205        /** The parameters objects of the script */
206        protected Map<String, Object> _parameters;
207        /** The server element id for this script */
208        protected String _serverId;
209        
210        /**
211         * Creates a script
212         * @param id The script id
213         * @param classname The script classname. Can not be null nor empty.
214         * @param scriptFiles The list of files needed to execute the classname. Must not be null.
215         * @param cssFiles The list of css files needed to correctly display the script. Must not be null.
216         * @param parameters The parameters associated with this Script.
217         */
218        public Script(String id, String classname, List<ScriptFile> scriptFiles, List<ScriptFile> cssFiles, Map<String, Object> parameters)
219        {
220            this(id, id, classname, scriptFiles, cssFiles, parameters);
221        }
222        
223        /**
224         * Creates a script
225         * @param id The script id
226         * @param serverId The script server id
227         * @param classname The script classname. Can not be null nor empty.
228         * @param scriptFiles The list of files needed to execute the classname. Must not be null.
229         * @param cssFiles The list of css files needed to correctly display the script. Must not be null.
230         * @param parameters The parameters associated with this Script.
231         */
232        public Script(String id, String serverId, String classname, List<ScriptFile> scriptFiles, List<ScriptFile> cssFiles, Map<String, Object> parameters)
233        {
234            _id = id;
235            _serverId = serverId;
236            _classname = classname;
237            _scriptFiles = scriptFiles;
238            _cssFiles = cssFiles;
239            _parameters = parameters;
240        }
241        
242        /**
243         * Clone a script
244         * @param script The script to clone
245         */
246        public Script(Script script)
247        {
248            _id = script._id;
249            _serverId = script._serverId;
250            _classname = script._classname;
251            _scriptFiles = new ArrayList<>(script._scriptFiles);
252            _cssFiles = new ArrayList<>(script._cssFiles);
253            _parameters = ConfigurationHelper.clonePluginParameters(script._parameters);
254        }
255        
256        /**
257         * The script id.
258         * @return The script id. Can not be null nor empty.
259         */
260        public String getId()
261        {
262            return _id;
263        }
264        
265        /**
266         * The id server-side associated with this script
267         * @return The server id;
268         */
269        public String getServerId()
270        {
271            return _serverId;
272        }
273        
274        /**
275         * The script classname.
276         * @return The script classname. Can not be null nor empty.
277         */
278        public String getScriptClassname()
279        {
280            return _classname;
281        }
282        
283        /**
284         * The list of files needed to execute the classname.
285         * @return The list of files needed to execute the classname. Must not be null.
286         */
287        public List<ScriptFile> getScriptFiles()
288        {
289            return _scriptFiles;
290        }
291        
292        /**
293         * The list of css files needed to correctly display the script.
294         * @return The list of css files needed to correctly display the script. Must not be null.
295         */
296        public List<ScriptFile> getCSSFiles()
297        {
298            return _cssFiles;
299        }
300        
301        /**
302         * This method returns the parameters initially given to the control script class.
303         * Initial parameters must be sufficient to allow the script to render the control without waiting for a refresh by the current parameters.
304         * @return a map of parameters. Key represents ids of the parameters and values represents its values. Can not be null.
305         */
306        public Map<String, Object> getParameters()
307        {
308            return _parameters;
309        }
310    }
311}