1 /* plugin.js is part of Aloha Editor project http://aloha-editor.org
  2  *
  3  * Aloha Editor is a WYSIWYG HTML5 inline editing library and editor. 
  4  * Copyright (c) 2010-2012 Gentics Software GmbH, Vienna, Austria.
  5  * Contributors http://aloha-editor.org/contribution.php 
  6  * 
  7  * Aloha Editor is free software; you can redistribute it and/or
  8  * modify it under the terms of the GNU General Public License
  9  * as published by the Free Software Foundation; either version 2
 10  * of the License, or any later version.
 11  *
 12  * Aloha Editor is distributed in the hope that it will be useful,
 13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
 14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 15  * GNU General Public License for more details.
 16  *
 17  * You should have received a copy of the GNU General Public License
 18  * along with this program; if not, write to the Free Software
 19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 20  * 
 21  * As an additional permission to the GNU GPL version 2, you may distribute
 22  * non-source (e.g., minimized or compacted) forms of the Aloha-Editor
 23  * source code without the copy of the GNU GPL normally required,
 24  * provided you include this license notice and a URL through which
 25  * recipients can access the Corresponding Source.
 26  */
 27 define([
 28 	'aloha/core',
 29 	'jquery',
 30 	'util/class',
 31 	'aloha/pluginmanager',
 32 	'aloha/console'
 33 ], function (
 34 	Aloha,
 35 	jQuery,
 36 	Class,
 37 	PluginManager,
 38 	console
 39 ) {
 40 	"use strict";
 41 
 42 	/**
 43  44 	 * Abstract Plugin Object
 45 	 * @namespace Aloha
 46 	 * @class Plugin
 47 	 * @constructor
 48 	 * @param {String} pluginPrefix unique plugin prefix
 49 	 */
 50 	var Plugin = Class.extend({
 51 
 52 		name: null,
 53 
 54 		/**
 55 		 * contains the plugin's default settings object
 56 		 * @cfg {Object} default settings for the plugin
 57 		 */
 58 		defaults: {},
 59 
 60 		/**
 61 		 * contains the plugin's settings object
 62 		 * @cfg {Object} settings the plugins settings stored in an object
 63 		 */
 64 		settings: {},
 65 
 66 		/**
 67 		 * Names of other plugins which must be loaded in order for this plugin to
 68 		 * function.
 69 		 * @cfg {Array}
 70 		 */
 71 		dependencies: [],
 72 
 73 		_constructor: function (name) {
 74 			/**
 75 			 * Settings of the plugin
 76 			 */
 77 			if (typeof name !== "string") {
 78 				console.error('Cannot initialise unnamed plugin, skipping');
 79 			} else {
 80 				this.name = name;
 81 			}
 82 		},
 83 
 84 		/**
 85 		 * @return true if dependencies satisfied, false otherwise
 86 		 */
 87 		checkDependencies: function () {
 88 			var dependenciesSatisfied = true,
 89 				that = this;
 90 
 91 			jQuery.each(this.dependencies, function () {
 92 
 93 				if (!Aloha.isPluginLoaded(this)) {
 94 					dependenciesSatisfied = false;
 95 					console.error('plugin.' + that.name, 'Required plugin "' + this + '" not found.');
 96 				}
 97 			});
 98 
 99 			return dependenciesSatisfied;
100 		},
101 
102 		/**
103 		 * Init method of the plugin. Called from Aloha Core to initialize this plugin
104 		 * @return void
105 		 * @hide
106 		 */
107 		init: function () {},
108 
109 		/**
110 		 * Get the configuration settings for an editable obj.
111 		 * Handles both conf arrays or conf objects
112 		 * <ul>
113 		 * <li>Array configuration parameters are:
114 		 * <pre>
115 		 * "list": {
116 		 *		config : [ 'b', 'h1' ],
117 		 *		editables : {
118 		 *			'#title'	: [ ],
119 		 *			'div'		: [ 'b', 'i' ],
120 		 *			'.article'	: [ 'h1' ]
121 		 *		}
122 		 *	}
123 		 * </pre>
124 		 *
125 		 * The hash keys of the editables are css selectors. For a
126 127 		 *
128 		 * <pre>
129 		 *  <div class="article">content</div>
130 		 * </pre>
131 		 *
132 		 *  the selectors 'div' and '.article' match and the returned configuration is
133 		 *
134 		 * <pre>
135 		 *  [ 'b', 'i', 'h1']
136 		 * </pre>
137 		 *
138 		 * The '#title' object would return an empty configuration.
139 		 *
140 		 * <pre>
141 		 *  [ ]
142 		 * </pre>
143 		 *
144 		 *  All other objects would get the 'config' configuration. If config is not set
145 		 * the plugin default configuration is returned.
146 		 *
147 		 * <pre>
148 		 *  [ 'b', 'h1']
149 		 * </pre></li>
150 		 * <li>Object configuration parameters are :
151 		 * <pre>
152 		 *	"image": {
153 		 *		config : { 'img': { 'max_width': '50px',
154 		 *		'max_height': '50px' }},
155 		 *		editables : {
156 		 *			'#title': {},
157 		 *			'div': {'img': {}},
158 		 *			'.article': {'img': { 'max_width': '150px',
159 		 *			'max_height': '150px' }}
160 		 *		}
161 		 *	}
162 		 * </pre>
163 		 *  The '#title' object would return an empty configuration.<br/>
164 		 *  The 'div' object would return the default configuration.<br/>
165 		 *  the '.article' would return :
166 		 *  <pre>
167 		 *		{'img': { 'max_width': '150px',
168 		 *		'max_height': '150px' }}
169 		 *  </pre>
170 		 * </li>
171 		 *
172 		 * @param {jQuery} obj jQuery object of an Editable Object
173 		 * @return {Array} config A Array with configuration entries
174 		 */
175 		getEditableConfig: function (obj) {
176 			var configObj = null,
177 				configSpecified = false,
178 				that = this;
179 
180 			if (this.settings.editables) {
181 				// check if the editable's selector matches and if so add its configuration to object configuration
182 				jQuery.each(this.settings.editables, function (selector, selectorConfig) {
183 					var k;
184 					if (obj.is(selector)) {
185 						configSpecified = true;
186 						if (selectorConfig instanceof Array) {
187 							configObj = [];
188 							configObj = jQuery.merge(configObj, selectorConfig);
189 						} else if (typeof selectorConfig === "object") {
190 							configObj = {};
191 							configObj['aloha-editable-selector'] = selector;
192 							for (k in selectorConfig) {
193 								if (selectorConfig.hasOwnProperty(k)) {
194 									if (selectorConfig[k] instanceof Array) {
195 										//configObj[k] = [];
196 										//configObj[k] = jQuery.extend(true, configObj[k], that.config[k], selectorConfig[k]);
197 										configObj[k] = selectorConfig[k];
198 									} else if (typeof selectorConfig[k] === "object") {
199 										configObj[k] = {};
200 										configObj[k] = jQuery.extend(true, configObj[k], that.config[k], selectorConfig[k]);
201 									} else {
202 										configObj[k] = selectorConfig[k];
203 									}
204 								}
205 							}
206 						} else {
207 							configObj = selectorConfig;
208 						}
209 					}
210 				});
211 			}
212 
213 			// fall back to default configuration
214 			if (!configSpecified) {
215 				if (typeof this.settings.config === 'undefined' || !this.settings.config) {
216 					configObj = this.config;
217 				} else {
218 					configObj = this.settings.config;
219 				}
220 			}
221 
222 			return configObj;
223 		},
224 
225 		/**
226 		 * Make the given jQuery object (representing an editable) clean for saving
227 		 * @param obj jQuery object to make clean
228 		 * @return void
229 		 */
230 		makeClean: function (obj) {},
231 
232 		/**
233 		 * Make a system-wide unique id out of a plugin-wide unique id by prefixing it with the plugin prefix
234 		 * @param id plugin-wide unique id
235 		 * @return system-wide unique id
236 		 * @hide
237 		 * @deprecated
238 		 */
239 		getUID: function (id) {
240 			console.deprecated('plugin', 'getUID() is deprecated. Use plugin.name instead.');
241 			return this.name;
242 		},
243 
244 		/**
245 		 * Return string representation of the plugin, which is the prefix
246 		 * @return name
247 		 * @hide
248 		 * @deprecated
249 		 */
250 		toString: function () {
251 			return this.name;
252 		},
253 
254 		/**
255 		 * Log a plugin message to the logger
256 		 * @param level log level
257 		 * @param message log message
258 		 * @return void
259 		 * @hide
260 		 * @deprecated
261 		 */
262 		log: function (level, message) {
263 			console.deprecated('plugin', 'log() is deprecated. Use Aloha.console instead.');
264 			console.log(level, this, message);
265 		}
266 	});
267 
268 	/**
269 	 * Static method used as factory to create plugins.
270 	 * 
271 	 * @param {String} pluginName name of the plugin
272 	 * @param {Object} definition definition of the plugin, should have at least an "init" and "destroy" method.
273 	 */
274 	Plugin.create = function (pluginName, definition) {
275 
276 		var pluginInstance = new (Plugin.extend(definition))(pluginName);
277 		pluginInstance.settings = jQuery.extendObjects(true, pluginInstance.defaults, Aloha.settings[pluginName]);
278 		PluginManager.register(pluginInstance);
279 
280 		return pluginInstance;
281 	};
282 
283 	return Plugin;
284 });
285