Estructura de Proyectos Autobase

Este documento describe la estructura de archivos y carpetas que debe tener un proyecto de usuario al desarrollar aplicaciones con Autobase.

Estructura General

Un proyecto Autobase tiene una estructura flexible que permite organizar los archivos de diferentes maneras según las necesidades del proyecto:

MiAplicacion/
├── app.yaml               # Configuración de la aplicación (REQUERIDO)
├── app.lua                # Eventos a nivel de aplicación (opcional)
├── templates.html         # Templates HTML globales (opcional)
├── index.yaml             # Página de inicio (REQUERIDO)
├── index.lua              # Eventos de la página Index (opcional)
├── customer-list.yaml      # Página de lista de clientes
├── customer-list.lua       # Eventos de customer-list
├── customer-edit/          # Carpeta para página de edición
│   ├── customer-edit.yaml  # Definición de la página
│   ├── events.lua         # Eventos de la página
│   └── templates.html     # Templates específicos de la página
├── dashboard.yaml         # Otra página en la raíz
├── shared/                # Carpeta para recursos compartidos (opcional)
│   ├── validators.lua     # Funciones Lua compartidas
│   ├── templates.html     # Templates compartidos
│   └── utils.lua          # Utilidades compartidas
└── reports/               # Carpeta para páginas de reportes
    ├── sales-report.yaml
    ├── sales-report.lua
    └── inventory-report.yaml

Archivos Principales

1. app.yaml (REQUERIDO)

El archivo app.yaml es el único archivo obligatorio y define la configuración general de la aplicación.

Ubicación: Siempre en la raíz del proyecto.

Contenido típico:

yaml

# Propiedades de la aplicación
props:
  title: Mi Aplicación
  description: Sistema de gestión
  version: 1.0.0

# Menú principal
mainMenuItems:
  - name: clientes
    icon: users
    target: customer-list
  - name: productos
    icon: package
    target: product-list
  - name: reportes
    icon: chart-bar
    menuItems:
      - name: ventas
        target: sales-report
      - name: inventario
        target: inventory-report

# Menú de usuario
userMenuItems:
  - name: miPerfil
    icon: user
    target: profile
  - name: configuracion
    icon: settings
    target: settings

2. Páginas (.yaml)

Regla importante: Todos los archivos .yaml son páginas, EXCEPTO app.yaml.

Ubicación: Pueden estar en:

La raíz del proyecto: customer-list.yaml
Dentro de carpetas: customer-edit/customer-edit.yaml
En subcarpetas: reports/sales/monthly.yaml

Nombre de la página: Se deriva del nombre del archivo (sin extensión).

Estructura de una página:

yaml

title: Lista de Clientes
onLoad: "@INCLUDE(events.lua, customerListOnLoad)"

components:
  - type: BUTTON
    name: addCustomer
    text: Agregar Cliente
    icon: bi-plus-circle
    cssClass: "btn btn-primary"
    target: customer-edit
    visible: var:buttonVisible

  - type: TABLE
    name: customersTable
    pageSize: 20
    children:
      - type: COLUMN
        field: name
        title: Nombre
      - type: COLUMN
        field: email
        title: Email

3. Archivos Lua (.lua)

Contienen funciones de eventos y lógica de negocio.

Ubicación: Flexible, pueden estar:

En la raíz junto a la página: index.lua
En carpetas de página: customer-edit/events.lua
En carpetas compartidas: shared/validators.lua

Estructura:

lua

-- events.lua

function customerListOnLoad()
  customersTable = sql([[
        SELECT id, name, email
        FROM customers
        ORDER BY name
    ]])
end

function addCustomerOnClick()
  release_var("customer*")
  customerId = nil
end

function editOnClick()
  customerId = int(@FIELD(id))
end

Uso en YAML con @INCLUDE:

yaml

onLoad: "@INCLUDE(events.lua, customerListOnLoad)"
onClick: "@INCLUDE(events.lua, addCustomerOnClick)"

4. Archivos HTML (.html)

Contienen templates HTML reutilizables.

Ubicación: Flexible, pueden estar:

En la raíz: templates.html
En carpetas de página: customer-list/templates.html
En carpetas compartidas: shared/cards.html

Estructura:

html

<!-- templates.html -->

<template id="customerCard">
  <div class="card">
    <div class="card-body">
      <h5>@VAR(customerName)</h5>
      <p>@VAR(customerEmail)</p>
    </div>
  </div>
</template>

<template id="productRow">
  <div class="product-item">
    <span>@VAR(productName)</span>
    <span>$@VAR(productPrice)</span>
  </div>
</template>

Uso en YAML con @INCLUDE:

yaml

- type: DISPLAY
  template: "@INCLUDE(templates.html, customerCard)"

La Página index

La página llamada index es especial y funciona como punto de entrada de la aplicación.

Archivo: index.yaml (puede estar en la raíz o en carpeta index/)

Usos típicos:

Pantalla de login
Landing page pública
Redirección según estado de autenticación

Ejemplo:

yaml

title: Bienvenido
onLoad: "@INCLUDE(index.lua, indexOnLoad)"

components:
  - type: FORM
    name: loginForm
    children:
      - type: TEXT_FIELD
        name: loginUsername
        label: Usuario
      - type: TEXT_FIELD
        name: loginPassword
        label: Contraseña
      - type: BUTTON
        name: loginButton
        text: Iniciar Sesión
        onClick: "@INCLUDE(index.lua, loginOnClick)"
        target: dashboard

Patrones de Organización

Patrón 1: Todo en la raíz

Ideal para aplicaciones pequeñas.

MiApp/
├── app.yaml
├── index.yaml
├── index.lua
├── customer-list.yaml
├── customer-list.lua
├── customer-edit.yaml
├── customer-edit.lua
└── templates.html

Patrón 2: Páginas en carpetas

Mejor organización para proyectos medianos.

MiApp/
├── app.yaml
├── index/
│   ├── index.yaml
│   └── events.lua
├── customers/
│   ├── customer-list.yaml
│   ├── customer-edit.yaml
│   └── events.lua
└── products/
  ├── product-list.yaml
  ├── product-edit.yaml
  └── events.lua

Patrón 3: Con recursos compartidos

Para aplicaciones grandes con código reutilizable.

MiApp/
├── app.yaml
├── app.lua
├── shared/
│   ├── validators.lua
│   ├── templates.html
│   ├── utils.lua
│   └── cards.html
├── customers/
│   ├── customer-list.yaml
│   ├── customer-edit.yaml
│   └── events.lua
├── products/
│   ├── product-list.yaml
│   └── events.lua
└── reports/
  ├── sales.yaml
  └── inventory.yaml

Función @INCLUDE

La función @INCLUDE permite referenciar archivos externos desde cualquier archivo YAML.

Sintaxis:

@INCLUDE(rutaArchivo, nombreElemento)

Características:

Cualquier .yaml puede referenciar CUALQUIER archivo .lua o .html
Las rutas son relativas al archivo .yaml que las usa
No hay restricciones sobre la organización de archivos

Ejemplos de uso:

yaml

# Desde la misma carpeta o raíz
onLoad: "@INCLUDE(events.lua, pageOnLoad)"

# Desde carpeta específica
onClick: "@INCLUDE(customer-edit/events.lua, saveOnClick)"

# Desde carpeta compartida
onLoad: "@INCLUDE(shared/validators.lua, validateEmail)"

# Templates
template: "@INCLUDE(templates.html, customerCard)"
template: "@INCLUDE(shared/cards.html, productCard)"

Tipos de Archivos Soportados

Extensión	Propósito	Obligatorio
`.yaml`	Definición de páginas y configuración de app	Sí (app.yaml e index.yaml)
`.lua`	Eventos y lógica de negocio	No
`.html`	Templates HTML reutilizables	No

Navegación entre Páginas

La navegación se realiza usando la propiedad target en botones:

yaml

- type: BUTTON
  name: goToCustomers
  text: Ver Clientes
  target: customer-list  # Nombre de la página destino

El nombre de la página es el nombre del archivo .yaml (sin extensión).

Ejemplos:

customer-list.yaml → target: customer-list
reports/sales.yaml → target: sales
dashboard/main.yaml → target: main

Pasaje de Datos entre Páginas

Las variables persisten automáticamente entre navegaciones:

Página origen (customer-list):

lua

function editOnClick()
  customerId = int(@FIELD(id))
  -- La variable customerId estará disponible en la página destino
end

Página destino (customer-edit):

lua

function customerEditOnLoad()
  if customerId ~= nil then
    -- Cargar datos del cliente usando customerId
        sql_to_vars([[
      SELECT name AS customerName, email AS customerEmail
            FROM customers
      WHERE id = @customerId
        ]])
    end
end

Mejores Prácticas

1. Organización de Archivos

