Comenzando

Elemental CMS se publica bajo licencia MPL-2.0 y se puede instalar fácilmente ejecutando el siguiente comando:

        
            pip install elemental-cms

Antes de Empezar #

Necesitamos un servidor MongoDB funcionando para poder explorar la herramienta y todos los ejemplos disponibles. Podemos usar una instalación independiente, o siempre podemos crear una cuenta en MongoDB Atlas. El nivel gratuito será más que suficiente para seguir esta guía.

Como la herramienta está escrita en Python, antes de comenzar a construir nuestra aplicación crearemos un "proyecto" Python:

        
            mkdir getting-started && \
            cd getting-started

Siempre se recomienda trabajar con entornos virtuales para poder aislar problemas y evitar instalar paquetes no deseados globalmente.

        
            python -m venv .venv && \
            source .venv/bin/activate

Ahora que tenemos nuestro entorno virtual activado, estamos listos para instalar el CLI de elemental-cms exclusivamente en nuestro nuevo "proyecto" aislado. Esto también instalará todas las dependencias.

Interfaz de Línea de Comandos (CLI) #

Ahora que la herramienta está instalada, podemos usarla escribiendo:

        
            elemental-cms

Esto mostrará la ayuda de la herramienta que se verá algo así:

        
            Usage: elemental-cms [OPTIONS] COMMAND [ARGS]...

              Elemental CMS management CLI

            Options:
              --help  Show this message and exit.

            Commands:
              global-deps  Global dependencies management
              init         Initialize Elemental CMS workspace
              media        Media content management
              pages        Pages management
              snippets     Snippets management
              static       Static resources management
              version      Show version information

Inicializando el Espacio de Trabajo de Elemental CMS #

El CLI incluye un comando "init" que creará una estructura básica en el directorio de trabajo. Pero antes de poder ejecutar el comando init, necesitamos crear un archivo de configuración con el nombre local.cli.json en nuestra carpeta de configuración.

        
            mkdir settings && \
            nano local.cli.json

Contenido mínimo del archivo local.cli.json para ejecutar el comando init:

        
            {
              "cmsCoreContext": {
                "DEBUG": true,
                "ENV": "development",
                "SECRET_KEY": "tu-clave-secreta-aqui",
                "SITE_NAME": "Elemental CMS Comenzando",
                "COMPANY": "Tu Empresa",
                "CANONICAL_URL": "https://www.tu-sitio.com",
                "LANGUAGES": [
                  "en",
                  "es"
                ],
                "DEFAULT_LANGUAGE": "en",
                "LANGUAGE_MODE": "multi",
                "STATIC_FOLDER": "static",
                "MEDIA_FOLDER": "media",
                "STATIC_URL": "https://storage.googleapis.com/tu-bucket-estatico",
                "MEDIA_URL": "https://storage.googleapis.com/tu-bucket-media",
                "STATIC_BUCKET": "tu-bucket-estatico",
                "MEDIA_BUCKET": "tu-bucket-media",
                "GOOGLE_SERVICE_ACCOUNT_INFO": {
                  "type": "service_account",
                  "project_id": "tu-id-proyecto"
                },
                "GLOBAL_DEPS_FOLDER": "workspace/global_deps",
                "PAGES_FOLDER": "workspace/pages",
                "SNIPPETS_FOLDER": "workspace/snippets",
                "USER_IDENTITY_SESSION_KEY": "userIdentity",
                "SESSION_STORAGE_ENABLED": true,
                "SESSION_TIMEOUT_IN_MINUTES": 360
              },
              "cmsDbContext": {
                "id": "elemental-cms-db-friendly-name",
                "connectionString": "mongodb://mi-usuario:mi-contraseña@mongodb-hostname:27017/admin?directConnection=true",
                "databaseName": "elemental_comenzando"
              }
            }

Las propiedades de carpeta y base de datos son vitales para que el comando init funcione. Si alguna de estas propiedades falta o está mal configurada, el comando no funcionará.

        
            elemental-cms init -c settings/local.cli.json

Si todo va bien, debemos tener la siguiente estructura de carpetas:

        
            └── getting-started
                ├── .elemental
                ├── media
                ├── settings
                │   └── local.cli.json
                ├── static
                ├── templates
                │   └── base.html
                ├── translations
                └── workspace
                    ├── global_deps
                    ├── pages
                    └── snippets

Además, nuestro servidor MongoDB tendrá nuestra base de datos CMS:

        
            > show dbs
            admin                      0.000GB
            config                     0.000GB
            elemental_comenzando       0.000GB
            local                      0.000GB

Creando Nuestra Primera Página #

Para crear una nueva página, comenzamos ejecutando el comando CLI de páginas así:

        
            elemental-cms pages create -p home en

Esto creará el archivo de contenido de la página y el archivo de especificación de la página bajo el directorio workspace/pages/en.

Archivo de Especificación

El archivo de especificación tiene los metadatos de la página que luego se pueden subir a la base de datos para hacer la página disponible en el CMS.

La estructura del archivo de especificación se puede ver a continuación:

        
            {
                "_id": {
                    "$oid": "625b675f0c82e4f4d2107e8d"
                },
                "name": "home",
                "language": "en",
                "title": "home page",
                "description": "",
                "isHome": false,
                "cssDeps": [],
                "jsDeps": [],
                "createdAt": {
                    "$date": 1650157407821
                },
                "lastModifiedAt": {
                    "$date": 1650157407821
                }
            }
Como esta es nuestra primera y única página, deberíamos establecer la propiedad isHome en true.

Archivo de Contenido

El archivo de contenido tendrá el HTML de la página. Después de la ejecución del comando create, tendrá un HTML simple como el siguiente:

        
            <div></div>

Subiendo Nuestra Nueva Página #

Para subir una página, debemos usar el comando pages push que enviará los metadatos y contenido a la base de datos y creará una versión "borrador" de la página.

        
            elemental-cms pages push -p home en

Publicando Nuestra Página #

Hasta ahora, la nueva página se almacena en el repositorio "borradores". Para ser accesible a través de la aplicación web, debemos publicar la página ejecutando el siguiente comando:

        
            elemental-cms pages publish -p home en

Aplicación Flask #

Hasta ahora, hemos creado una página multiidioma y la hemos publicado exitosamente, pero nos falta nuestro punto de entrada de la aplicación. Como este framework está basado en Flask, debemos crear un punto de entrada simple como lo haríamos para cualquier aplicación Flask.

Entonces crearemos el archivo de script main.py, y luego agregaremos el script mínimo requerido para lanzar una aplicación web simple.

        
            import json
            import os

            from elementalcms import Elemental, ElementalContext
            from elementalcms.core import FlaskContext, MongoDbContext
            from flask import Flask

            www = Flask(__name__, template_folder='templates', static_folder='static')

            CONFIG_FILEPATH = os.environ.get('CONFIG_FILEPATH', 'settings/local.www.json')

            with open(CONFIG_FILEPATH) as config_file:
                settings = json.load(config_file)
                cms_core_context = FlaskContext(settings['cmsCoreContext'])
                cms_db_context = MongoDbContext(settings['cmsDbContext'])
                elemental_context = ElementalContext(cms_core_context, cms_db_context)

            Elemental(www, elemental_context)

            if __name__ == '__main__':
                www.run(host='0.0.0.0', port=8000)

Ejecutando la Aplicación

Para ejecutar la aplicación, usamos python como lo haríamos con cualquier otra aplicación:

        
            python main.py

Configuración CLI y WWW

Si ejecutamos la aplicación ahora mismo, obtendremos un error porque el archivo settings/local.www.json no existe. Podemos crear este archivo copiando la versión local.cli.json.

        
            cp settings/local.cli.json settings/local.www.json

Luego editamos el archivo local.www.json para que su contenido se vea así:

        
            {
              "cmsCoreContext": {
                "DEBUG": true,
                "ENV": "development",
                "SECRET_KEY": "tu-clave-secreta-aqui",
                "SITE_NAME": "Elemental CMS Comenzando",
                "COMPANY": "Tu Empresa",
                "CANONICAL_URL": "https://www.tu-sitio.com",
                "LANGUAGES": [
                  "en",
                  "es"
                ],
                "DEFAULT_LANGUAGE": "en",
                "LANGUAGE_MODE": "multi",
                "STATIC_FOLDER": "static",
                "MEDIA_FOLDER": "media",
                "STATIC_URL": "/static",
                "MEDIA_URL": "/media",
                "GLOBAL_DEPS_FOLDER": "workspace/global_deps",
                "PAGES_FOLDER": "workspace/pages",
                "SNIPPETS_FOLDER": "workspace/snippets",
                "USER_IDENTITY_SESSION_KEY": "userIdentity",
                "SESSION_STORAGE_ENABLED": true,
                "SESSION_TIMEOUT_IN_MINUTES": 360,
                "DESIGN_MODE_ENABLED": true
              },
              "cmsDbContext": {
                "id": "elemental-cms-db-friendly-name",
                "connectionString": "mongodb://mi-usuario:mi-contraseña@mongodb-hostname:27017/admin?directConnection=true",
                "databaseName": "elemental_comenzando"
              }
            }

Como podemos ver, las principales diferencias están en las siguientes propiedades de cmsCoreContext:

Propiedad

local.www.json

local.cli.json

STATIC_URL

/static

https://storage.googleapis.com/tu-bucket-estatico

MEDIA_URL

/media

https://storage.googleapis.com/tu-bucket-media

STATIC_BUCKET

NO REQUERIDO NI USADO

tu-bucket-estatico

MEDIA_BUCKET

NO REQUERIDO NI USADO

tu-bucket-media

GOOGLE_SERVICE_ACCOUNT_INFO

NO REQUERIDO NI USADO

Cuenta de servicio de Google Cloud con acceso otorgado sobre GCS

DESIGN_MODE_ENABLED

true (opcional)

NO USADO
El archivo local.cli.json es usado por el CLI para poder publicar archivos de medios y estáticos a GCS.
El archivo local.www.json se usa en nuestro entorno de desarrollo local. Usa URLs /media y /static para servir archivos locales mientras estamos en modo desarrollo. En modo desarrollo no usaremos GCS, y por eso el archivo de debug puede faltar configuraciones relacionadas como STATIC_BUCKET, MEDIA_BUCKET y GOOGLE_SERVICE_ACCOUNT_INFO. También podemos activar el modo de diseño agregando la propiedad DESIGN_MODE_ENABLED y estableciéndola en true.
Content