Commentaires

La fonctionnalité principale de Hyvor Talk est l'embed de commentaires. C'est un système de commentaires en temps réel complet qui peut être intégré aux blogs, aux sites d'actualité et à d'autres sites web.

L'embed de commentaires est chargé via le Web Component <hyvor-talk-comments>. Pour commencer, ajoutez le script suivant juste avant la balise </body>. Il enregistre le Web Component <hyvor-talk-comments> sur votre page web.

<script async src="https://talk.hyvor.com/embed/embed.js" type="module"></script>

Ensuite, ajoutez l'élément <hyvor-talk-comments> à l'endroit où vous souhaitez que la section des commentaires se charge. Il est possible d'ajouter plusieurs sections de commentaires à une même page si nécessaire.

<hyvor-talk-comments website-id="YOUR_WEBSITE_ID" page-id=""></hyvor-talk-comments>
Pour des instructions spécifiques à chaque plateforme, consultez la page Installation.

Attributs

Les attributs suivants sont pris en charge dans l'élément <hyvor-talk-comments>

Attribut
Valeur
website-id
L'ID de votre site web Hyvor Talk
page-id
Un identifiant unique pour la page courante. Voir page-id.
page-url
URL de la page (facultatif).
page-title
Titre de la page (facultatif). Le titre de la page est affiché dans les notifications, les e-mails et la console. document.title est utilisé par défaut.
page-language
Remplace la langue du site web pour cette page. Voir langues.
page-author
E-mail (ou e-mail encodé en base64) de l'auteur
page-badges
Attribue des badges au niveau de la page à des utilisateurs
sso-user and sso-hash
colors
light, dark ou os. Voir Styles et couleurs
loading
Accepte default, lazy et manual. Voir loading
settings
Paramètres encodés en JSON. Voir settings
t-*
Définit des textes personnalisés. Voir traductions

page-id

L'attribut page-id sert à identifier la page courante, et c'est sans doute l'attribut le plus important.

  • S'il n'est pas défini ou s'il est vide, l'URL canonique de la page courante sera utilisée comme page-id.
  • S'il est défini, sa valeur sera utilisée comme page-id.

Chaque page-id charge un fil de discussion différent. Il est fortement recommandé d'utiliser un ID qui ne change pas dans le temps (par ex. un ID de base de données). Si un ID change, vous devrez migrer manuellement les données vers la nouvelle page. Consultez notre section sur le déplacement de données entre pages.

page-badges

L'attribut page-badges sert à attribuer des badges à des utilisateurs au niveau de la page. C'est utile, par exemple, pour donner un badge à l'auteur de la page. Il accepte une chaîne encodée en JSON :

<hyvor-talk-comments
	website-id="x"
	page-badges='{
		"sso:user-id": 3,
		"htid:hyvor_x": 1,
		"htid:sso_x": 2
	}'
></hyvor-talk-comments>

Chaque clé de l'objet JSON est un ID d'utilisateur, qui peut être de deux types.

La valeur de l'objet JSON est un ID de badge que l'on trouve dans Console → Paramètres → Badges.

settings

Tous les paramètres au niveau du site web peuvent être remplacés au niveau de la page avec l'attribut settings. Il accepte une chaîne encodée en JSON. Voici un exemple :

<hyvor-talk-comments
	website-id="x"
	settings='{
		"custom_css":"#app { font-size: 18px }",
		"profiles": {
			"pictures": false
		}
	}'
></hyvor-talk-comments>

Voici tous les paramètres disponibles :

comments.settings = {
	name: 'John Doe', // website name
	custom_css: null, // or string of CSS
	auth: {
		sso_stateless_login_url: null // or URL string
	},
	comments_view: {
		note: 'This is a note', // note shown above the comments
		close_after_days: 0, // close the page after X days (0 for never)
		is_keyboard_navigation_on: true,
		nested_levels: 3, // number of nested levels (the rest will be collapsed)
		display_replied_to_type: 'none' | 'deep' | 'all' // when to show 'replied to' tag
	},
	profiles: {
		default_sort: null, // 'top' | 'newest' | 'oldest'
		pictures: true, // show profile pictures
		profiles: true, // show profile popup
		default_picture: null, // default profile picture URL
		display_name_type: 'name', // 'name' | 'username'
		mod_alias_name: 'Moderator', // alias for moderators for company representation
		mod_alias_picture: null,
		mod_badge_id: null // for showing a special badge for moderators
	},
	realtime: {
		on: true, // enable realtime updates
		count: true, // show online count
		users: false, // show online users list
		typing: 'off' // show if someone is typing = 'off' | 'on_without_typer' | 'on_with_typer'
	},
	voting: {
		type: 'both', // 'both' | 'up' | 'down'
		voters: true // show voters list
	},
	top_widget: 'reactions', // 'reactions' | 'ratings' | 'none'
	reactions: {
		configs: [
			{
				type: 'superb', // 'superb' | 'love' | 'wow' | 'sad' |  'laugh' | 'angry'
				is_shown: true,
				image_url: 'image.png',
				text: 'Superb'
			}
			// more items
		],
		display_type: 'image' // how to display reaction = 'image' | 'text' | 'both'
	},
	ratings: {
		star_color: '#f1c40f' // color of the rating stars
	},
	text: {
		// if a string is set, it will be shown *regardless* of the language.
		comment_box: null,
		reply_box: null,
		no_comments: null,
		reactions: null,
		ratings: null,
		comment_count_0: null,
		comment_count_1: null,
		comment_count_multi: null
	},
	editor: {
		emoji: true,
		images: true,
		gifs: true,
		embeds: true, // link embedding
		mentions: true,
		code_blocks: true,
		blockquotes: true,
		inline_styles: true, // bold, italic, inline code, strike, spoiler
		links: true,
		math: true
	},
	ui: {
		width: null, // null | number - width of the comments box in pixels, 100% if null
		box_shadow: 'string', // box-shadow CSS property for boxes
		box_radius: 'string', // border-radius CSS property for boxes
		box_border_size: 'string', // border-size CSS property for boxes
		box_border_color: 'string', // border-color CSS property for the comments and other boxes
		button_radius: 'string', // border-radius CSS property for buttons
		color_theme: 'os' | 'light' | 'dark' // default color theme
	},
	light_palette: {
		text: '#000000',
		accent: '#000000',
		accent_text: '#000000',
		box: '#000000',
		box_text: '#000000',
		box_text_light: '#000000',
		input: '#000000'
	},
	dark_palette: {}, // same properties as light_palette

	// comments highlighting
	highlight: {
		new: true, // whether to highlight new comments
		new_color: '#00ff00',
		// upvote-based highlighting
		upvote_1_threshold: null, // null | number
		upvote_2_threshold: 2, // null | number
		upvote_1_color: '#0000ff',
		upvote_2_color: '#ff0000'
	}
};

