NPM / STUDIO

Studio con NPM

Esta guía cubre únicamente la integración de Studio como dependencia de un proyecto. Incluye la parte del navegador y, cuando la necesites, los servicios de servidor para guardar e importar.

1. Instalar las dependencias

Instala Studio y Player en el mismo proyecto para que el editor pueda utilizar el Player durante la Vista alumno.

Terminal

npm install @p2lrn/studio@0.5.0-alpha.11 @p2lrn/player@0.5.0-alpha.11

Las versiones de Studio y Player deben estar alineadas.

2. Registrar Studio en la aplicación

Importa Studio una vez desde el código cliente. Después podrás utilizar <p2lrn-studio> en la interfaz.

JavaScript / TypeScript

import '@p2lrn/studio';

HTML mínimo

<p2lrn-studio></p2lrn-studio>

Con este montaje mínimo puedes crear un curso, abrir un archivo o una URL, editar, previsualizar y descargar un nuevo .p2lrn.

3. Abrir un curso inicial

El atributo src es opcional. Úsalo cuando la aplicación ya conoce qué curso debe abrir el editor.

HTML

<p2lrn-studio src="/courses/curso.p2lrn"></p2lrn-studio>

El atributo src es opcional. Si no lo defines, el usuario puede crear un curso nuevo desde la interfaz.

4. Generar las rutas del servidor

Después de instalar Studio, ejecuta una sola vez el setup dentro de tu proyecto. No tienes que escribir las rutas de Guardar, Reader e Importación una por una.

Terminal

npx p2lrn-studio setup

El comando localiza la raíz del proyecto, detecta la tecnología y materializa las tres operaciones: /api/p2lrn/studio/save, /api/p2lrn/studio/read y /api/p2lrn/studio/import. También crea la carpeta de cursos.

Reader ya forma parte del Toolkit instalado con Studio.

En backends JavaScript/TypeScript las rutas llaman directamente a @p2lrn/studio/server. En PHP, Python, Ruby, .NET, Java, Go y Rust, setup genera el controlador o handler del framework y un puente local de Node que ejecuta Reader e importación. No se crea ni se levanta otro servidor.

Importante antes de habilitar estas rutas para usuarios reales: la seguridad depende de tu propio sitio web.

p2lrn-studio setup crea Save, Reader e Import, pero no añade automáticamente autenticación ni permisos de usuarios. En el servidor de tu aplicación debes comprobar quién solicita cada operación y si tiene permiso para editar ese curso o centro, así como aplicar CSRF cuando uses cookies, límites de tamaño y destinos de almacenamiento autorizados. Estas comprobaciones deben hacerse antes de invocar los helpers de P2LRN. Consulta la guía de integración y seguridad. El ejemplo generado no sustituye el sistema de permisos de tu aplicación.

5. Indicar a Studio las rutas generadas

Estos atributos sólo indican al componente dónde están las rutas que setup ya ha creado. No sustituyen la creación de los archivos del backend.

HTML

<p2lrn-studio
  src="/courses/curso.p2lrn"
  save-endpoint="/api/p2lrn/studio/save"
  reader-endpoint="/api/p2lrn/studio/read"
  import-endpoint="/api/p2lrn/studio/import"
  course-path="course">
</p2lrn-studio>

save-endpoint

Ruta generada para guardar el paquete exportado.

reader-endpoint

Ruta generada que usa Reader para analizar documentos.

import-endpoint

Ruta generada para convertir paquetes educativos externos a P2LRN.

course-path

Ruta lógica de guardado. El valor por defecto es course.

6. Para qué necesita conocer la tecnología

Studio usa las mismas tres operaciones en todos los casos, pero cada backend declara sus rutas de una forma distinta. La detección sirve para generar los archivos correctos para ese proyecto.

Next.js

Crea rutas dentro de app/api/....

Nest

Crea un controlador dentro de la estructura src/.

Laravel / Symfony

Prepara controladores y, cuando corresponde, la definición de rutas.

Django / FastAPI / Flask

Prepara vistas, routers o blueprints compatibles con cada entorno.

Go / Rust / Spring / ASP.NET

Genera el handler, controlador o endpoint en el formato esperado por el proyecto.

Ver todas las tecnologías reconocidas

Next.js, Express, Nest, Fastify, Hono, SvelteKit, Nuxt, Astro, Remix, React Router, Node.js, PHP, Laravel, Symfony, Django, FastAPI, Flask, Rails, ASP.NET, Spring, Go, Rust y una integración genérica.

7. Funciones auxiliares del servidor

Si tu servidor usa JavaScript o TypeScript, el paquete expone funciones auxiliares para implementar las operaciones de guardado, Reader e importación.

JavaScript / TypeScript

import {
  handleP2LRNStudioSave,
  handleP2LRNStudioReader,
  handleP2LRNStudioExternalImport,
} from '@p2lrn/studio/server';

Protege estas rutas con la autenticación y autorización de tu aplicación. El navegador no debe poder decidir libremente rutas de escritura del servidor.

8. API del componente

createCourse(options)

Crea un curso nuevo. options admite también author, createdAt, license y copyrightHolder.

openFile(file) / openUrl(url)

Abren un paquete local o remoto.

setMode('edit' | 'preview')

Cambia entre edición y Vista alumno.

addUnit() / addLesson() / addContent()

Añaden estructura y contenido.

resourceLibrary

Propiedad opcional. Asigna un objeto con list() y get(digest) para habilitar la biblioteca compartida.

materializeSharedResource(activityId)

Convierte una referencia digest-pinned en un fallback embebido usando los bytes de la biblioteca conectada.

download() / saveCourse()

Descarga o envía el paquete al endpoint de guardado configurado.

exportOfflineAssignment() / downloadOfflineAssignment()

Generan la entrega autorreproducible de Windows o ZIP portable.

reviewOfflineResult(file)

Valida y presenta un .p2lrn-result devuelto por el alumno.

JavaScript / TypeScript · biblioteca

const studio = document.querySelector('p2lrn-studio');
studio.resourceLibrary = resourceLibrary;

9. Eventos

p2lrn-studio-create

Se ha creado un curso.

p2lrn-studio-open

Se ha abierto un paquete.

p2lrn-studio-download

Se ha descargado un paquete.

p2lrn-studio-save

Ha finalizado un guardado en servidor.

p2lrn-studio-offline-export

Se ha generado/descargado una entrega offline; incluye formato, assignmentId y contentRoot.

p2lrn-studio-offline-review

Se ha revisado un resultado offline; expone estado de integridad/coincidencia e intento.