Guía Definitiva: Crea tu primer bloque en Moodle 4.5 desde cero (Parte 1)

DESARROLLO MOODLE · PARTE 1

Un estudiante entra en el curso, necesita ayuda y no sabe dónde buscarla. Un correo escondido en un PDF o una página de soporte a tres clics de distancia no resuelve el problema. En este tutorial aprenderás a crear tu primer bloque en Moodle 4.5 desde cero: un pequeño punto de ayuda contextual, visible dentro del curso y preparado para crecer.

No vamos a construir un ejemplo desechable. Crearemos block_soporte_curso siguiendo la estructura oficial de plugins de Moodle, con cadenas de idioma, capacidades, una plantilla Mustache y un proceso de instalación que puedas comprobar paso a paso.

El problema: la ayuda existe, pero llega tarde

Puedes tener contenidos excelentes, actividades bien organizadas y evaluaciones precisas. Aun así, basta con que el alumnado no encuentre dónde preguntar para que la experiencia se deteriore: aumentan los correos, se repiten las mismas incidencias y el equipo docente acaba actuando como primera línea de soporte.

«No encuentro dónde subir la tarea», «el PDF no se abre» o «¿con quién contacto?» no suelen ser problemas pedagógicos. Son problemas de contexto y acceso a la ayuda.

Un bloque personalizado no sustituye una buena arquitectura de información, pero puede actuar como un pequeño salvavidas: coloca el canal de soporte justo en la pantalla donde surge la duda.

Qué vamos a construir

El resultado será un bloque de soporte para cursos Moodle con cuatro elementos:

En Moodle 4.5, con el tema Boost, los bloques del curso se muestran normalmente en el cajón de bloques del lateral derecho. El usuario puede abrirlo o cerrarlo, de modo que el contenido debe ser breve, reconocible y útil; no podemos asumir que permanecerá siempre desplegado.

Qué es realmente un bloque en Moodle

Antes de crear un bloque en Moodle 4.5 conviene entender dónde encaja. Moodle es un sistema modular: el núcleo proporciona las capacidades comunes y los plugins amplían su comportamiento mediante actividades, formatos de curso, métodos de matriculación, informes, temas y bloques, entre otros.

Un bloque es un plugin orientado a mostrar información o funciones complementarias en diferentes páginas. No es la opción adecuada para crear una actividad evaluable —para eso existe el tipo mod—, pero encaja muy bien para accesos rápidos, resúmenes, avisos, indicadores o ayuda contextual.

La documentación oficial de plugins de bloque para Moodle 4.5 define la estructura y los métodos que utilizaremos. Si quieres ampliar primero la visión general, también puedes consultar 10 habilidades clave para desarrollar en Moodle.

Requisitos previos

Para crear un bloque en Moodle 4.5 no necesitas modificar el core. De hecho, no debes hacerlo: desarrolla el componente dentro de /blocks, utiliza Git y no trabajes directamente sobre el servidor de producción.

Paso 1: crear la estructura del bloque

El primer paso para crear un bloque en Moodle 4.5 es respetar su convención de nombres. Todos los plugins de este tipo viven dentro de /blocks. El nombre corto será soporte_curso, por lo que su componente completo —el nombre Frankenstyle que Moodle usa internamente— será block_soporte_curso.

blocks/soporte_curso/
├── block_soporte_curso.php
├── version.php
├── db/
│   └── access.php
├── lang/
│   ├── en/
│   │   └── block_soporte_curso.php
│   └── es/
│       └── block_soporte_curso.php
└── templates/
    └── content.mustache

blocks/soporte_curso/
├── block_soporte_curso.php
├── version.php
├── db/
│   └── access.php
├── lang/
│   ├── en/
│   │   └── block_soporte_curso.php
│   └── es/
│       └── block_soporte_curso.php
└── templates/
    └── content.mustache

Paso 2: declarar el plugin en version.php

version.php es el manifiesto del plugin. Moodle lo utiliza durante la instalación y las actualizaciones para comprobar la identidad del componente, su versión y la versión mínima del core que necesita.

Crea blocks/soporte_curso/version.php:

<?php

defined('MOODLE_INTERNAL') || die();

$plugin->component = 'block_soporte_curso';
$plugin->version   = 2026081100;
$plugin->requires  = 2024100700; // Moodle 4.5.
$plugin->maturity  = MATURITY_STABLE;
$plugin->release   = '1.0.0';

<?php

defined('MOODLE_INTERNAL') || die();

$plugin->component = 'block_soporte_curso';
$plugin->version   = 2026081100;
$plugin->requires  = 2024100700; // Moodle 4.5.
$plugin->maturity  = MATURITY_STABLE;
$plugin->release   = '1.0.0';

La propiedad component debe coincidir con la ubicación blocks/soporte_curso. En requires declaramos la primera versión de Moodle 4.5: de esta forma Moodle impedirá instalar el bloque en un core anterior.

