Esta documentación corresponde a Magnolia 5.3 en castellano y contiene sólo parte del total de los contenidos. Para la documentación completa consulte la versión en inglés o la documentación de Magnolia 5.4 para una versión mas reciente.

En este tutorial, crearás tu primera content app. Una aplicación de contenidos es un tipo especial de app que sirve para gestionar contenidos como por ejemplo productos. Los contenidos en este ejemplo son coches antiguos pero puedes usar cualquier tipo de contenido. (warning) Magnolia 5.2.3

     

Crea un módulo

Tu aplicación de contenidos necesita estar desplegado como un módulo de Magnolia. Elige entre estas opciones dependiendo de tu nivel de habilidad.

Opción 1: Clonar el proyecto en Git

Elige esta opción si sabes como trabajar con un proyecto de Magnolia y Git. Con esta opción obtienes un proyecto que puedes editar en tu IDE y personalizarlo a tus necesidades.

  1. Clona lel repositorio app-tutorial.
git clone http://git.magnolia-cms.com/git/documentation/app-tutorial.git
  1. fake
  2. Importa el proyecto en tu IDE. Aqui tienes como se ve el project en IntelliJ IDEA:
  3. Construye el proyecto creando un JAR y despliégalo en una instancia de magnolia. O simplemente ejecuta el proyecto en tu IDE.

Opción 2: Descarga el módulo en formato JAR

Elige esta opción is eres nuevo en Magnolia. Descarga el módulo JAR y sigue las instrucciones estándar de instalación de módulos. De esta manera obtienes la aplicación de contenidos completa y puedes aprender cómo funciona.

  1. Descarga el  JAR file  magnolia-app-tutorial  de Nexus.
  2. Copia el JAR en la carpeta  <CATALINA_HOME>/webapps/<contextPath>/WEB-INF/lib. Típicamente esto está en <CATALINA_HOME>/webapps/magnoliaAuthor/WEB-INF/lib.
  3. Reinicia tu instancia de Magnolia y ejecuta la actualización via Web. Esto instalará el módulo App Tutorial.

Contenido del Módulo

El módulo contiene los siguientes archivos:

Configuración de la aplicación

La mejor manera de aprender es cambiar cosas y ver el efecto que tiene. Ve a Configuración > /modules/app-tutorial para encontrar la configuración.

Node nameValue
 
server
 

 
modules

 

 
app-tutorial

 

 
version

1.3.4-SNAPSHOT

Descriptor de la aplicación

El descriptor de app describe la configuración de una aplicación. El descriptor asigna a la aplicación un nombre, un icono y una clase de implementación. El nombre del nodo de configuración debe ser único ya que es usado para referenciar la aplicación en todo el sistema. Esto significa que no esta permitido usar pages como nombre ya que existe una aplicación Pages app con ese nombre. 

Node nameValue

 
modules

 

 
app-tutorial

 

 
apps

 

 
products

 

 
appClass

info.magnolia.ui.contentapp.ContentApp

 
class

info.magnolia.ui.contentapp.ContentAppDescriptor

 
version

1.3.4-SNAPSHOT

App launcher layout

En el app launcher layout agregamos la aplicación al grupo Edición.

Node name

 
modules

 
ui-admincentral

 
config

 
appLauncherLayout

 
groups

 
edit

 
apps

 
pages

 
assets

 
contacts

 
products

Ve al app launcher y verifica que puedes ver el icono Productos.

Si mueves la aplicación a otro grupo, cierra sesión y vuelve a entrar para ver el cambio.

Subapp browser

La subapp browser encontrada en /modules/app-tutorial/apps/products permite ver y organizar contenidos. Es parte de cualquier aplicación de contenidos.

Node nameValue

 
modules

 

 
app-tutorial

 

 
apps

 

 
products

 

 
subApps

 

 
browser

 

 
class

info.magnolia.ui.contentapp.browser.BrowserSubAppDescriptor

 
subAppClass

info.magnolia.ui.contentapp.browser.BrowserSubApp

Content connector

(warning) Magnolia 5.3+

Un content connector le comunica a la aplicación donde se encuentra el contenido. En este caso nosotros guardamos los productos en el repositorio así que usamos el JCR content connector. La configuración identifica el workspace y el path. También configura el tipo de nodo sobre el que opera la aplicación de contenidos.

