XalokNext Manual Tecnico

Manual técnico Documentación para instalación y desarrollo

Manual técnico

Sumario

Introducción ........................................................................................................................... 3 1. Instalación .......................................................................................................................... 4 1.1 Prerequisitos ...................................................................................................... 4 1.2 Web Server ......................................................................................................... 5 1.3 Varnish 3 ............................................................................................................. 5 1.4 MySQL .................................................................................................................. 5 1.5 Elasticsearch ...................................................................................................... 6 1.6 Redis ..................................................................................................................... 7 1.7 Estructura de directorios ............................................................................... 7 2. Descarga y deploy inicial para desarrollo ............................................................... 8

3.

4. 5.

6.

2.1 Configuración ..................................................................................................... 8 2.2 Configuración de la base de datos ........................................................... 10 2.3 Población de la base de datos ................................................................... 10 2.4 Deploy de desarrollo .................................................................................... 10 2.5 Editor inline ..................................................................................................... 12 2.6 Backbone.js ..................................................................................................... 12 Editor ................................................................................................................................ 13 3.1 Módulos HTML ................................................................................................ 13 3.2 Ejemplos de módulos HTML ....................................................................... 21 3.3 Módulos builtin .............................................................................................. 27 Base de datos ................................................................................................................. 32 Módulos de desarrollo ................................................................................................. 33 5.1. Categorías ....................................................................................................... 33 5.2. Menús ............................................................................................................... 34 5.3. Tracking (más vistas, comentadas, etc.) ................................................ 35 5.3. Rating ............................................................................................................... 36 5.4. Procesos de background ............................................................................ 37 5.5. RSS..................................................................................................................... 38 Configuraciones ............................................................................................................. 41

2

Manual técnico

Introducción Este documento describe la plataforma de Xalok Next desde un punto de vista técnico, focalizando en su arquitectura, subsistemas, componentes y módulos. La plataforma de Xalok Next está basada en el framework Symfony2.

3

Manual técnico

1. Instalación 1.1

Prerequisitos

Esta sección describe el software requerido para la ejecución de Xalok Next, explicando su operación y uso en la solución, y su interacción. La aplicación Xalok Next se ejecuta sobre cualquier sistema con un servidor web como Apache2 o Nginx, PHP 5.4 y MySql.

•

•

Módulos Webserver: o

virtual hosts

o

expires

o

rewrite

o

header (header rewriting)

PHP 5.4 con los siguientes módulos instalados: o

php5-cgi

o

php5-cli

o

php5-common

o

php5-curl

o

php5-gd

o

php5-mysql

o

php5-redis

o

php5-apc

o

php5-intl

o

php5-mcrypt

o

php-xml-serializer

o

php-xml-rss

o

php-xml-parser

o

php-net-socket

4

Manual técnico

•

Mysql 5.0

•

Varnish

•

ElasticSearch

•

Git

1.2 Web Server Dependiendo del entorno utilizado, puede ser necesario rescribir todo lo que no esté localizado en el disco duro a web/app_{environment}.php

Ejemplo de Apache mod_rewrite: RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^(.*)$ app_dev.php [QSA,L]

1.3 Varnish 3 Xalok Next utiliza Varnish para los fronts. Configuración de cache default puede ser encontrada aquí: app/config/config/public_cache.yml

Varnish. Completa información de Varnish en: https://www.varnishcache.org/docs/3.0/installati on/index.html

Pueden ser configurados tantos paths como se necesite con las siguientes reglas de cache control. - { path: {route_preg_match_sintax}, controls: { public: true, s_maxage: 600 } }

1.4 MySQL Además de la necesidad de ser codificado en UTF-8, el monitoreo y uso de la base de datos MySql no requiere ninguna configuración especial o tareas administrativas diferentes de las usualmente recomendadas.

5

Manual técnico

Iniciar y detener el manager de la base de datos MySql es realizado como es usual, utilizando el script provisto por el mismo software.

1.5 Elasticsearch Xalok Next utilize elasticsearch como motor de búsquedas. Elasticsearch es un motor de búsqueda open source con una API cliente-servidor, siendo de especial importancia su arquitectura distribuída.