t-* (custom translations)

Vous pouvez définir des traductions personnalisées avec les attributs t-.

<hyvor-talk-comments t-as-guest="Comment without account" t-newest="Latest" />

Vous trouverez les clés sur la page de traduction (connexion requise). Par exemple, si la clé est as-guest, l'attribut doit être t-as-guest. Consultez la documentation sur les langues pour plus d'informations.

Si vous devez construire dynamiquement une traduction à partir d'un contexte supplémentaire, utilisez le hook t. Pour certaines traductions, il fournit un contexte supplémentaire, comme les données du commentaire ou de l'utilisateur.

Créer le composant avec JavaScript

Au lieu d'ajouter l'élément <hyvor-talk-comments> directement dans le HTML, vous pouvez le créer avec JavaScript. C'est utile lorsque vous avez besoin d'utiliser des propriétés.

const comments = document.createElement('hyvor-talk-comments');
comments.setAttribute('website-id', 'YOUR_WEBSITE_ID');
comments.setAttribute('page-id', page.id);

document.body.appendChild(comments);

Propriétés (obsolète)

Les propriétés sont obsolètes. Utilisez plutôt l'attribut settings et les attributs t-.

1. Settings (obsolète)

La propriété settings fait la même chose que l' attribut settings. Elle n'est prise en charge que pour la rétrocompatibilité.

Notez que pour que la propriété settings fonctionne, vous devez attendre que le Web Component soit défini. La méthode la plus simple consiste à utiliser customElements.whenDefined.

customElements.whenDefined('hyvor-talk-comments').then(() => {
	// create the element
	const comments = document.createElement('hyvor-talk-comments');
	// set the settings
	comments.settings = {};
	// then append
	document.getElementById('wrap').appendChild(comments);
});

2. Translations (obsolète)

Cette propriété n'est prise en charge que pour la rétrocompatibilité. Nous recommandons aux nouveaux utilisateurs d'utiliser les attributs t- pour les traductions.

const comments = document.createElement('hyvor-talk-comments');

comments.translations = {
	sort: 'Order by',
	reactions_text: 'What do you think about this post?'
};

Chargement

Par défaut, la section des commentaires est chargée dès que le composant est ajouté au DOM. Vous pouvez personnaliser ce comportement avec l'attribut loading. Il accepte les valeurs suivantes :

  • default - commence le chargement immédiatement
  • lazy - commence le chargement lorsque l'élément est dans la zone visible (avec IntersectionObserver)
  • manual - commence le chargement lorsque .load() est appelé sur l'élément <hyvor-talk-comments>.

Chargement manuel

L'attribut loading peut être défini sur manual pour retarder l'affichage de l'embed de commentaires jusqu'à l'appel de la méthode .load(). Voici un exemple avec un bouton pour charger les commentaires :

<hyvor-talk-comments website-id="YOUR_WEBSITE_ID" page-id="" loading="manual"></hyvor-talk-comments>

<button onclick="document.querySelector('hyvor-talk-comments').load()">Charger les commentaires</button>

API

L'élément <hyvor-talk-comments> expose une mini-API avec les méthodes suivantes :

  • api.reload() - recharge la section des commentaires. Identique à .load()
  • api.page() - récupère les données de la page courante. Voir objet Page.
  • api.auth.user() - récupère les données publiques de l'utilisateur courant. Voir objet User. null s'il n'est pas connecté.
  • api.auth.logout() - déconnecte l'utilisateur courant. Supprime les données de connexion du localStorage.
  • api.hooks.register(name: string, value: Record<string, any>) - Enregistre un hook.

Voici un exemple pour récupérer les données de l'utilisateur courant :

const comments = document.querySelector('hyvor-talk-comments');
comments.api.auth.user();

Objets de l'API

Objet Page
interface Page {
	id: number;
	created_at: number;
	identifier: string;
	url: string;
	title: string;
	is_closed: boolean;
	is_premoderation_on: boolean;
	comments_count: number;
	reactions: Record<'superb' | 'love' | 'wow' | 'sad' | 'laugh' | 'angry', number>;
	ratings: {
		average: number;
		count: number;
	};
	online_count: number;
}
Objet User
interface User {
	id: number;
	type: 'hyvor' | 'sso';
	name: string;
	username: string;
	picture_url: string | null;
	bio: string | null;
	location: string | null;
	website_url: string | null;
	badges: number[];
}