Discourse incluye cientos de Plugin Outlets que pueden utilizarse para inyectar nuevo contenido o reemplazar contenido existente en la interfaz de usuario de Discourse. Los ‘argumentos del outlet’ están disponibles para que el contenido pueda personalizarse según el contexto.
Elegir un outlet
Para encontrar el nombre de un plugin outlet, busca en el núcleo de Discourse “<PluginOutlet”, o utiliza el componente de tema plugin outlet locations. (por ejemplo, topic-above-posts).
Outlets de envoltura (wrapper)
Algunos outlets en el núcleo se ven como <PluginOutlet @name="foo" />. Estos te permiten inyectar nuevo contenido. Otros outlets ‘envuelven’ una implementación existente del núcleo de esta manera:
<PluginOutlet @name="foo">
implementación del núcleo
</PluginOutlet>
Definir un conector para este tipo de outlet ‘wrapper’ reemplazará la implementación del núcleo. Solo un tema/plugin activo puede contribuir con un conector para un plugin outlet wrapper.
Para los plugin outlets wrapper, puedes renderizar la implementación original del núcleo usando la palabra clave {{yield}}. Esto puede ser útil si solo deseas reemplazar la implementación del núcleo bajo ciertas condiciones, o si te gustaría envolverla en algo.
Definir el conector
Una vez que hayas elegido un outlet, decide un nombre para tu conector. Este debe ser único en todos los temas / plugins instalados en una comunidad determinada. Por ejemplo: brand-official-topics.
En tu tema / plugin, define un nuevo conector .gjs con una ruta formateada así:
{theme}/javascripts/discourse/connectors/{nombre-del-outlet}/{nombre-del-conector}.gjs
{plugin}/assets/javascripts/discourse/connectors/{nombre-del-outlet}/{nombre-del-conector}.gjs
El contenido de estos archivos se renderizará como un componente de Ember. Para información general sobre Ember y el formato .gjs, consulta las guías de Ember.
Para nuestro hipotético conector “brand official topics”, el archivo podría verse así:
<template>
<div class="alert alert-info">
Este tema fue creado por un miembro del
<a href="https://discourse.org/team">Equipo de Discourse</a>
</div>
</template>
Usar argumentos del outlet
Los Plugin Outlets proporcionan información sobre el contexto circundante a través de @outletArgs. Los argumentos pasados a cada outlet varían. Una forma sencilla de ver los argumentos es agregar esto a tu plantilla:
{{log @outletArgs}}
Esto registrará los argumentos en la consola de desarrollador de tu navegador. Aparecerán como un objeto Proxy — para explorar la lista de argumentos, expande el [[Target]] del proxy.
En nuestro ejemplo topic-above-posts, el tema renderizado está disponible bajo @outletArgs.model. Así que podemos agregar el nombre de usuario del miembro del equipo de esta manera:
<template>
<div class="alert alert-info">
Este tema fue creado por
{{@outletArgs.model.details.created_by.username}}
(un miembro del
<a href="https://discourse.org/team">Equipo de Discourse</a>)
</div>
</template>
Agregar lógica más compleja
A veces, una plantilla simple no es suficiente. Para agregar lógica de JavaScript a tu conector, actualiza tu archivo .gjs para exportar un componente basado en clases. Esto funciona exactamente igual que cualquier otra definición de componente y puede incluir inyecciones de servicios.
En nuestro ejemplo topic-above-posts, podríamos querer renderizar al usuario de manera diferente según la configuración del sitio ‘prioritize username in ux’. El archivo .gjs podría verse algo así:
.../connectors/topic-above-posts/brand-official-topic.gjs:
import Component from "@glimmer/component";
import { service } from "@ember/service";
export default class BrandOfficialTopics extends Component {
@service siteSettings;
get displayName() {
const user = this.args.outletArgs.model.details.created_by;
if (this.siteSettings.prioritize_username_in_ux) {
return user.username;
} else {
return user.name;
}
}
<template>
<div class="alert alert-info">
Este tema fue creado por
{{this.displayName}}
(un miembro del
<a href="https://discourse.org/team">Equipo de Discourse</a>)
</div>
</template>
}
Renderizado condicional
Si solo deseas que tu contenido se renderice bajo ciertas condiciones, a menudo es suficiente envolver tu plantilla con un bloque {{#if}} de Handlebars. Si eso no es suficiente, es posible que quieras usar el hook shouldRender para controlar si se renderiza o no la plantilla de tu conector.
En primer lugar, asegúrate de tener un conector .gjs basado en clases como se describe anteriormente. Luego, agrega una función static shouldRender(). Ampliando nuestro ejemplo:
import Component from "@glimmer/component";
export default class BrandOfficialTopics extends Component {
static shouldRender(outletArgs, helper) {
const firstPost = outletArgs.model.postStream.posts[0];
return firstPost.primary_group_name === "team";
}
// ... (cualquier otra lógica)
<template>{{! ... }}</template>
}
Ahora el conector solo se renderizará cuando el primer mensaje del tema haya sido creado por un miembro del equipo.
shouldRender se evalúa en un contexto de autoseguimiento de Glimmer. Los cambios futuros en cualquier propiedad referenciada (por ejemplo, outletArgs) harán que la función se vuelva a evaluar.
Introducir nuevos outlets
Si necesitas un outlet que aún no existe, siéntete libre de hacer una pull request o abrir un tema en Development.
Este documento está bajo control de versiones — sugiere cambios en github.