Elasticsearch. Completa información en http://www.elasticsearch.org /guide/

Algunas de sus características son: •

Facilidad de configuración, simplica los procesos de set-up.

•

Arquitectura diseñada para la distribución, lo cual permite escalar nodos proveer y alta disponibilidad, soportando grandes cantidades de datos con cortos tiempos de respuesta.

•

Resultados en tiempo real.

•

Brinda RESTful HTTP API, y usa JSON para peticiones y resultados. También puede ser operado utilizando la API nativa en Java.

•

Es free-schema, no es necesario tener una definición explícita de esquema (fácil configuración).

•

Soporta multitenancy, incluyendo indices y tipos multiples (tipos en un CMS), y la posibilidad de búsquedas en cualquier combinación de ambos.

•

Cumple con las propiedades ACID de los sistemas transaccionales, en nivel de documento.

•

Basado en Lucene.

El archivo de configuración de elasticsearch puede ser encontrado en la siguiente ubicación: app/config/misc/fos_elastica.yml

6

Manual técnico

Este archive es usado por FOSElasticaBundle, una documentación completa puede ser encontrada aquí: https://github.com/Exercise/FOSElasticaBundle

1.6 Redis El servidor Redis es utilizado para comentarios y pageviews, pero también almacena el listado de los artículos publicados, siendo de utilidad para agilizar y hacer más rápida las queries a los artículos en frontend.

Redis. Completa información en http://redis.io/documentatio n

Por defecto Redis almacena la información en memoria RAM y cada cierta cantidad de segundos escribe la información en disco. Los pageviews, más vistas, más comentados y comentarios son de los servicios más requeridos del CMS.

1.7 Estructura de directorios Como antes fue mencionado, Xalok Next fue desarrollado con el framework Symfony2. La estructura de directorios es la sugerida por Symfony2. app/: Configuración de la aplicación; src/: Código PHP del proyecto; vendor/: Dependencias third-party; web/: Directorio raíz del web. Más información sobre la estructura de directorios puede ser encontrada en: http://symfony.com/doc/current/quick_tour/the_archi tecture.html

7

Manual técnico

2. Descarga y deploy inicial para desarrollo La descarga y deploy inicial de la plataforma puede ser hecho desde Webflow Technologies Update Channel, el cual se basa en infraestructura SSH+GIT. La primera cosa a hacer es crear la clave de acceso para el usuario de deploy: $ ssh-keygen -t rsa -b 2048 Una vez la clave generada, debe ser enviada al equipo de Update Channel con la siguiente información: Client name: el nombre del cliente. Contact person: la persona a cargo del deploy. Deployment key: contenidos de la clave pública generada en el archivo /~/.ssh/id_rsa.pub Finalmente, una vez recibida la confirmación de inscripción, el software puede ser descargado a través de comandos git por el usuario de deploy en el directorio web: $ git clone /var/www/ $ cd /var/www/

2.1 Configuración #change this to whatever user your web server is using $ export WWEB_USER=www-data (apache user or nginx user ... whathever webserver user are u using) $ export SF_ENV=local_admin_dev (admin environment) $ export SF_HOST=localhost (the host from which the app will run; required for fixtures) $ export DERIVED_DIRS="web/uploads web/files app/var app/cache app/logs app/elasticsearch app/Resources/translations"

8

Manual técnico

#just in case it was installed before $ rm -rf vendor/* $ rm -rf app/cache/* $ rm -rf app/logs/* $ rm -rf web/files/* $ rm -rf web/uploads/* #in app/config copy config_local.yml.sample and parameters_local*.yml.sample #and change values for your setup $ curl -s https://getcomposer.org/installer | php $ php composer.phar install $ mkdir $DERIVED_DIRS

#on MAC OSX $ sudo chmod -R +a "$WWEB_USER allow delete,write,append,file_inherit,directory_inherit" $DERIVED_DIRS $ sudo chmod -R +a "`whoami` allow delete,write,append,file_inherit,directory_inherit" $DERIVED_DIRS #on Debian #optional, if acl is not installed $ sudo apt-get install acl #edit /etc/fstab and add to the project partition acl $ sudo mount -o remount,acl /home #end optional $ sudo setfacl -R -m u:$WWEB_USER:rwx -m u:`whoami`:rwx $DERIVED_DIRS $ sudo setfacl -dR -m u:$WWEB_USER:rwx -m u:`whoami`:rwx $DERIVED_DIRS

