Batflat es un sistema de gestión de contenidos simple, ligero y rápido polaco. Fue publicado por primera vez en mayo de 2016. La versión gratuita está compartida bajo [license](/license) que exige deja información sobre los autores y enlaces de referencia. Batflat funciona genial para la creación de sitios pequeños tales como presentaciones de negocios, portfolios, blogs o páginas de inicio. Con esta documentaciń aprenderás cómo instalar, configurar y crear tus propios módulos y temas.
La documentación está dividida en varias secciones. La primera es para instrucciones generales, la segunda para diseñadores web, y las dos últimas para desarrolladores web.
Prerrequisitos
--------------
Los prerrequisitos de sistema para Batflat son modestos ya que todos los modernos servidores pueden proporcionarlos.
La configuración de PHP debe tener las extensiones siguientes :
+ dom
+ gd
+ mbstring
+ pdo
+ zip
+ cURL
Instalación
------------
En primer lugar, descargar la última versión de [Batflat](http://feed.sruu.pl/batflat/download/latest).
Extraer todos los ficheros del paquete comprimido y colocarlo en el directorio local o del servidor remoto deseado. En el caso de un servidor remoto, conectar vía cliente (S)FTP, como el programa gratuito de [FileZilla](https://filezilla-project.org). Habitualmente los ficheros suelen ser subidos a carpetas llamadas `www`, `htdocs` o `public_html`.
**¡AVISO!** Asegúrese de que el fichero `.htaccess` está también en el servidor. Sin él el CMS no funcionará.
Algunos servidores pueden necesitar de permisos adicionales como `chmod 777` para los siguiente directorios y ficheros:
+ tmp/
+ uploads/
+ admin/tmp/
+ inc/data/
+ inc/data/database.sdb
Abra su navegador y localice la dirección donde los ficheros de Batflat están alojados. Debería ver una plantilla por defecto con contenido de ejemplo.
Vaya al panel de administración añadiendo `/admin/` al final de la URL. **El usuario y la contraseña iniciales son *"admin"*.** Debería cambiarlos justo despues que haya accedido por razones de seguridad. También recomendamos renombrar el directorio del panel de administración. *(necesitará cambiar el valor de la constante en el fichero de definiciones)*.
Configuración
-------------
CMS puede configurarse modificando los parámetros del panel de administración o mediante el fichero de definiciones. Aunque, no recomendamos cambiar la configuración del fichero si no es una persona con experiencia en ello.
### Panel de Administración
Para cambiar la configuración básica en el panel de administrador, seleccione la pestaña `Párametros`. Puede indicar un nombre de página, una descripción o palabras clave en las metaetiquetas, the meta tags, así como en cualquier parte de la plantilla por defecto, como en su cabecera. Puede cambiar la página de inicio, el idioma por defecto, *(indistintamente para el sitio web como para el panel)*, definir el contenido del pié de página, y elegir el editor *(HTML o WYSIWYG)* que estará disponible al editar subpáginas y artículos del blog.
Cambiará la configuración de los restantes módulos en las pestañas correspondientes con sus nombres.
### Fichero de definiciones
Más avanzadas cosas pueden cambiarse en el fichero `inc/core/defines.php`, el cual contiene definiciones de variables constantes.
+ `ADMIN` — el nombre del directorio que contiene el panel de administración
+ `THEMES` — ruta al directorio que contiene los temas
+ `MODULES` — ruta al directorio que contiene los módulos
+ `UPLOADS` — ruta al directorio que contiene los ficheros subidos
+ `FILE_LOCK` — bloque la posibilidad de modificar ficheros mediante el panel de administración
+ `BASIC_MODULES` — listado de los módulos básicos que no pueden eliminarse
+ `HTML_BEAUTY` — formato HTML embellecido tras parseo del código
+ `DEV_MODE` — modo desarrollador, donde los errores PHP y los avisos son mostrados
Actualizar
----------
Si desea estar al día con las últimas novedades, corrección de errores e incidencias de seguridad, deberá revisar regularmente las actualizaciones de Batflat. Puede hacerlo en `Parámetros -> Actualizaciones`. El sistema comprobará si hay una nueva versión y automáticamente descargará un nuevo paquete desde nuestro servidor que actualice los ficheros principales y los módulos.
En caso de complicaciones puede usar el modo manual. Para hacerlo así, descargue la última versión de Batflat, súbala al directorio principal de la aplicación, y, entonces, añada el parámetro `&manual` al final del marcador URL de actualización. El CMS debería detectar un paquete zipeado y al hacer click sobre el botón de actualización, el proceso de extracción y sobreescritura de ficheros se ejecutará.
Antes de cada actualización, Batflat crea una copia de seguridad. La encontrará en el directorio de scripts, en la carpeta de `backup/`. Si la actualización ha fallado, puede restaurarla en cualquier momento.
Temas
======
Estructura
----------
La estructura de los temas en Batflat es muy simple. Tan sólo cree una nueva carpeta en el directorio `themes/` con los ficheros siguientes:
+ `index.html` — plantilla por defecto para subpáginas
+ `manifest.json` — información del tema
+ `preview.png` — pantallazo que muestre el tema *(opcional)*
Cada subpágina puede usar otra plantilla, por lo que, además del mencionado fichero, puede también crear otror, p. ej. `xyz.html`. La selección de plantillas está disponible en el panel de administración mientras crea una página. No hay reglas sobre ficheros CSS y JS. Total libertad.
En la carpeta del tema puede también crear sus propias vistas del módulo. Para hacer ésto debe crear un directorio `modules/nombre_modulo` y ficheros `*.html` con los nombres correspondientes a los nombres de las vista originales. Por ejemplo, la vista del formulario de contacto debe estar contenida en la ruta siguiente: `themes/theme_name/modules/contact/form.html`. Batflat automáticamente detecta una nueva vista y la usa en lugar de la vista por defecto del módulo.
Etiquetas de Plantillas (Template tags)
---------------------------------------
CMS usa un sistema de plantillas sencillo que incluye las siguientes etiquetas:
### Variables
```php
{$foo} // simple variable
{$foo|e} // HTML escape for variable
{$foo|cut:10} // content of the variable cut to 10 characters
{$foo.bar} // array
```
El acceso a los elementos del array se hace por el carácter '.' (punto).
### Condiciones
```php
{if: $foo > 5}
lorem
{elseif: $foo == 5}
ipsum
{else}
dolor
{/if}
```
### Bucles (loop)
```html
<ul>
{loop: $foo}
<li>{$key}, {$value}, {$counter}</li>
{/loop}
{loop: $foo as $bar}
<li>{$key}, {$bar}, {$counter}</li>
{/loop}
{loop: $foo as $bar => $baz}
<li>{$bar}, {$baz}, {$counter}</li>
{/loop}
</ul>
```
La etiqueta loop tiene 3 niveles de expansión. El primero is una variable array que el sistema de plantillas interrumpirá en tres variables llamadas `$key`,` $value` y `$counter`, las cuales contienen sucesivas iteraciones inicializadas desde cero. El segundo paso permite indicar el el nombre de la variable que contiene el valor, y el tercero es también el nombre de la variable índice.
### Incluir ficheros de plantilla
```html
<html>
<body>
{template: header.html}
<main>
<p>Lorem ipsum dolor sit amet.</p>
</main>
{template: footer.html}
</body>
</html>
```
### Código PHP
```php
Today`s date: {?= date('Y-m-d') ?}
```
Si deja el carácter `=`, el código sólo se ejecutará y no mostrará nada. Esto permite, por ejemplo, definir nuevas variables dentro de la plantilla:
```php
{? $foo = 5 ?}
```
### Deshabilitar intérprete (parseo)
```
{noparse}Use the {$ contact.form} tag to display contact form.{/noparse}
```
Cualquier etiqueta dentro de la expresión *noparse* se mantendrá sin variaciones.
### Comentarios
```
{* this is a comment *}
```
Los Comentarios no serán visibles en el código fuente tras compliarse la plantilla.
### Idiomas
```
{lang: pl_polski}
Witaj świecie!
{/lang}
{lang: en_english}
Hello world!
{/lang}
{lang: es_spanish}
¡Hola, mundo!
{/lang}
```
Si desea personalizar los elementos de la plantilla en un idioma particular, utilice las etiquetas susodichas.
Sistema de variables
--------------------
Batflat, como sus módulos, proporciona muchas variables *(habitualmente arrays)* que sirven para mostrar cada elemento de la página. He aquí algunos de los más importantes:
+ `{$settings.pole}` — un elemento array conteniendo el valor del parámetro dado por Batflat
+ `{$settings.moduł.pole}` — un elemento array conteniendo el valor del parámetro dado por el módulo
+ `{$bat.path}` — almacena la ruta donde se aloja el sistema
+ `{$bat.lang}` — muestra el idioma actual utilizado
+ `{$bat.notify}` — la última modificación
+ `{$bat.notify.text}` - texto de notificación
+ `{$bat.notify.type}` - tipo de mensaje correspondiente a las Bootstrap *(danger, success)*
+ `{$bat.header}` — metaetiquetas adicionales, scripts JS y hojas de estilo CSS cargadas por los módulos
+ `{$bat.footer}` — scripts JS adicionales cargados por los módulos
+ `{$bat.theme}` — muestra la ruta al tema activo con el servidor
+ `{$bat.powered}` — muestra *Powered by Batflat* con un enlace al sitio oficial
+ `{$navigation.xyz}` — muestra una lista de `<li>` elementos de navegación
+ `{$page.title}` — muestra el nombre de la subpágina
+ `{$page.content}` — muestra el contenido de la subpágina
Cada módulo, como los temas, deben estar en carpetas separadas creadas en el directorio `inc/modules/`. Por favor, observe qeu el directorio no contiene ni mayúsculas ni caracteres especiales, tales como espacios.
Cuando cree un módulo, reflexione sobre qué el tipo de módulo desea usar. ¿Será configurable en el panel de administración? ¿o sólo funcionará en el lado de presentación? Debido a esta división, en Batflat distinguimos tres archivos principales del módulo:
+ `Info.php` — contiene información sobre el módulo, tal como nombre, descripción, autor o icon
+ `Admin.php` — el contenido de este fichero será accessible mediante el panel de administración
+ `Site.php` — el contenido de este fichero estará disponible a los visitantes del sitio
El cuarto y opcional fichero es el `ReadMe.md` que debería contener información adicional para futuros usuarios en formato [Markdown](https://es.wikipedia.org/wiki/Markdown), p.ej. cómo usar el módulo.
Si planea escribir un módulo que use HTML, sería bueno que se asegure que el código PHP está separado del lenguaje HTML en sí mismo. Para ello, necesita crear un directorio `views` dentro de la carpeta del módulo. Incluya cualquier fichero de vistas en él.
El problema multidioma del módulo es similar. Tan sólo cree ficheros de idioma con la extensión `ini` dentro del directorio `lang`.
La estructura del módulo debiera verse algo parecido a ésto:
```
ejemplo/
|-- lang/
| |-- admin/
| | |-- en_english.ini
| | |-- pl_polski.ini
| | |-- es_spanish.ini
| |-- en_english.ini
| |-- pl_polski.ini
| |-- es_spanish.ini
|-- views/
| |-- admin/
| | |-- bar.html
| |-- foo.html
|-- Admin.php
|-- Info.php
|-- Site.php
+-- ReadMe.md
```
Crear un módulo
-----------------
### Info file
El fichero más importante para cada módulo. Contiene información básica e instrucciones durante la instalación y desinstalación.
```php
<?php
return [
'name' => 'Example',
'description' => 'Lorem ipsum....',
'author' => 'Robin',
'version' => '1.0',
'compatibility' => '1.3.*', // Compatibility with Batflat version
'icon' => 'bolt',
'pages' => ['Example' => 'example'], // Registration as a page (optional)
Una lista de iconos que puede usar en este fichero esta disponible en [fontawesome.io](http://fontawesome.io/icons/). Asegúrese de que no se indica el nombre del icono con el prefijo `fa-`.
Registrar un módulo como una página le permite, libremente, usar el enrutamiento y su selección como página de inicio.
### Fichero Admin
El contenido de este fichero se lanzará en el panel de administración.
```php
<?php
namespace Inc\Modules\Ejemplo;
use Inc\Core\AdminModule;
class Admin extends AdminModule
{
public function init()
{
// Procedures invoked at module initialization
}
public function navigation()
{
return [
'Foo' => 'foo',
'Bar' => 'bar',
];
}
public function getFoo($parm)
{
return "Foo $parm!";
}
public function postBar()
{
return "Bar!";
}
}
```
En el método `navigation`, incluir un array con las subpáginas del módulo. Cada página debería ser asignada a un método *(sin un prefijo)*. Los elementos de este array se mostrarán en el menú del panel de administración.
Los métodos también aceptan argumentos que son pasados vía URL. Por ejemplo, tras introducir la dirección `/ejemplo/foo/abc`, el método `getFoo` devolverá *"Foo abc!"*.
Como puede ver en la siguiente lista, cada método que representa la subpágina del módulo debería tener un prefijo especificando el tipo de solicitud. En muchos casos usará la nomenclatura `getFoo`, y el formulario de envío `postFoo`. Si el método soporta todos los tipos, debería preceder el prefijo `any`*(por ejemplo, `anyFoo`)*. Esto es importante porque páginas sin prefijo no serán manejadas. Los métodos soportados son traducidos por enrutado dinámico como sigue:
+ `getFoo()` — como `/ejemplo/foo` para una petición GET
+ `getFoo($parm)` — como `/ejemplo/foo/abc` para una petición GET
+ `postBar()` — como `ejemplo/bar` para peticiones POST *(formulario de envío)*
+ `anyFoo()` — como `/ejemplo/foo` para cada tipo de petición
### Site file
Este fichero se responsabiliza de la parte vista por los visitantes del sitio. Si el módulo es demasiado largo, una buena práctica es registrarlo como una página y aplicarle un enrutado.
```php
<?php
namespace Inc\Modules\Ejemplo;
use Inc\Core\SiteModule
class Site extends SiteModule
{
public function init()
{
$this->_foo();
}
public function routes()
{
$this->route('ejemplo', '_mySite');
}
private function _mySite()
{
$page = [
'title' => 'Título ejemplo..',
'desc' => 'Descripción del sitio',
'content' => 'Lorem ipsum dolor...'
];
$this->setTemplate('index.html');
$this->tpl->set('page', $page);
}
private function _foo()
{
$this->tpl->set('bar', '¿Por qué tan serio?');
}
}
```
En el anterior ejemplo, una nueva variable de plantilla `bar` se ha creado la cual, por llamada al método `_foo()` en el módulo initializer, puede usarse en los ficherso del tema como `{$bar}`. En suma, el método `routes()` ha creado una subrutina `/ejemplo` que apunta a la llamada del método `_mySite()`. Si va a `http://example.com/ejemplo`, llamará al método `_mySite()`.
### Fichero de Idiomas
El módulo puede contener variables de idiomas que pueden usarse en clases y vistas. Los ficheros de idiomas tienen una extension `.ini` y están localizados en el directorio` lang` del módulo.
Por ejemplo, si deseas añadir un fichero de idioma conteniendo expresiones en Español para la parte administrativa del módulo `Ejemplo`, deberá crear un fichero en la ruta `inc/modules/example/lang/admin /es_spanish.ini`.
El contenido debería asemejarse al siguiente listado:
```
full_name = "Nombre y apellidos"
email = "Correo"
subject = "Asunto"
message = "Mensaje"
send = "Enviar"
send_success = "Correo correctamente enviado. Le responderemos pronto."
send_failure = "Imposible enviar mensaje. Quizál la función mail() está deshabilitada en el servidor."
wrong_email = "La dirección de correo enviada es incorrecta."
empty_inputs = "Rellene todos los campos necesarios para enviar un mensaje."
antiflood = "Debe esperar un rato antes de volver a enviar otro mensaje."
```
Utilice la construcción `$this->lang('subject')` en la clase del módulo y `{$lang.example.subject}` en la vista. Para una clase, podemos dejar el segundo parámetro del método `lang`, el cual será el nombre del módulo.
Enrutado
--------
Enrutado es el proceso de tramitar una petición de dirección recibida y decidir que debería ejecutarse o mostrarse. Se supone que llama al método/función adecuado en base a la URL de la página. Debe usar el enrutado dentro del método público `routes()`.
```php
void route(string $pattern, mixed $callback)
```
El primer parámetro del método `route` es una expresión regular. Algunas de tales expresiones ya se han definido:
+ `:any` — cualquier cadena de carácteres (string)
+ `:int` — números enteros
+ `:str` — una string que es una etiqueta del tipo slug
El segundo parámetro es un nombre de método o una función anónima que pasa un número de argumentos definidos en una expresión regular.
Los módulos muestran fachadas especiales que facilitan el acceso a los métodos dentro del núcleo (core). Esto permite acortar las llamadas como `$this->core->foo->bar`.
### db
```php
void db([string $table])
```
Permite operar en una base de datos. Los detalles se describen en la sección del núcleo (core).
#### Argumentos
+ `table` — Database table name *(opcional)*
#### Ejemplo
```php
$this->db('table')->where('age', 20)->delete();
```
### draw
```php
string draw(string $file [, array $variables])
```
Devuelve el código compilado de la vista que, previamente, ha empleado las etiquetas del sistema de plantillas. También permite definir variables por sustitución con el método `set()`.
#### Argumentos
+ `file` — fichero con la vista dentro del módulo o la ruta a un fichero fuera de él.
+ `variables` — un array de definición de variables que pueden usarse como etiquetas *(opcional)*
Este es el kernel/motor de Batflat, la parte más importante que se responsabiliza de todas sus tareas básicas. El core contiene muchas definiciones de constantes, funciones, y métodos que se pueden usar al escribir módulos.
Constantes
----------
Todas las definiciones de constantes se describen en la primera parte de esta documentación. Para usarlas en un fichero PHP tan sólo llame a sus nombres. Las constantes son particularmente útiles al crear URLs y rutas de ficheros.
#### Ejemplo
```php
echo MODULES.'/contact/view/form.html';
```
Funciones
---------
Batflat tiene varias funciones de ayuda incorporada (built-in helper functions) que facilitan la creación de módulos.
### domain
```php
string domain([bool $with_protocol = true])
```
Devuelve el nombre de dominio con o sin http(s).
#### Argumentos
+ `with_protocol` — decide si la dirección será devuelta con o sin protocolo
#### Valor devuelto
String con el nombre de dominio.
#### Ejemplo
```php
echo domain(false);
// Result: example.com
```
### checkEmptyFields
```php
bool checkEmptyFields(array $keys, array $array)
```
Comprueba si el array contiene elementos vacíos. Es útil al valir formularios.
#### Argumentos
+ `keys` — lista de elementos del array que la función ha revisado
+ `array` — source array
#### Valor devuelto
Devuelve `TRUE` si, al menos, uno de los elementos está vacío. `FALSE` cuando todos los elementos están completos.
Traduce texto en caracteres no alfanuméricos, guiones y espacios, y elimina caracteres especiales. Se usar para crear barras en URLs y nombres de variables en el sistema de plantillas.
#### Argumentos
+ `text` — texto a convertir
#### Valor devuelto
Devuelve el texto en formato amigable.
#### Ejemplo
```php
echo createSlug('To be, or not to be, that is the question!');
+ `type` — tipo de notificación: *success* o *failure*
+ `text` — contenido de la notificación
+ `args` — argumentos adicionales *(opcional)*
#### Ejemplo
```php
$foo = 'Bar';
$this->core->setNotify('success', 'This is %s!', $foo);
// Result: "This is Bar!"
```
Base de datos
-------------
La base de datos que usa Batflat es SQLite version 3. Para su uso el CMS utiliza una simple clase que facilita la creación de consultas. No es necesario saber de SQL para ser capaz de operar con ello.
Además, recomendamos la herramienta [phpLiteAdmin](https://github.com/sruupl/batflat-pla) para la gestión de bases de datos. Es un script en un único fichero PHP similar a *phpMyAdmin*, donde se pueden administrar tablas de Batflat. Le permitirá familiarizarse con la estructura de las tablas existentes.
El fichero de la base de datos está ubicado en `inc/data/database.sdb`.
No todas las consulta se pueden crear usando los métodos anteriores *(p.ej. crear o eliminar una tabla)*, por lo que se puede también escribir consultas utilizando [PDO](http://php.net/manual/es/book.pdo.php):
Operar con el sistema de plantillas es fácil y se basa fundamentalmente en dos métodos. Uno permite asignar variables, mientras que el otro devuelve el código compilado. En situaciones exceptionales, los otros dos métodos son útiles.
### set
```php
void set(string $name, mixed $value)
```
Asigna un valor a una variable que puede usarse en las vistas.
#### Argumentos
+ `name` — nombre de la variable
+ `value` — valor de la variable
#### Ejemplo
```php
$foo = ['bar', 'baz', 'qux'];
$this->tpl->set('foo', $foo);
```
### draw
```php
string draw(string $file)
```
Devuelve el código compilado de la vista que, previamente, ha empleado las etiquetas del sistema de plantillas.
Todos los ficheros de idiomas están ubicados en los directorios `lang` dentro del módulo y en la ruta `inc/lang`.
En esta última ruta hay las correspondientes carpetas para los idiomas con el siguiente formato: `en_english`. La primera parte es la abreviatura del idioma y la segunda es el nombre completo en inglés.
Dentro del directorio está el fichero `general.ini`, que contiene variables generales del idioma para el sistema.
Tras crear una nueva carpeta de idioma, Batflat automáticamente detecta el idioma añadido y permite su selección en el panel de administración. Tenga en cuenta que el proceso de creación de un nuevo idioma deberá repetirse para cada módulo.
