BasePlugin_es

Sobre el nombre

El archivo BasePlugin.js contiene la definición de Ediphy.Plugin, que supone una capa de abstracción sobre los plugins para facilitar al desarrollador su creación. Es por esto que el archivo se llama de este modo, porque es una especie de base para los plugins, y a partir de ahora, cuando se quiera hacer referencia a Ediphy.Plugin, se hará indistintamente de este modo o usando BasePlugin.

Funcionalidad

La razón de la necesidad de esta "clase" es porque a la hora de definir la funcionalidad que se desea en un plugin, se detectaron patrones en el código que eran repetidos muy a menudo o llamadas a funciones con parámetros que hacían que el código fuera un poco confuso. Por esto, se decidió mover todo lo común de los plugins a BasePlugin, para simplificar el proceso de creación de plugins.

En cierto modo, BasePlugin se comporta como una clase estática, ya que aunque se instancie para cada uno de los plugins, estas instancias son indistinguibles dentro de un mismo tipo de plugin. Es por esto que BasePlugin necesita tener cierta información sobre la instancia con la que está trabajando en concreto, para poder aplicar los cambios necesarios usando las funciones definidas y luego reenviárselos al núcleo de la aplicación.

Estructura

Tiene las siguientes propiedades privadas:

• descendant: es una variable que almacena la definición del plugin que se desea para poder acceder a sus métodos. Al instanciar BasePlugin, queda ya guardado el tipo de plugin que se usa y se puede acceder a través de esta variable a la definición, ya que no cambia. En cierto modo, es un descendiente de BasePlugin, de ahí el nombre.
• state: es una variable que almacena el estado concreto definido para el plugin. Cada vez que se llama a algún método, se actualiza si es ne cesario, ya que es gracias a esto por lo que se puede distinguir entre instancias del mismo tipo de plugin. En caso de que el plugin contuviera a otros, tiene una propiedad generada automáticamente llamada "__pluginContainerIds" que contiene información sobre los contenedores de plugins definidos en la plantilla.
• id: almacena el id asignado en el núcleo al EditorBox que contiene a este plugin para poder saber a quién aplicar los cambios que se deseen.
• initialParams: objeto que almacena una serie de parámetros iniciales que debe tener en cuenta el núcleo a la hora de crear el EditorBox contenedor del plugin, como por ejemplo la posición.
• defaultFor: función que recibe tres parámetros, "arg", "value" y "warn". Asigna el valor "value" a "arg" en caso de que este no estuviera definido y lanza el mensaje "warn" por la consola si está definido. Sirve para asignar valores por defecto a variables.
• assignPluginContainerIds: método que, dado el JSON al que es convertido el HTML generado por las plantillas definidas en el plugin, modifica los <plugin /> asignándoles los atributos correspondientes encontrados en la propiedad "__pluginContainerIds" del estado si los hubiera. La primera vez que se renderiza el plugin no es usado, pero al ser creados los sortableContainers en el núcleo y asignados unos identificadores, estos se guardan en esa propiedad del estado del plugin mencionada anteriormente. Gracias a esto es por lo que al volver a renderizar el plugin, los plugins contenidos en él no son borrados.

Tras esto, vienen los métodos "públicos":