9

Manual técnico

2.2 Configuración de la base de datos #before creating the database you shoud create parameters, config files for your running environment #you have also some sample files there for each type #app/config/parameters/ and app/config/config #after you create the config files you can create also app file in web folder $ ./app/console --env=$SF_ENV doctrine:schema:drop --force $ ./app/console --env=$SF_ENV doctrine:database:create $ ./app/console --env=$SF_ENV doctrine:schema:create

2.3 Población de la base de datos #download elasticsearch and install it if is necessary currently the CMS is using elasticsearch 0.90.1 http://www.elasticsearch.org/downloads/ #start elastica server before loading the fixtures $ sudo ./bin/elasticsearch $ ./app/console --env=$SF_ENV doctrine:fixtures:load

2.4 Deploy de desarrollo #Add symlinks to public assets $ cd web $ ln -s bundles/[project]cms/javascripts $ ln -s bundles/[project]cms/stylesheets css $ ln -s bundles/[project]cms/images

# !!! install compass (for development environment) #compass compile for creating css files from sass files

10

Manual técnico

$ compass compile --force src/[project]/Bundle/CmsBundle/Resources/public/ $ compass compile --force src/[project]/Bundle/CmsAdminBundle/Resources/pub lic/

#OPTIONALY for development environment #watching sass modifications and compile them automaticaly $ cd src/[project]/Bundle/CmsBundle/Resources/public; compass watch $ cd src/[project]/Bundle/CmsAdminBundle/Resources/pub lic; compass watch

#install virtual host and define public_site_name and admin_site_name #if you use apache you have also .htaccess sample to web folder

#!!! install redis at least version 2 #Tracking pageviews/comments $ cd src/Wf/Bundle/TrackingBundle/Resources/node_app; npm install

#start the tracking server $ ./app/console --env=$SF_ENV wf:tracking:nodejs:start # HELPING command for reload boards: $ ./app/console --env=$SF_ENV wf:cms:reload:board

11

Manual técnico

2.5 Editor inline El editor in-line es principalmente utilizado para editar boards y artículos en modo WYSISWYG. Se encuentra en: src/Wf/Bundle/CmsEditorBundle (more exactly in Resources/public/javascripts)

2.6 Backbone.js La arquitectura del editor in-line está basada en el framework backbone.js. Una completa documentación de backbone.js puede ser encontrada en:

Backbone. Completa información en http://backbonejs.org/

12

Manual técnico

3. Editor 3.1 Módulos HTML A partir de versión 2.1.0 es posible definir y configurar los módulos disponibles, en un template utilizando markup HTML. Por ejemplo:

Opciones disponibles para todos los módulos wf-role: Se usa en las templates de artículo para determinar el rol del módulo. Roles posibles son: title: el título supra: el cintillo, texto encima del título epigraph: el sumario, párrafo introductorio signature: la firma, campo conteniendo el nombre del editor o la agencia location: localización geográfica de la noticia image: la imagen principal del artículo, la imagen elegida en este módulo es también utilizada para auto-poblar los módulos con imágenes cuando el artículo es seleccionado en una board image_captioned: se utiliza este en lugar de image si la imagen principal tiene leyenda paragraph: se utiliza para párrafos normales (body text)

wf-toolbar-position: Controla la posición de la toolbar respecto al modulo actual. Usar uno de: top, left, right, bottom o none.

wf-toolbar-css-class: Usar para mostrar una toolbar más fina que la default. Esta clase es automáticamente agregada a los submódulos de un composite.

13

Manual técnico

wf-allow: Los valores disponibles son: +-: permite tanto agregar otro módulo como eliminar el módulo actual +: pemite agregar módulos debajo del actual sin eliminar el módulo actual -: permite eliminar el modulo actual

`` (empty string): este módulo es "fijo", no permite agregar otros módulos ni eliminar el actual Por ejemplo: en el template de artículo, debería haber sólo un título:

wf-new: Este atributo no contiene un valor. Si está presente, el modulo actual sera agregado automáticamente cuando una nueva página con este template sea creada Por ejemplo, el modulo título en el template de artículo debería estar siempre presente, agregar wf-new a él y configurar su atributo wf-allow a una string vacía:



wf-serializable: Disponible solo para módulos de nivel superior, módulos con roles y módulos de texto. Este atributo agrega el valor del módulo en el contenido serializado del artículo, permitiendo importar el valor de este módulo en una board.

14

Manual técnico



wf-tab y wf-tab-detail: Para cada módulo con wf-tab agregado en el selector .tabs .titles, crea un nuevo selector .tabs .body en el cual se pueden agregar módulos para ser mostrados en ese tab. Tab

Opciones para módulos wfed/body_text wf-formattings: controla cuáles opciones son mostradas para dar formato al texto. Muestra opciones de formato: negrita, cursiva y subrayado Formatos disponibles: b: negrita

15

Manual técnico

u: subrayado i: cursiva ol: lista ordenada ul: lista no ordenada a: link s: tachado Hay también algunos atajos disponibles: short: negrita, subrayado, cursiva, tachado, link lists: lista ordenada y no ordenada extended: incluye short + lists Se pueden combinar estas opciones de cualquier forma:

wf-styles: Muestra un dropdown en la lista donde los editores pueden marcar texto seleccionado con clases determinadas Muestra un dropdown permitiendo a los editores agregar un (o "bluetext") alrededor de la selección

wf-use-placeholder: Muestra el módulo aún si ningún texto ha sido modificado en él Útil para módulos que sólo tienen settings

wf-maxlength: No permite al usuario escribir más que el maxlength de caracteres definido. Un contador de caracteres es mostrado en la toolbar, por lo cual hay que asegurarse de mostrar la toolbar si wf-maxlength o wf-soft-maxlength son seteados

16

Manual técnico

wf-soft-maxlength: Muestra un warning cuando el usuario supera el maxlength de caracteres definido, pero permite al usuario continuar escribiendo.

Opciones para módulos wfed/image wf-filter: el filtro avalanche (widthxheight) de la imagen. El valor de esta opción debe ser configurado en: app/config/misc/avalanche.yml

Opciones para módulos wfed/collection wf-content-type: Los valores permitidos (builtin) son: image, video, audio, page, poll, file, listing Existe también el tipo especial none – para sliders donde el botón edit deba estar oculto y el contenido

17

Manual técnico

del slide deba ser editado manualmente. Por ejemplo: un slider donde cada slide tiene múltiples cajas/artículos. Agregar wf-content-type a la definición del slide. Esto agrega el botón edit en el toolbar del slider, permitiendo al usuario seleccionar múltiples wf-contenttype – cuando el usuario pulsa OK, un slide para cada wf-content-type es creado y agregado al slider.

Settings de módulo Muestra un botón de setting en la toolbar, permitiendo al usuario configurar el módulo actual.

wf-class: permite al editor elegir una clase CSS para el módulo, permitiendo cambiar entre variaciones del módulo. Image position Default position On the left On the right ... rest of the markup of this module/embedded submodules/etc ... Cuando el editor selecciona una de las opciones, la correspondiente clase CSS es agregada automáticamente al módulo. Por defecto, si hay menos que 5 opciones las muestra como botones de radio. Si hay más, las muestra como un element para ahorrar espacio. Si se desea sobrescribir este comportamiento, se puede explícitamente setear: para mostrarlo siempre como un elemento

18

Manual técnico

wf-multi-class: Lo mismo que wf-class, pero permite chequear multiples opciones (que son mostradas como checkboxes) Module settings Big title Image on the right ... rest of the markup of this module/embedded submodules/etc ...

wf-setting: Elemento genérico para otros tipos de settings: Title displayed as the label for this select First option Second option Se pueden usar tantos settings como se desee para cada módulo, solamente hay que asegurarse que el nombre del setting sea diferente en cada caso, esta es una de las razones por las que el nombre del atributo es requerido. ... options ...

19

Manual técnico

... options ... ... options ...

Opciones para módulos wfed/dynamic/board wf-slugs: Contenedor para elementos slug X Y