Node nameValue
 
subApps
 

 
browser

 

 
contentConnector

 

 
nodeTypes

 

 
product

 

 
icon

icon-items

 
name

mgnl:product

 
defaultOrder

jcrName

 
includeProperties

false

 
rootPath

/

 
workspace

products

Workbench

El workbench es una vista que muestra una lista de contenidos en un workspace. Es parte del framework de aplicaciones de contenido, y es usualmente definido en la subapp browser. El workbench puede mostrar los contenidos en vistas de árbol, lista y thumbnails. También provee una caja de búsqueda. En la deficnión del workbench se especifica el workspace sobre el cual se muestran los contenidos y qué tipos de nodos se muestran.

En esta aplicación, el workbench muestra dos tipos de nodo: mgnl:folder y mgnl:product.

(warning) Magnolia 5.2.5 e inferiores

Node nameValue

 
browser

 

 
workbench

 

 
nodeTypes

 

 
product

 

 
icon

icon-items

 
name

mgnl:product 

 
folder

 

 
icon

icon-folder

 
name

mgnl:folder

 
defaultOrder

jcrName

 
dropConstraintClass

info.magnolia.ui.workbench.tree.drop.AlwaysTrueDropConstraint

 
editable

false

 
includeProperties

false

 
path

/

 
workspace

products

(warning) Magnolia 5.3+: nodeTypes, path y workspace son movidos al nodo Content connector en 5.3, como se muestra a continuación.

Node nameValue

 
browser

 

 
workbench

 

 
defaultOrder

jcrName

 
dropConstraintClass

info.magnolia.ui.workbench.tree.drop.AlwaysTrueDropConstraint

 
editable

false

 
includeProperties

false

Vistas del contenidos

Una vista de contenido define cómo el contenido es mostrado al usuario. Debajo de workbench, nosotros tenemos tres vistas: árbol, lista, thumbnail y búsqueda. La vista de árbol define tres columnas: NombreEstadoFecha de modificación. Las otras vistas extienden la vista de árbol, desplegando las mismas columnas.

Node nameValue
 
workbench
 

 
contentViews

 

 
tree

 

 
columns

 

 
jcrName

 

 
class

info.magnolia.ui.workbench.column.definition.PropertyColumnDefinition

 
editable

true

 
label

Product name

 
propertyName

jcrName

 
sortable

true

 
status

 

 
class

info.magnolia.ui.workbench.column.definition.StatusColumnDefinition

 
displayInChooseDialog

false

 
formatterClass

info.magnolia.ui.workbench.column.StatusColumnFormatter

 
label

Status

 
width

45

 
moddate

 

 
class

info.magnolia.ui.workbench.column.definition.MetaDataColumnDefinition

 
displayInChooseDialog

false

 
formatterClass

info.magnolia.ui.workbench.column.DateColumnFormatter

 
label

Modification date

 
propertyName

mgnl:lastModified

 
sortable

true

 
width

160

 
class

info.magnolia.ui.workbench.tree.TreePresenterDefinition

 
list

 

 
columns

 

 
extends

../../tree/columns

 
class

info.magnolia.ui.workbench.list.ListPresenterDefinition

 
thumbnail

 

 
class

info.magnolia.ui.workbench.thumbnail.ThumbnailPresenterDefinition

 
search

 

 
columns

 

 
extends

../../tree/columns

 
class

info.magnolia.ui.workbench.search.SearchPresenterDefinition

Ésta es la vista de árbol:

Prueba las otras vistas también. La búsqueda es sensible mayúsculas y minúsculas por defecto.

Acciones

Las acciones te permiten agregar, editar y borrar carpetas y productos. Cada acción es adherida a un action definition.

Node nameValue
 
browser
 

 
actions

 

 
addProduct

 

 
availability

 

 
nodeTypes

 

 
folder

mgnl:folder

 
root

true

 
appName

products 

 
class

info.magnolia.ui.contentapp.detail.action.CreateItemActionDefinition

 
icon

icon-add-item

 
nodeType

mgnl:product

 
subAppId

detail

 
addFolder

 

 
availability

 

 
root

true

 
class

info.magnolia.ui.framework.action.AddFolderActionDefinition

 
icon