✅ Recomendado:

Agrupar páginas relacionadas en carpetas
Usar carpeta shared/ para código reutilizable
Mantener nombres descriptivos y consistentes

❌ Evitar:

Mezclar páginas no relacionadas en la misma carpeta
Nombres de archivo genéricos como page-1.yaml

2. Nombres de Páginas

✅ Recomendado:

customer-list, customer-edit, order-dashboard
dashboard, profile, settings
sales-report, inventory-report

❌ Evitar:

page1, page2, list, edit
Form, Table, Screen

3. Organización de Eventos

✅ Recomendado:

Un archivo events.lua por página o módulo
Nombres de función descriptivos: customerListOnLoad, saveOnClick
Agrupar funciones relacionadas

❌ Evitar:

Todas las funciones en un solo archivo gigante
Nombres genéricos: onClick, load, save

4. Templates

✅ Recomendado:

Templates reutilizables en templates.html o shared/templates.html
Templates específicos cerca de su página
Nombres descriptivos de templates

❌ Evitar:

Duplicar templates entre páginas
HTML inline largo en archivos YAML

Ejemplo Completo de Proyecto

MiSistema/
│
├── app.yaml                    # Configuración principal
├── app.lua                     # Eventos globales (opcional)
├── .autobase.env              # Configuración del CLI (no subir a Git)
├── .gitignore                 # Ignorar archivos locales
│
├── index/                      # Página de inicio
│   ├── index.yaml
│   ├── events.lua
│   └── templates.html
│
├── shared/                     # Recursos compartidos
│   ├── validators.lua          # Validaciones comunes
│   ├── templates.html          # Templates comunes
│   └── utils.lua               # Funciones utilitarias
│
├── customers/                  # Módulo de clientes
│   ├── customer-list.yaml
│   ├── customer-edit.yaml
│   ├── events.lua
│   └── templates.html
│
├── products/                   # Módulo de productos
│   ├── product-list.yaml
│   ├── product-edit.yaml
│   └── events.lua
│
├── orders/                     # Módulo de pedidos
│   ├── order-list.yaml
│   ├── order-edit.yaml
│   └── events.lua
│
└── reports/                    # Reportes
    ├── sales/
    │   ├── daily.yaml
    │   └── monthly.yaml
    ├── inventory/
    │   └── stock.yaml
    └── events.lua

Resumen

✅ app.yaml es obligatorio y define la configuración de la aplicación
✅ index.yaml es la página de entrada (login/home)
✅ Todos los .yaml (excepto app.yaml) son páginas
✅ Los archivos .lua contienen eventos y lógica
✅ Los archivos .html contienen templates reutilizables
✅ La organización en carpetas es completamente flexible
✅ @INCLUDE permite referenciar archivos desde cualquier ubicación
✅ El nombre de la página viene del nombre del archivo .yaml
✅ La navegación usa target: nombre-pagina
✅ Las variables persisten automáticamente entre páginas

FORM

Estructura de Proyectos Autobase ​

Estructura General ​

Archivos Principales ​

1. app.yaml (REQUERIDO) ​

2. Páginas (.yaml) ​

3. Archivos Lua (.lua) ​

4. Archivos HTML (.html) ​

La Página index ​

Patrones de Organización ​

Patrón 1: Todo en la raíz ​

Patrón 2: Páginas en carpetas ​

Patrón 3: Con recursos compartidos ​

Función @INCLUDE ​

Tipos de Archivos Soportados ​

Navegación entre Páginas ​

Pasaje de Datos entre Páginas ​

Mejores Prácticas ​

1. Organización de Archivos ​

2. Nombres de Páginas ​

3. Organización de Eventos ​

4. Templates ​

Ejemplo Completo de Proyecto ​

Resumen ​

Estructura de Proyectos Autobase

Estructura General

Archivos Principales

1. app.yaml (REQUERIDO)

2. Páginas (.yaml)

3. Archivos Lua (.lua)

4. Archivos HTML (.html)

La Página index

Patrones de Organización

Patrón 1: Todo en la raíz

Patrón 2: Páginas en carpetas

Patrón 3: Con recursos compartidos

Función @INCLUDE

Tipos de Archivos Soportados

Navegación entre Páginas

Pasaje de Datos entre Páginas

Mejores Prácticas

1. Organización de Archivos

2. Nombres de Páginas

3. Organización de Eventos

4. Templates

Ejemplo Completo de Proyecto

Resumen