20

Manual técnico

3.2 Ejemplos de módulos HTML Módulos simples Módulo de texto simple Put a paragraph of text too

Placeholder Como este es parte de un template twig, es posible también usar traducción para el placeholder: {{ 'paragraph.placeholder'|trans({}, 'ProjectDomain') }}

Más opciones {{ 'paragraph.placeholder'|trans({}, 'ProjectDomain') }}

Módulo de imagen

21

Manual técnico

Recordar agregar el filtro avalanche_filter en app/config/misc/avalanche.yml (o utilizar uno existente)

Módulo de página compuesta Este modulo permite al usuario elegir un link a una página diferente (usada en una board)

22

Manual técnico

Agregar la clase page-link a las marcas autopoblará estas marcas con links a esa página (puede haber otros hrefs dentro del módulo que no se deseen autopoblar)

Módulo de slider

Slider con flechas ...content type module...

23

Manual técnico



Sliders con listas (solo es mostrado en la parte pública) Agregar código js a public.js: (function adaptListToSlider() { $('.slider .listing').addClass('sliderpane').find('.listing-item').addClass('slide'); })();

Módulo de board dinámica X Y

24

Manual técnico



Páginas relacionadas

Módulos switching (wf-group) {{ "most_tabs.settings.type_of_articles"|trans }}

25

Manual técnico

{{ "select"|trans }} {{ "most_tabs.settings.most_viewed"|trans }} {{ "most_tabs.settings.most_shared"|trans }}

26

Manual técnico

3.3 Módulos builtin Módulos de texto wfed/title: Módulos usados para los títulos de los artículos.

wfed/title/page_title: Estos módulos deberían ser usados sólo una vez en el template de artículo. Este módulo es usado para determinar el título del artículo (almacenado en una columna diferente en la base de datos) wfed/title/title: Al usar este módulo en boards se autocompletará con el título del artículo. wfed/title/supra: Al usar este modulo en boards se autocompletará con el antetítulo del artículo.

wfed/body_text: Módulos para ser usados en el cuerpo del artículo. wfed/body_text/paragraph: Módulo que tiene formatos (negrita, cursiva, subrayado, etc.) Opciones disponibles: - formatos que pueden ser una combinación (array) de los siguientes: - short: [b, u, i, s, a] - extended: [short, lists] - full: [extended, align] - alignment: [align-left, align-center, align-right] -lists: [ol,ul] -b:negrita -u:subrayado -i:cursiva -ol:inserter lista ordenada -ul:inserter lista no ordenada -a:crear link

27

Manual técnico