• create: este es el método usado para asignar a la instancia del Ediphy.Plugin la definición del plugin que se quiere usar y guardarlo en descendant. Además, se asigna a sí mismo todas las funciones de descendant que no sean las indicadas más abajo, ya que se supone que serán funciones necesarias para el correcto funcionamiento del mismo, como controladores de eventos y funciones auxiliares.
• init: es una función que inicializa el plugin llamando al método de la API addMenuButton que pasa como parámetro la configuración del plugin. Lo habitual es que el componente PluginRibbon esté escuchando el evento lanzado por addMenuButton ya que es el encargado de pintar los botones en la aplicación. Además, si descendant tiene definido su propio init, se ejecuta.
• getConfig: este método se asegura de que el objeto de configuración del plugin está completo y que no le falta ninguna propiedad para posteriormente devolverlo. Intenta coger los valores del getConfig de descendant, y si alguna propiedad no estuviera definida, entonces le asigna un valor por defecto. Estas propiedades son:
• name: nombre del plugin (aparecerá también en la aplicación). Por defecto toma el valor "PluginName".
• category: categoría del plugin, ya que en la aplicación existe la capacidad de filtrar plugins por categoría. Por defecto, se define como texto ("text").
• needsConfigModal: booleano que indica si es necesario el modal de configuración o no. Si no se define, se le asigna el valor "falso".
• needsTextEdition: booleano que indica si el plugin necesita de las herramientas preparadas para que pueda contener texto editable. Además, si esta variable es positiva, se crea una propiedad oculta en el estado del plugin llamada "__text" que almacena la salida del CKEditor, usada como plantilla para generar el HTML de manera automática si no está definida en el plugin (es el único caso posible). Por defecto, es negativa.
• icon: es una cadena de texto con uno de los valores proporcionados por FontAwesome
• aspectRatioButtonConfig: si se desea que el plugin tenga la opción de bloquear la relación de aspecto para que al redimensionarlo esta no se pierda, se ha de configurar usando esta propiedad. Es un objeto con tres claves, "name", que define la etiqueta que aparecerá junto al botón en la barra de herramientas (por defecto, "Aspect Ratio"), "location", que especifica la localización en la que se desea poner dicho botón (es un array en el que se indican los nombres de la pestaña y acordeón u acordeones, ya que se permite un nivel de anidamiento. Si no se especifica, aparecerá en "other"/"extra") y "defaultValue", que indica el valor inicial que va a tener, activo o inactivo.
• callback: esta propiedad no debe definirse en el plugin ya que se genera automáticamente, si se le asignara algún valor, este será sobreescrito. Aquí se define la función que se ejecutará al interactuar con el botón del plugin y puede recibir como parámetro una configuración inicial (como pueda ser la posición o el tamaño) que se guarda en initialParams. Si el plugin declara getInitialState entonces state pasará a valer lo devuelto por esta función, si no será un objeto vacío. Además, como se ha mencionado anteriormente, si needsTextEdition es positivo, se creará la propiedad "__text" en state. Por último, si needsConfigModal es positivo, entonces se llama a openConfigModal para invocar el modal de configuración, en caso contrario, llama a render y en ambas situaciones llama a estas funciones indicando que es la primera vez que se ejecutan.
• VER SECCIÓN DE CREACIÓN DE PLUFGINS PARA VER EL RESTO DE LOS CAMPOS DE getConfig
• getToolbar: devuelve la barra de herramientas definida en el plugin en caso de estarlo, si no un objeto vacío. Al igual que en getConfig, se asegura que está correctamente formada para evitar fallos en la aplicación, indicando los errores cometidos. La barra de herramientas debe tener dos propiedades, "__name" (el nombre que aparecerá en la parte correspondiente en la aplicación) y "accordions", que contiene los acordeones deseados, que sirven para agrupar los botones. Esta propiedad, es a su vez un objeto que tiene una propiedad "__name", otra llamada "buttons" que contiene la definición de los botones y puede tener una propiedad llamada "accordions" para definir más acordeones dentro de sí mismo. En caso de contenerla, ha de tener también un array llamado "order" que indica mediante sus claves el orden en el que se quieren renderizar los botones y los acordeones pertenecientes al acordeón que se está definiendo (los botones definidos en un subacordeón no deben aparecer aquí). Por último, los botones deben tener también una propiedad "__name" y si definen una propiedad llamada "autoManaged" como falsa, entonces automáticamente se les asignará una propiedad "callback" que será la función update definida más abajo. Esto es así porque en general, los botones controlarán cosas sencillas relativas al estilo, como pueda ser la opacidad o el borde del EditorBox y los botones pueden ser "autogestionados". Sin embargo, si se desea que un botón haga algo más complejo como pueda ser modificar la disposición de los elementos del plugin, entonces es necesario indicar de qué modo quiere hacerse y es a través de la función update.
• openConfigModal: esta función se encarga de pedir que se abra el modal de configuración y poblarlo con el contenido correspondiente. Es por esto que recibe tres parámetros, un booleano indicando si es la primera vez que se usa o no (necesario para posteriormente pasárselo a render), el estado del plugin (almacenado en el estado del núcleo) y el identificador del EditorBox (para que los cambios realizados se puedan asignar al contenedor adecuado). Si descendant no ha definido su plantilla de configuración (devuelta por getConfigTemplate) lanzará un error, en caso contrario, al recibir la respuesta de la API openConfig, el <div> que esta devuelve será poblado con la plantilla de configuración.
• forceUpdate: es un método que renueva los valores de state y sender y llama a render para forzar la actualización del contenido del plugin. Se usa por ejemplo cuando tenemos una barra de herramientas que genera los botones de manera dinámica (en caso de no hacerlo de este modo, la barra de herramientas se genera de nuevo pero los valores no son almacenados en el núcleo y por tanto no se ven reflejados en la interfaz) o al cambiar el texto de un plugin que requiera de la edición de texto.
• render: esta función recibe un parámetro booleano que indica si es la primera vez que es llamada y básicamente lo que hace es obtener la plantilla definida en el plugin y llamar al método de la API renderPlugin con los parámetros adecuados. La plantilla se obtiene llamando al método getRenderTemplate de descendant (si no está definido salta un error) que recibe como parámetro el estado del plugin y posteriormente se transforma a JSON usando la librería html2json. Tras esto, se analiza el JSON generado usando el método assignPluginContainerIds del modo explicado más arriba y por último se llama a renderPlugin pasándole los parámetros necesarios.
• update: este método recibe cuatro parámetros, el estado del plugin, su identificador asignado en el núcleo, el nombre asignado al botón de la barra de herramientas que ha sido invocado y el nuevo valor del mismo. Su función es actualizar el estado y el identificador almacenados y da la oportunidad de actualizar la plantilla del plugin en función del nuevo valor dado en caso de haber definido el método handleToolbar. Es mediante este mecanismo por lo que funcionan los botones de la barra de herramientas no definidos como "autoManaged", ya que al recibir el nuevo valor asignado en el botón, el plugin puede definir un nuevo valor para el estado y como tras hacer esto se vuelve a llamar a render de manera automática, la plantilla queda actualizada en función del nuevo valor de state.
• setState: recibe una clave y un valor como parámetro y se los asigna al objeto state.
• getState: devuelve el estado del plugin state.