Cómo leer 2026081100

El formato habitual es YYYYMMDDXX: año, mes, día y un contador de dos dígitos. 2026081100 representa la primera versión publicada el 11 de agosto de 2026. Si generas otra revisión ese mismo día, utilizarías 2026081101.

Puedes consultar todas las propiedades disponibles en la referencia oficial de version.php para Moodle 4.5.

Paso 3: añadir las cadenas de idioma

Los textos visibles no deben quedar repartidos por la lógica PHP. Moodle resuelve las cadenas mediante get_string() y el idioma activo de cada usuario. Todo plugin debe proporcionar, como mínimo, el archivo en inglés.

Idioma base: inglés

Crea lang/en/block_soporte_curso.php:

<?php

defined('MOODLE_INTERNAL') || die();

$string['pluginname'] = 'Course support';
$string['soporte_curso:addinstance'] = 'Add a new course support block';
$string['soporte_curso:myaddinstance'] = 'Add a new course support block to the Dashboard';
$string['block_title'] = 'Need help?';
$string['help_text'] = 'If you have technical issues or questions about the course, we are here to help.';
$string['contact_email'] = 'support@example.edu';
$string['btn_text'] = 'View frequently asked questions';
$string['faq_url'] = 'https://example.edu/help';

<?php

defined('MOODLE_INTERNAL') || die();

$string['pluginname'] = 'Course support';
$string['soporte_curso:addinstance'] = 'Add a new course support block';
$string['soporte_curso:myaddinstance'] = 'Add a new course support block to the Dashboard';
$string['block_title'] = 'Need help?';
$string['help_text'] = 'If you have technical issues or questions about the course, we are here to help.';
$string['contact_email'] = 'support@example.edu';
$string['btn_text'] = 'View frequently asked questions';
$string['faq_url'] = 'https://example.edu/help';

Traducción al castellano

Crea lang/es/block_soporte_curso.php con las mismas claves:

<?php

defined('MOODLE_INTERNAL') || die();

$string['pluginname'] = 'Soporte del curso';
$string['soporte_curso:addinstance'] = 'Añadir un bloque de soporte del curso';
$string['soporte_curso:myaddinstance'] = 'Añadir un bloque de soporte del curso al Área personal';
$string['block_title'] = '¿Necesitas ayuda?';
$string['help_text'] = 'Si tienes problemas técnicos o dudas sobre el curso, estamos aquí para ayudarte.';
$string['contact_email'] = 'soporte@example.edu';
$string['btn_text'] = 'Consultar preguntas frecuentes';
$string['faq_url'] = 'https://example.edu/ayuda';

<?php

defined('MOODLE_INTERNAL') || die();

$string['pluginname'] = 'Soporte del curso';
$string['soporte_curso:addinstance'] = 'Añadir un bloque de soporte del curso';
$string['soporte_curso:myaddinstance'] = 'Añadir un bloque de soporte del curso al Área personal';
$string['block_title'] = '¿Necesitas ayuda?';
$string['help_text'] = 'Si tienes problemas técnicos o dudas sobre el curso, estamos aquí para ayudarte.';
$string['contact_email'] = 'soporte@example.edu';
$string['btn_text'] = 'Consultar preguntas frecuentes';
$string['faq_url'] = 'https://example.edu/ayuda';

Las claves deben ser idénticas en todos los idiomas. Si Moodle no encuentra una cadena, mostrará algo parecido a [[block_title]]; suele ser una señal de nombre incorrecto o caché pendiente de purgar.

Paso 4: definir quién puede añadir el bloque

Las capacidades conectan el plugin con el sistema de roles y permisos de Moodle. No determinan quién puede ver el contenido público del bloque, sino quién puede crear una instancia en un curso o en su Área personal.

Crea db/access.php:

<?php

defined('MOODLE_INTERNAL') || die();

$capabilities = [
    'block/soporte_curso:addinstance' => [
        'riskbitmask' => RISK_SPAM | RISK_XSS,
        'captype' => 'write',
        'contextlevel' => CONTEXT_BLOCK,
        'archetypes' => [
            'editingteacher' => CAP_ALLOW,
            'manager' => CAP_ALLOW,
        ],
        'clonepermissionsfrom' => 'moodle/site:manageblocks',
    ],
    'block/soporte_curso:myaddinstance' => [
        'captype' => 'write',
        'contextlevel' => CONTEXT_SYSTEM,
        'archetypes' => [
            'user' => CAP_ALLOW,
        ],
        'clonepermissionsfrom' => 'moodle/my:manageblocks',
    ],
];

<?php

defined('MOODLE_INTERNAL') || die();

$capabilities = [
    'block/soporte_curso:addinstance' => [
        'riskbitmask' => RISK_SPAM | RISK_XSS,
        'captype' => 'write',
        'contextlevel' => CONTEXT_BLOCK,
        'archetypes' => [
            'editingteacher' => CAP_ALLOW,
            'manager' => CAP_ALLOW,
        ],
        'clonepermissionsfrom' => 'moodle/site:manageblocks',
    ],
    'block/soporte_curso:myaddinstance' => [
        'captype' => 'write',
        'contextlevel' => CONTEXT_SYSTEM,
        'archetypes' => [
            'user' => CAP_ALLOW,
        ],
        'clonepermissionsfrom' => 'moodle/my:manageblocks',
    ],
];

addinstance permite que profesorado con edición y gestores añadan el bloque. myaddinstance es la capacidad estándar para el Área personal. En la clase principal limitaremos el bloque a las vistas de curso, de modo que esta segunda capacidad queda preparada, pero el bloque no aparecerá todavía en el Área personal.

Paso 5: separar la presentación con Mustache

Podríamos concatenar HTML dentro de get_content(), pero mezclar lógica, datos y marcado produce un bloque difícil de mantener. Moodle utiliza Mustache como sistema de plantillas: PHP prepara un contexto de datos y la plantilla decide cómo representarlo.

Crea templates/content.mustache:

{{!
    @template block_soporte_curso/content

    Example context (json):
    {
        "block_title": "Need help?",
        "help_text": "We are here to help.",
        "contact_email": "support@example.edu",
        "btn_text": "View frequently asked questions",
        "faq_url": "https://example.edu/help"
    }
}}
<div class="p-3 text-center">
    <p class="h5 mb-3">{{block_title}}</p>
    <p class="mb-3 text-muted">{{help_text}}</p>

    <p class="mb-3">
        <a href="mailto:{{contact_email}}"><strong>{{contact_email}}</strong></a>
    </p>

    <a href="{{faq_url}}" class="btn btn-primary w-100">{{btn_text}}</a>
</div>

{{!
    @template block_soporte_curso/content

    Example context (json):
    {
        "block_title": "Need help?",
        "help_text": "We are here to help.",
        "contact_email": "support@example.edu",
        "btn_text": "View frequently asked questions",
        "faq_url": "https://example.edu/help"
    }
}}
<div class="p-3 text-center">
    <p class="h5 mb-3">{{block_title}}</p>
    <p class="mb-3 text-muted">{{help_text}}</p>

    <p class="mb-3">
        <a href="mailto:{{contact_email}}"><strong>{{contact_email}}</strong></a>
    </p>

    <a href="{{faq_url}}" class="btn btn-primary w-100">{{btn_text}}</a>
</div>

Las expresiones dobles {{variable}} escapan el contenido antes de insertarlo en el HTML. Esto es importante: no cambies a llaves triples salvo que el dato ya sea HTML seguro, filtrado y quieras renderizarlo deliberadamente como marcado.

Paso 6: programar la clase principal

Ahora conectaremos las cadenas de idioma con la plantilla. Crea block_soporte_curso.php en la raíz del plugin:

<?php

defined('MOODLE_INTERNAL') || die();

class block_soporte_curso extends block_base {

    /**
     * Initialises the block title.
     */
    public function init(): void {
        $this->title = get_string('pluginname', 'block_soporte_curso');
    }

    /**
     * Builds the block content.
     */
    public function get_content(): ?stdClass {
        global $OUTPUT;

        if ($this->content !== null) {
            return $this->content;
        }

        $faqurl = new moodle_url(
            get_string('faq_url', 'block_soporte_curso')
        );

        $data = [
            'block_title' => get_string('block_title', 'block_soporte_curso'),
            'help_text' => get_string('help_text', 'block_soporte_curso'),
            'contact_email' => get_string('contact_email', 'block_soporte_curso'),
            'btn_text' => get_string('btn_text', 'block_soporte_curso'),
            'faq_url' => $faqurl->out(false),
        ];

        $this->content = new stdClass();
        $this->content->text = $OUTPUT->render_from_template(
            'block_soporte_curso/content',
            $data
        );
        $this->content->footer = '';

        return $this->content;
    }

    /**
     * Restricts the block to course pages.
     */
    public function applicable_formats(): array {
        return [
            'all' => false,
            'course-view' => true,
        ];
    }

    /**
     * Prevents duplicate support blocks in the same course.
     */
    public function instance_allow_multiple(): bool {
        return false;
    }
}

<?php

defined('MOODLE_INTERNAL') || die();

class block_soporte_curso extends block_base {

    /**
     * Initialises the block title.
     */
    public function init(): void {
        $this->title = get_string('pluginname', 'block_soporte_curso');
    }

    /**
     * Builds the block content.
     */
    public function get_content(): ?stdClass {
        global $OUTPUT;

        if ($this->content !== null) {
            return $this->content;
        }

        $faqurl = new moodle_url(
            get_string('faq_url', 'block_soporte_curso')
        );

        $data = [
            'block_title' => get_string('block_title', 'block_soporte_curso'),
            'help_text' => get_string('help_text', 'block_soporte_curso'),
            'contact_email' => get_string('contact_email', 'block_soporte_curso'),
            'btn_text' => get_string('btn_text', 'block_soporte_curso'),
            'faq_url' => $faqurl->out(false),
        ];

        $this->content = new stdClass();
        $this->content->text = $OUTPUT->render_from_template(
            'block_soporte_curso/content',
            $data
        );
        $this->content->footer = '';

        return $this->content;
    }

    /**
     * Restricts the block to course pages.
     */
    public function applicable_formats(): array {
        return [
            'all' => false,
            'course-view' => true,
        ];
    }

    /**
     * Prevents duplicate support blocks in the same course.
     */
    public function instance_allow_multiple(): bool {
        return false;
    }
}

Qué ocurre en cada carga de página

1. Moodle instancia block_soporte_curso y ejecuta init().
2. Cuando necesita el contenido, llama a get_content().
3. El plugin recupera las cadenas correspondientes al idioma del usuario.
4. moodle_url valida y representa la URL del botón.
5. El contexto $data pasa a templates/content.mustache.
6. Mustache genera el HTML y escapa las variables insertadas con llaves dobles.

La comprobación de $this->content !== null evita preparar el mismo contenido más de una vez durante la carga. applicable_formats() impide que el bloque se ofrezca fuera de las páginas de curso y instance_allow_multiple() evita duplicados idénticos.

Paso 7: instalar el bloque en Moodle 4.5

Comprueba primero que la carpeta final sea blocks/soporte_curso. Un error habitual es introducir un nivel adicional al descomprimir el ZIP, por ejemplo blocks/soporte_curso/soporte_curso/version.php; Moodle no detectará esa estructura.

Instalación desde la interfaz web

1. Copia la carpeta soporte_curso dentro de /blocks.
2. Accede como administrador a Administración del sitio → Notificaciones.
3. Verifica que Moodle muestre el componente block_soporte_curso sin errores de dependencia.
4. Pulsa Actualizar base de datos Moodle ahora y espera el mensaje de confirmación.

Alternativa por línea de comandos

En despliegues automatizados es preferible ejecutar la actualización desde la raíz de Moodle:

php admin/cli/upgrade.php --non-interactive

php admin/cli/upgrade.php --non-interactive

Ejecuta el comando con el usuario correcto del sistema y dentro de tu procedimiento habitual de mantenimiento, copia de seguridad y reversión.

Paso 8: añadir y probar el bloque

1. Entra en un curso con un usuario que tenga permisos de edición.
2. Activa el modo de edición.
3. Abre el cajón lateral y pulsa Agregar un bloque.
4. Busca Soporte del curso si utilizas castellano o Course support si utilizas inglés.
5. Selecciona el bloque y comprueba que aparece en el cajón.

Prueba mínima antes de darlo por terminado

Cuándo purgar las cachés de Moodle

Durante el desarrollo, Moodle puede conservar cadenas, plantillas y metadatos del plugin. Si un cambio correcto no aparece, ve a Administración del sitio → Desarrollo → Purgar todas las cachés o ejecuta:

php admin/cli/purge_caches.php

php admin/cli/purge_caches.php

Purgar cachés es una comprobación útil, no una solución universal. Si el error persiste al crear un bloque en Moodle 4.5, revisa el registro de PHP, la depuración de Moodle, los nombres de componente y los permisos de archivos.

Errores comunes al crear un bloque en Moodle 4.5

Qué falta antes de considerarlo un plugin de producción

El bloque ya funciona, pero «funciona en mi curso» no equivale a «está listo para distribuir». Antes de instalarlo en una plataforma real, revisa:

Este trabajo no añade una función llamativa a la demo, pero evita que un plugin pequeño se convierta en deuda técnica cuando llegue a decenas de cursos.

La limitación actual y lo que haremos en la Parte 2

Preguntas frecuentes

Conclusión: ya tienes tu primer bloque en Moodle 4.5

Ahora ya sabes crear un bloque en Moodle 4.5 con una base mantenible. Moodle reconoce el componente, controla quién puede añadirlo, resuelve sus textos según el idioma y delega la presentación en una plantilla Mustache.

La lección importante no es cómo mostrar un correo en un lateral. Es cómo encajar una necesidad sencilla dentro de las convenciones de una plataforma grande sin crear una excepción difícil de mantener.

A partir de aquí puedes ampliar el bloque con configuración, permisos específicos, estilos propios, eventos o datos procedentes de otras APIs. Esa evolución será mucho más segura porque la base ya respeta la forma en la que Moodle espera que trabajen sus plugins.