-s:tachado -styles: un array (['red', 'blue']`) con las clases CSS disponibles como un menú dropdown en la toolbar del módulo wfed/body_text/link: Link a otra URL wfed/body_text/page_epigraph: Al usar este módulo en una board poblará con el epígrafe (descripción corta) de la página seleccionada wfed/body_text/subtitle: Este modulo se puede usar templates de artículo, para subtítulos o ladillos (entre diferentes partes del artículo) wfed/body_text/published_at: Este modulo se usa en templates de artículo para mostrar los artículos publicados a la fecha. Para darle formato a la fecha, chequear: CmsBundle\Entity\PageArticle::$publishedAtFormat

Módulos de media wfed/image/: wfed/image/simple: Imagen simple, este modulo muestra una toolbar con un botón edit para que los usuarios puedan elegir una imagen. Opciones disponibles: - filter: el filtro avalanche (widthxheight) de esta imagen. El valor de esta opción debe ser configurado en app/config/misc/avalanche.yml

wfed/video/: wfed/video/linked:

28

Manual técnico

Link a un archivo de vídeo, este módulo muestra una toolbar con un botón edit para que los usuarios puedan elegir un vídeo.

Módulos compuestos Permiten combinar uno o más módulos. Una ventaja de agrupar módulos en uno compuesto es en la ordenación, sólo los módulos superiores son arrastrados, entonces con un módulo compuesto resulta posible combinar los módulos base que componen un link a un artículo en una board (título, epígrafe, imagen) para que ellos puedan ser arrastrados todos juntos.

wfed/composite/: wfed/composite/module: La base del modulo compuesto. Se usa cuando ningún otro módulo builtin compuesto se adecua a sus necesidades. wfed/composite/captioned_image: Un modulo compuesto que contiene una imagen y una leyenda (párrafo) wfed/composite/page: Link a un artículo, este módulo muestra una toolbar con un botón edit para que los usuarios puedan elegir un artículo para vincular (link). Por defecto, incluye los siguientes módulos: wfed/title/title, wfed/body_text/epigraph, wfed/image/simple

Módulos de colección Los módulos de colección son usados cuando el mismo submódulo es repetido múltiples veces (por ejemplo: sliders).

wfed/collection/: wfed/wfed/collection/collection//simple: Módulo base de colección wfed/collection/page: Colección de links a otros artículos

29

Manual técnico

wfed/collection/related: Lo mismo que wfed/collection/page pero, cuando se usa en un módulo de página compuesta, se autopuebla con los links a las páginas relacionadas de los artículos seleccionados.

wfed/gallery/: wfed/gallery/simple: Galería simple de imágenes.

wfed/slider/: wfed/slider/simple: Slider de imágenes. wfed/slider/captioned: Slider de imágenes con leyenda

Módulos miscelánea wfed/dynamic/: wfed/dynamic/board: Embebe otra board dentro de la actual board. Por ejemplo, si se tiene un widget (links a los artículos de opinión de hoy) embebido en la sidebar. Este permite reutilizar la misma board (el widget de opinión) en diferentes sidebars, posicionándola más arriba en la sidebar de la homepage y más abajo en la sidebar de una home de categoría (sección), mientras que la edición de los artículos seleccionados es hecha en un único lugar. wfed/dynamic/listing: Módulo de lista automatica. wfed/dynamic/js: Módulo de JavaScript libre, permite pegar código JavaScript, sin las marcas wfed/dynamic/ads: Módulo Ads, tiene un botón setting que permite elegir las posiciones de publicidad definidas en el Ad Manager.

30

Manual técnico

:wfed/free/: wfed/free/html: Módulo de HTML libre

wfed/file/: wfed/file/simple: Link a un archivo estático, permite hacer upload de otros tipos de archives como .pdf, .doc, etc.

31

Manual técnico

4. Base de datos Listas En la parte pública, cada identificador de página publicada es almacenado en algunos sets ordenados de Redis (uno por categoría, subcategoría, uno por cada tag, autor, etc.). Cuando se muestran algunas listas en la parte pública, en lugar de hacer consultas a MySql (join page_category join category where category.id = X), lo cual sería muy lento cuando hay muchos artículos, lo que hace el CMS es tomar los identificadores de los correspondientes sets Redis y hacer la consulta a MySql por el identificador de páginas. Sin embargo esto no resulta del todo útil ya que sólo funciona para páginas publicadas (y en particular, sólo con páginas de tipo artículo. Los identificadores de página son mantenidos en Redis ordenados por publishedAt. Lo que hace esto funcionar es el método:

vendor/wfcms/cms-base bundle/Wf/Bundle/CmsBaseBundle/Publish/Manager/Bas eManager.php:getPageLists Cuando una página es publicada, este método es llamado y puebla un array de nombres de listas (strings) al cual la página “pertenece”. En vendor/wfcms/cms-basebundle/Wf/Bundle/CmsBaseBundle/PageRenderer/ListingP ageRenderer.php se encuentra un ejemplo donde esto se utiliza. $qb = $articleRepository->getBaseQB(); $qb->byList($listName); Una limitación importante relacionada a mostrar resultados es que la lista Redis es usada sólo cuando los resultados son paginados, no se puede llamar a $qb>execute() para conseguir los resultados, se debe poner la QB en un paginador con $qb->byList($listName)

32

Manual técnico

5. Módulos de desarrollo 5.1. Categorías Agregar settings de categoría En app/config/parameters/project.yml: wf_cms_admin.form.type.category.settings.class: ___PROJECT___\Bundle\CmsAdminBundle\Form\Type\C ategorySettingsFormType

En src/___PROJECT___/Bundle/CmsAdminBundle/Form/Ty pe/CategorySettingsFormType.php: