mirror of
https://github.com/wassname/talk.git
synced 2026-07-01 18:58:29 +08:00
English version of docs
This commit is contained in:
Kim Gardner
@@ -0,0 +1,169 @@
|
||||
---
|
||||
title: Slots and Plugins
|
||||
permalink: /slots-and-plugins/
|
||||
---
|
||||
|
||||
Plugins make use of **"slots"** in order to change Talk's interface.
|
||||
|
||||
By default, Talk has various plugins provided by default. We can see this in `plugins.default.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"server": [
|
||||
"talk-plugin-auth",
|
||||
"talk-plugin-featured-comments",
|
||||
"talk-plugin-offtopic",
|
||||
"talk-plugin-respect"
|
||||
],
|
||||
"client": [
|
||||
"talk-plugin-auth",
|
||||
"talk-plugin-author-menu",
|
||||
"talk-plugin-comment-content",
|
||||
"talk-plugin-featured-comments",
|
||||
"talk-plugin-flag-details",
|
||||
"talk-plugin-ignore-user",
|
||||
"talk-plugin-member-since",
|
||||
"talk-plugin-moderation-actions",
|
||||
"talk-plugin-offtopic",
|
||||
"talk-plugin-permalink",
|
||||
"talk-plugin-respect",
|
||||
"talk-plugin-sort-most-replied",
|
||||
"talk-plugin-sort-most-respected",
|
||||
"talk-plugin-sort-newest",
|
||||
"talk-plugin-sort-oldest",
|
||||
"talk-plugin-viewing-options",
|
||||
"talk-plugin-profile-settings"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Let's only focus on the plugins which are listed under `client` - these are the plugins that use *slots* to inject certain functionality into the Talk UI.
|
||||
|
||||
For example, if we look at the Respect plugin (`talk-plugin-respect`), we can see its `client/index.js` looks like this:
|
||||
|
||||
|
||||
```js
|
||||
import RespectButton from './RespectButton';
|
||||
import translations from './translations.yml';
|
||||
|
||||
export default {
|
||||
translations,
|
||||
slots: {
|
||||
commentReactions: [RespectButton],
|
||||
},
|
||||
};
|
||||
|
||||
```
|
||||
|
||||
Inside the `slots` property, we specify which **slots** the plugin will use. Above we are saying that the `RespectButton` component is being injected into the slot `commentReactions`.
|
||||
|
||||
Slots can receive an Array of components, so we can use one plugin or many for one slot.
|
||||
|
||||
### Anatomy of the Slot Component
|
||||
|
||||
In Talk core, we have 32 slots available for us to use. The component `Slot` has a `fill` property where we establish the name of the slot. It looks like this:
|
||||
|
||||
|
||||
```js
|
||||
<Slot
|
||||
fill="commentReactions"
|
||||
{...props}
|
||||
/>
|
||||
```
|
||||
|
||||
You won't have to use this to build plugins, but it's helpful to find where to embed your plugin.
|
||||
|
||||
### Slot List
|
||||
|
||||
* `adminCommentDetailArea`
|
||||
* `adminCommentMoreDetails`
|
||||
* `adminCommentLabels`
|
||||
* `adminModerationSettings`
|
||||
* `adminStreamSettings`
|
||||
* `adminTechSettings`
|
||||
* `adminCommentInfoBar`
|
||||
* `adminCommentContent`
|
||||
* `adminSideActions`
|
||||
* `adminModeration`
|
||||
* `adminModerationIndicator`
|
||||
|
||||
* `commentInputDetailArea`
|
||||
* `commentAvatar`
|
||||
* `commentAuthorName`
|
||||
* `commentAuthorTags`
|
||||
* `commentTimestamp`
|
||||
* `commentInfoBar`
|
||||
* `commentContent`
|
||||
* `commentReactions`
|
||||
* `commentActions`
|
||||
* `commentInputArea`
|
||||
|
||||
* `draftArea`
|
||||
* `streamSettings`
|
||||
* `historyCommentTimestamp`
|
||||
* `profileSections`
|
||||
* `embed`
|
||||
* `stream`
|
||||
* `streamFilter`
|
||||
* `streamQuestionArea`
|
||||
* `login`
|
||||
* `userProfile`
|
||||
* `userDetailCommentContent`
|
||||
|
||||
### Where should I insert my plugin?
|
||||
|
||||
The first thing we should consider is what components will be affected by our plugin's functionality. For example, if we want to add functionality to all the comments that are rendered in a total list of comments, we would use the component `Comment`.
|
||||
|
||||
The slots that are able to add functionality to comments start with `comment`, like `commentContent`, or `commentReactions`, as you can see above.
|
||||
|
||||
### Disabling plugins via `plugins_config`
|
||||
|
||||
Typically, you will manage plugins via your `plugins.json` file. If you want to remove a plugin, you would simply delete it there. However, we can also do this directly with the `plugins_config`.
|
||||
|
||||
Let's look at our example article, `views/article.ejs`. Here we see can we have the Talk embed, and within the embed, we can also send a configuration object. To disable a plugin visually, we can pass `true` to the property `disable_components`. Like so:
|
||||
|
||||
|
||||
```js
|
||||
plugins_config: {
|
||||
'talk-plugin-love': {
|
||||
disable_components: true,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Sending information to slots and plugins
|
||||
|
||||
|
||||
Inside our `plugins_config`, we can also send properities and our plugins will receive them. For example, if we send this:
|
||||
|
||||
```js
|
||||
plugins_config: {
|
||||
test: 'data'
|
||||
}
|
||||
```
|
||||
|
||||
The plugin will receive a config object with the properties we've passed. If we do a `console.log` with `this.props`, we would see:
|
||||
|
||||
```js
|
||||
config: {test: 'data'}
|
||||
```
|
||||
|
||||
### Debugging slots and plugins
|
||||
|
||||
|
||||
You can debug slots and plugins simply by passing the `debug` property with value `true`:
|
||||
|
||||
|
||||
```js
|
||||
plugins_config: {
|
||||
debug: true
|
||||
}
|
||||
```
|
||||
|
||||
This will turn on a visual aid to show you all of Talk's available slots and their names. Just move your mouse around!
|
||||
|
||||
### Slot ClassNames
|
||||
|
||||
Slots autogenerate their classes with the prefix `talk-slot`, followed by the name of the slot in kebab case.
|
||||
|
||||
For example, the class autogenerated for the slot `commentContent` is `talk-slot-comment-content`.
|
||||
@@ -0,0 +1,157 @@
|
||||
# Plugins y Slots
|
||||
Los *Slots* son una parte muy importante para crear plugins. Estos nos permiten inyectar nuestros plugins en la interfaz visual de Talk.
|
||||
|
||||
Talk por defecto muestra varios plugins - Observemos el archivo `plugins.default.json` :
|
||||
|
||||
```json
|
||||
{
|
||||
"server": [
|
||||
"talk-plugin-auth",
|
||||
"talk-plugin-featured-comments",
|
||||
"talk-plugin-offtopic",
|
||||
"talk-plugin-respect"
|
||||
],
|
||||
"client": [
|
||||
"talk-plugin-auth",
|
||||
"talk-plugin-author-menu",
|
||||
"talk-plugin-comment-content",
|
||||
"talk-plugin-featured-comments",
|
||||
"talk-plugin-flag-details",
|
||||
"talk-plugin-ignore-user",
|
||||
"talk-plugin-member-since",
|
||||
"talk-plugin-moderation-actions",
|
||||
"talk-plugin-offtopic",
|
||||
"talk-plugin-permalink",
|
||||
"talk-plugin-respect",
|
||||
"talk-plugin-sort-most-replied",
|
||||
"talk-plugin-sort-most-respected",
|
||||
"talk-plugin-sort-newest",
|
||||
"talk-plugin-sort-oldest",
|
||||
"talk-plugin-viewing-options",
|
||||
"talk-plugin-profile-settings"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
La parte que nos interesa es `client`, ya que estos son los plugins que van a utilizar los *slots* para meterse en distintas partes de Talk.
|
||||
|
||||
Por ejemplo: Si observamos el plugin `talk-plugin-respect`, que está dentro de la carpeta `plugins` vamos a notar que el `client/index.js` luce asi:
|
||||
|
||||
```js
|
||||
import RespectButton from './RespectButton';
|
||||
import translations from './translations.yml';
|
||||
|
||||
export default {
|
||||
translations,
|
||||
slots: {
|
||||
commentReactions: [RespectButton],
|
||||
},
|
||||
};
|
||||
|
||||
```
|
||||
|
||||
Dentro de la propiedad `slots` especificamos qué *slots* utilizará el plugin. Ahí estamos diciendo que el componente `RespectButton` se incrustará en el slot `commentReactions`.
|
||||
|
||||
Los slots reciben un /Array/ de componentes. Es decir, puede ser uno o varios.
|
||||
|
||||
### Anatomía del component Slot
|
||||
En el core de Talk tenemos 32 slots declarados. El componente Slot tiene una propiedad `fill` donde establecemos el nombre del slot. Una declaración de un `<Slot>` luce así:
|
||||
|
||||
```js
|
||||
<Slot
|
||||
fill="commentReactions"
|
||||
{...props}
|
||||
/>
|
||||
```
|
||||
|
||||
Esto probablemente no lo utilices para desarrollar plugins, pero sí para buscar donde se va a embeber tu plugin.
|
||||
|
||||
### Lista de Slots
|
||||
|
||||
* `adminCommentDetailArea`
|
||||
* `adminCommentMoreDetails`
|
||||
* `adminCommentLabels`
|
||||
* `adminModerationSettings`
|
||||
* `adminStreamSettings`
|
||||
* `adminTechSettings`
|
||||
* `adminCommentInfoBar`
|
||||
* `adminCommentContent`
|
||||
* `adminSideActions`
|
||||
* `adminModeration`
|
||||
* `adminModerationIndicator`
|
||||
|
||||
* `commentInputDetailArea`
|
||||
* `commentAvatar`
|
||||
* `commentAuthorName`
|
||||
* `commentAuthorTags`
|
||||
* `commentTimestamp`
|
||||
* `commentInfoBar`
|
||||
* `commentContent`
|
||||
* `commentReactions`
|
||||
* `commentActions`
|
||||
* `commentInputArea`
|
||||
|
||||
* `draftArea`
|
||||
* `streamSettings`
|
||||
* `historyCommentTimestamp`
|
||||
* `profileSections`
|
||||
* `embed`
|
||||
* `stream`
|
||||
* `streamFilter`
|
||||
* `streamQuestionArea`
|
||||
* `login`
|
||||
* `userProfile`
|
||||
* `userDetailCommentContent`
|
||||
|
||||
### Cómo sé donde colocar mi plugin?
|
||||
|
||||
Lo primero que debemos pensar es a qué componente afectará la funcionalidad del plugin. Por ejemplo, si queremos agregar funcionalidad a todos los comentarios que se renderizan en la lista total de comentarios, esto tendrá que ver con el componente `Comment`.
|
||||
|
||||
Los slots habilitados para agregar funcionalidad a los comentarios tienen un prefix `comment` como el `commentContent` o el `commentReactions`, que vimos previamente.
|
||||
|
||||
### Deshabilitando plugins por configuración
|
||||
|
||||
Los plugins se eliminan borrando su entrada en el `plugins.json`. Pero si por alguna razón necesitamos hacerlo por configuración, podemos hacerlo.
|
||||
|
||||
Dentro de `views/article.ejs` embebemos Talk y notarás que podemos envialarle un objeto de configuración. Para deshabilitar visualmente a los plugins podemos utilizar la propiedad `disable_components` en `true`. y se utiliza de la siguiente forma:
|
||||
|
||||
```js
|
||||
plugins_config: {
|
||||
'talk-plugin-love': {
|
||||
disable_components: true,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Enviando información a los slots / plugins
|
||||
|
||||
Dentro de `plugins_config` podemos pasar todas las propiedades que queramos y los plugins las recibirán.
|
||||
|
||||
Por ejemplo: Si enviamos esto
|
||||
```js
|
||||
plugins_config: {
|
||||
test: 'data'
|
||||
}
|
||||
```
|
||||
|
||||
El plugin recibirá por props un objeto config con las propiedades que le pasamos. Haciendo un console.log de `this.props` verás:
|
||||
|
||||
```js
|
||||
config: {test: 'data'}
|
||||
```
|
||||
|
||||
### Debug Slots
|
||||
|
||||
Podés debuggear Slots / Plugins sólo con pasar la propiedad `debug` con valor `true`.
|
||||
|
||||
```js
|
||||
plugins_config: {
|
||||
debug: true
|
||||
}
|
||||
```
|
||||
|
||||
Esto mostrará todos los slots disponibles en la UI y su nombre si pasas el mouse sobre ellos.
|
||||
|
||||
### Slot ClassNames
|
||||
Los slots autogeneran sus clases con el prefijo `talk-slot-` seguido del nombre del slot en kebab case.
|
||||
Por ejemplo, la clase autogenerada del slot `commentContent` es `talk-slot-comment-content`.
|
||||
@@ -0,0 +1,170 @@
|
||||
---
|
||||
title: Plugins Overview
|
||||
permalink: /plugin-slots/
|
||||
toc: true
|
||||
---
|
||||
|
||||
Plugins make use of "slots" in order to change Talk's interface.
|
||||
|
||||
By default, Talk has various plugins provided by default. We can see this in `plugins.default.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"server": [
|
||||
"talk-plugin-auth",
|
||||
"talk-plugin-featured-comments",
|
||||
"talk-plugin-offtopic",
|
||||
"talk-plugin-respect"
|
||||
],
|
||||
"client": [
|
||||
"talk-plugin-auth",
|
||||
"talk-plugin-author-menu",
|
||||
"talk-plugin-comment-content",
|
||||
"talk-plugin-featured-comments",
|
||||
"talk-plugin-flag-details",
|
||||
"talk-plugin-ignore-user",
|
||||
"talk-plugin-member-since",
|
||||
"talk-plugin-moderation-actions",
|
||||
"talk-plugin-offtopic",
|
||||
"talk-plugin-permalink",
|
||||
"talk-plugin-respect",
|
||||
"talk-plugin-sort-most-replied",
|
||||
"talk-plugin-sort-most-respected",
|
||||
"talk-plugin-sort-newest",
|
||||
"talk-plugin-sort-oldest",
|
||||
"talk-plugin-viewing-options",
|
||||
"talk-plugin-profile-settings"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Let's only focus on the plugins which are listed under `client` - these are the plugins that use *slots* to inject certain functionality into the Talk UI.
|
||||
|
||||
For example, if we look at the Respect plugin (`talk-plugin-respect`), we can see its `client/index.js` looks like this:
|
||||
|
||||
|
||||
```js
|
||||
import RespectButton from './RespectButton';
|
||||
import translations from './translations.yml';
|
||||
|
||||
export default {
|
||||
translations,
|
||||
slots: {
|
||||
commentReactions: [RespectButton],
|
||||
},
|
||||
};
|
||||
|
||||
```
|
||||
|
||||
Inside the `slots` property, we specify what *slots* the plugin will use. Above we are saying that the `RespectButton` component is being injected into the slot `commentReactions`.
|
||||
|
||||
Slots can receive an Array of components, so we can use one plugin or many for one slot.
|
||||
|
||||
### Anatomy of the Slot Component
|
||||
|
||||
In Talk core, we have 32 slots available for us to use. The component `Slot` has a `fill` property where we establish the name of the slot. It looks like this:
|
||||
|
||||
|
||||
```js
|
||||
<Slot
|
||||
fill="commentReactions"
|
||||
{...props}
|
||||
/>
|
||||
```
|
||||
|
||||
You won't have to use this to build plugins, but it's helpful to find where to embed your plugin.
|
||||
|
||||
### Slot List
|
||||
|
||||
* `adminCommentDetailArea`
|
||||
* `adminCommentMoreDetails`
|
||||
* `adminCommentLabels`
|
||||
* `adminModerationSettings`
|
||||
* `adminStreamSettings`
|
||||
* `adminTechSettings`
|
||||
* `adminCommentInfoBar`
|
||||
* `adminCommentContent`
|
||||
* `adminSideActions`
|
||||
* `adminModeration`
|
||||
* `adminModerationIndicator`
|
||||
|
||||
* `commentInputDetailArea`
|
||||
* `commentAvatar`
|
||||
* `commentAuthorName`
|
||||
* `commentAuthorTags`
|
||||
* `commentTimestamp`
|
||||
* `commentInfoBar`
|
||||
* `commentContent`
|
||||
* `commentReactions`
|
||||
* `commentActions`
|
||||
* `commentInputArea`
|
||||
|
||||
* `draftArea`
|
||||
* `streamSettings`
|
||||
* `historyCommentTimestamp`
|
||||
* `profileSections`
|
||||
* `embed`
|
||||
* `stream`
|
||||
* `streamFilter`
|
||||
* `streamQuestionArea`
|
||||
* `login`
|
||||
* `userProfile`
|
||||
* `userDetailCommentContent`
|
||||
|
||||
### Where should I insert my plugin?
|
||||
|
||||
The first thing we should consider is what components will be affected by our plugin's functionality. For example, if we want to add functionality to all the comments that are rendered in a total list of comments, we would use the component `Comment`.
|
||||
|
||||
The slots that are able to add functionality to comments start with `comment`, like `commentContent`, or `commentReactions`, as you can see above.
|
||||
|
||||
### Disabling plugins via `plugins_config`
|
||||
|
||||
Typically, you will manage plugins via your `plugins.json` file. If you want to remove a plugin, you would simply delete it there. However, we can also do this directly with the `plugins_config`.
|
||||
|
||||
Let's look at our example article, `views/article.ejs`. Here we see can we have the Talk embed, and within the embed, we can also send a configuration object. To disable a plugin visually, we can pass `true` to the property `disable_components`. Like so:
|
||||
|
||||
|
||||
```js
|
||||
plugins_config: {
|
||||
'talk-plugin-love': {
|
||||
disable_components: true,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Sending information to slots and plugins
|
||||
|
||||
|
||||
Inside our `plugins_config`, we can also send properities and our plugins will receive them. For example, if we send this:
|
||||
|
||||
```js
|
||||
plugins_config: {
|
||||
test: 'data'
|
||||
}
|
||||
```
|
||||
|
||||
The plugin will receive a config object with the properties we've passed. If we do a `console.log` with `this.props`, we would see:
|
||||
|
||||
```js
|
||||
config: {test: 'data'}
|
||||
```
|
||||
|
||||
### Debugging slots and plugins
|
||||
|
||||
|
||||
You can debug slots and plugins simply by passing the `debug` property with value `true`:
|
||||
|
||||
|
||||
```js
|
||||
plugins_config: {
|
||||
debug: true
|
||||
}
|
||||
```
|
||||
|
||||
This will turn on a visual aid to show you all of Talk's available slots and their names. Just move your mouse around!
|
||||
|
||||
### Slot ClassNames
|
||||
|
||||
Slots autogenerate their classes with the prefix `talk-slot`, followed by the name of the slot in kebab case.
|
||||
|
||||
For example, the class autogenerated for the slot `commentContent` is `talk-slot-comment-content`.
|
||||
Reference in New Issue
Block a user