icon-add-folder

 
editFolder

 

 
deleteFolder

 

 
editProduct

 

 
deleteProduct

 

Barra de acciones

La barra de acciones pone a disposición del usuario acciones a realizar. La barra de acciones esta normalmente situada en el lado derecho de la subapp browser. La definición de barra de acciones organiza las acciones en secciones (etiquetas verdes) y grupos (entre líneas horizontales). Las reglas de disponibilidad determinan cual sección es desplegada al usuario. Por ejemplo, cuando el usuario selecciona un contenido en la subapp browser, las reglas de disponibilidad permitirán que sólo las acciones relevantes sean mostradas. Un grupo contiene acciones que tienen algo en común, como las acciones para agregar elementos.

Node nameValue

 
browser

 

 
actionbar

 

 
sections

 

 
root

 

 
groups

 

 
addActions

 

 
items

 

 
addProduct

 

 
addFolder

 

 
availability

 

 
nodes

false

 
root

true

 
folder

 

 
product

 

 
defaultAction

editProduct

Proveedor de imágenes

Image provider es un componente que pinta imágenes usadas en aplicaciones. Genera la imagen vertical en la parte baja de la barra de acciones y los thumbnails en la vista de thumbnails.

Node nameValue

 
browser

 

 
imageProvider

 

 
class

info.magnolia.ui.imageprovider.definition.ConfiguredImageProviderDefinition

 
imageProviderClass

info.magnolia.ui.imageprovider.DefaultImageProvider

 
originalImageNodeName

photo

Selecciona un contenido en el browser subapp para probar la vista preliminar. La vista preliminar es mostrada en la parte baja de la barra de acciones.

Subapp detail

Una subapp de detalle te permite editar un producto. Ésta es configurada con un subapp descriptor tal como se hace con la subapp browser pero las clases son diferentes.

Node nameValue

 
subApps

 

 
detail

 

 
class

 info.magnolia.ui.contentapp.detail.DetailSubAppDescriptor

 
subAppClass

 info.magnolia.ui.contentapp.detail.DetailSubApp

Content connector

(warning) Magnolia 5.3+

Un JCR content connector también es necesario en la subapp detail. Sin embargo, la definición es mas sencilla. Tan sólo necesitas indicar el nombre del workspace.

Node nameValue
 
subApps
 

 
browser

 

 
contentConnector

 

 
workspace

products

 
rootPath

/

Nota: La propiedad rootPath mostrada arriba tiene el mismo valor que el contentConnector de la subapp browser, para ser precisos: estas propiedades deben tener el mismo valor. Sin embargo, debido a que "/" es el valor por defecto de rootPath, esta propiedad puede ser omitida en ambas secciones de configuración. Para simplificar tu configuración es razonable que el contentConnector de la subapp browser extienda el contentConnector de la subapp detail.

Editor

El editor es un componente que edita un contenido. El editor típicamente contiene un formulario. En una aplicación de contenidos, deberás crear una definición de editor debajo de la subapp detail . Esto define los tipos de nodo que el editor puede editar, un form para editarlos y acciones para guardar lo editado.

Node nameValue

 
detail

 

 
editor

 

 
nodeType

 

 
icon

icon-items

 
name

mgnl:product

 
workspace

products

Formulario

Tu aplicación puede editar cualquier tipo de contenido. Lo que planees editar determina los campos que necesitarás en el formulario. En este tutorial los contenidos son productos, así que creamos un formulario con tres campos, nombre, foto y créditos de la foto.

Node name

Value

 
editor

 

 
actions

 

 
commit

 

 
save

 

 
form

 

 
tabs

 

 
product

 

 
fields

 

 
name

 

 
class

info.magnolia.ui.form.field.definition.TextFieldDefinition

 
name

jcrName

 
fileUpload

 

 
allowedMimeTypePattern

image.*

 
binaryNodeName

photo

 
class

info.magnolia.dam.asset.field.definition.DamUploadFieldDefinition

 
photoCredit

 

 
class

info.magnolia.ui.form.field.definition.TextFieldDefinition

Acciones para guardar y cancelar

Commit y cancel son acciones reusables que guardan la información de formularios. Están definidas en la subapp detail. Los botones de la caja de diálogo que las ejecutan se encuentran en el editor (ver arriba).

Node nameValue

 
detail

 

 
actions

 

 
commit

 

 
class

info.magnolia.ui.form.action.SaveFormActionDefinition

 
implementationClass

info.magnolia.ui.form.action.SaveFormAction

 
cancel

 

 
class

info.magnolia.ui.form.action.CancelFormActionDefinition

Crea un par de contenidos y verifica que puedes editarlos también.

Ahora, hazlo tu mismo

Hay muchas maneras de crear tu propia aplicación de contenidos:

Opción 1: Copiar una app

  1. Copia la configuración de nodos de una aplicación de contenidos existente a la nueva aplicación. Puedes copiar una de la aplicaciones nativas de Magnolia, por ejemplo Contacts.
  2. Exporta la configuración de los nodos a XML mediante Export.
  3. Abre el XML en un editor de texto. Busca y reemplaza los nombres de los contenidos. Por ejemplo, si tu aplicación gestiona manzanas en vez de naranjas, reemplaza manzana con naranja.
  4. Importa el XML en Magnolia.
  5. Registra un nuevo workspace en el descriptor del módulo y crea un nuevo tipo de nodo.

Opción 2: Extiende una aplicación

Este método funciona bien si una de las aplicaciones nativas de Magnolia hace la mayoría de lo que necesitas. No tienes que cambiar mucho. Extiende la aplicación nativa para obtener todas sus funcionalidades y agregar algo especial. Por ejemplo, configura una aplicación especial Páginas que muestre sólo una rama del sitio web. Si los editores mayormente trabajan en esa rama, la aplicación les ahorrará tener que navegar allí.

  1. Extiende una aplicación existente para heredar la configuración. Por ejemplo, mira cómo la aplicación JCR Browser extiende la aplicación Configuración heredando sus subapps.
  2. Define las excepciones en tu propia aplicación.

Mirar también 3.3.5 Create an app en Magnolia Academy.

Mejoras

Aquí proponemos ideas para mejorar tu aplicación de contenidos y prepararla para su uso en producción:

Agrega acciones de importación y exportación

Agrega acciones de importación y exportación, para así poder exportar productos a XML (ver export). Mira cuántas acciones están implementadas en la Contacts app. Copia la configuración a tu aplicación. El framework de Magnolia UI provee acciones genéricas para importar y exportar que están listas para ser usadas.

Import and export actions in the Contacts app
/modules/contacts/apps/contacts/subApps/browser/actions/export
/modules/contacts/apps/contacts/subApps/browser/actions/import
/modules/contacts/apps/contacts/subApps/browser/actionbar/sections/root/groups/importExportActions
/modules/contacts/apps/contacts/subApps/browser/actionbar/sections/contact/groups/importExportActions
/modules/contacts/apps/contacts/subApps/browser/actionbar/sections/folder/groups/importExportActions

Agregar acciones de publicación

Agregar acciones activate y deactivate para poder publicar productos a la instancia pública. Copia las acciones de la aplicación Contactos.

Para agregar la funcionalidad de publicación:

  1. Agrega acciones activate y deactivate para poder publicar productos a la instancia pública. Copia las acciones de la aplicación Contactos.
  2. Agrega las acciones  activate y deactivate en la barra de acciones. Copia esto de la aplicación Contactos.
  3. Agrega una subscripción al workspace products para que las instancias públicas reciban el contenido.

(warning) ¡No olvides instalar tu módulo también en la instancia pública! Puede que no necesites la aplicación en la instancia pública pero necesitas el workspace products para que los productos puedan ser activados.

Agrega la aprobación de borrado

Evita que los editores eliminen productos con un simple click. La mejor práctica es marcar un contenido para borrado y requerir que el editor publique el cambio:

  1. Despliega un mensaje de confirmación, preguntando si el usuario realmente quiere eliminar el contenido.
  2. Marca el contenido como borrado.
  3. Activa el cambio. Esto finalmente elimina el contenido.

Mira cómo la aplicación de Contactos gestiona esto y replica las acciones en tu aplicación. Mira además cómo la regla de disponibilidad info.magnolia.ui.api.availability.IsNotDeletedRule es usada en la acción activate para asegurar que el contenido activable no esta marcado para borrado. Para mas información puedes consultar action availability rule.

 


Créditos: