Configuration client¶

La config client est un fichier JavaScript qui s'exécute dans le navigateur à l'ouverture de l'éditeur. Elle sert à ajouter des plugins GrapesJS, des transformateurs de publication et des options du CMS.

Mettre en place le fichier¶

Faites pointer SILEX_CLIENT_CONFIG vers votre fichier :

SILEX_CLIENT_CONFIG=/chemin/vers/client-config.js pnpm start

Avec Docker, montez le fichier et définissez la variable :

environment:
  SILEX_CLIENT_CONFIG: /silex/client-config.js
volumes:
  - ./client-config.js:/silex/client-config.js:ro

Le fichier remplace la config client par défaut, server/deploy/client-config.js. Elle charge le plugin d'onboarding et transforme les liens qui finissent par /index.html en liens vers le dossier (/about/index.html devient /about/). Pour garder ce comportement, copiez son contenu dans votre fichier.

Le fichier doit exporter une fonction. Elle reçoit l'objet ClientConfig :

export default async function (config) {
  // ajoutez ici plugins, transformateurs et options
  return {}
}

Comment le fichier est chargé¶

Le serveur lit le fichier une fois au démarrage et le sert à /silex.js?<version>. L'éditeur le charge avec un import() dynamique dans le navigateur. Le fichier n'est pas bundlé et ne passe pas par Node. Donc :

require() et process.env n'existent pas.
Les imports nus comme import x from 'grapesjs-tooltip' ne marchent pas.
Les imports doivent être des URL absolues (un CDN, par exemple) ou des chemins de fichiers servis par le serveur Silex.
Un import relatif comme ./plugins/x.js devient /plugins/x.js. Rien ne sert cette URL, sauf si un plugin serveur le fait (voir Créer des plugins).

Avec SILEX_DEBUG=true, le serveur relit le fichier à chaque requête. Sinon, redémarrez le serveur après une modification.

Ajouter un plugin GrapesJS¶

Un plugin GrapesJS est une fonction (editor, opts) => {}. Ajoutez-le à config.grapesJsConfig.plugins. Ses options vont dans config.grapesJsConfig.pluginsOpts, avec la fonction comme clé (GrapesJS utilise plugin.toString()) :

import tooltip from 'https://cdn.jsdelivr.net/npm/grapesjs-tooltip@0.1.8/+esm'

function helloBlock(editor, opts) {
  editor.Blocks.add('hello-block', {
    label: opts.label ?? 'Hello block',
    category: 'Elements',
    content: '<p class="hello">Hello</p>',
  })
}

export default async function (config) {
  config.grapesJsConfig.plugins.push(helloBlock, tooltip)
  config.grapesJsConfig.pluginsOpts[helloBlock.toString()] = { label: 'Hello' }
  return {}
}

Vos plugins s'exécutent avant ceux de Silex. Silex charge déjà grapesjs-custom-code, @silexlabs/grapesjs-css-variables, @silexlabs/grapesjs-fonts, @silexlabs/grapesjs-symbols, le plugin de sources de données et d'autres : ne les ajoutez pas une deuxième fois. La liste complète est dans editor/grapesjs/index.ts.

Modifier la config GrapesJS¶

Silex construit sa config GrapesJS après l'exécution de votre fichier, et ses propres clés l'emportent : blockManager, assetManager, storageManager, layerManager, selectorManager, richTextEditor et d'autres. Les plugins s'additionnent. Dans pluginsOpts, les valeurs de Silex l'emportent pour les plugins qu'il configure.

Pour modifier une clé que Silex définit, faites-le dans l'événement silex:grapesjs:start. Il se déclenche une fois que Silex a construit config.grapesJsConfig, avant le démarrage de GrapesJS :

export default async function (config) {
  config.on('silex:grapesjs:start', () => {
    config.grapesJsConfig.showOffsets = false
  })
  return {}
}

Événements¶

Écoutez-les sur l'objet config :

Événement	Argument	Moment
`silex:startup:start`	aucun	la config client est chargée
`silex:grapesjs:start`	aucun	avant le démarrage de GrapesJS, modifiez `config.grapesJsConfig` ici
`silex:grapesjs:end`	`{ editor }`	GrapesJS est prêt
`silex:startup:end`	`{ editor, config }`	le site est chargé dans l'éditeur

config.on('silex:grapesjs:end', ({ editor }) => {
  editor.on('silex:publish:end', ({ success, message }) => {
    console.log('Publié', success, message)
  })
})

Les événements de publication comme silex:publish:start, silex:publish:page, silex:publish:data et silex:publish:end se déclenchent sur l'editor GrapesJS, pas sur config. Tous les noms d'événements sont dans editor/events.ts. Dans le navigateur, window.silex.events.ClientEvent contient les mêmes noms.

Transformateurs de publication¶

Un transformateur modifie les fichiers au moment de la publication :

export default async function (config) {
  config.addPublicationTransformers({
    transformFile(file) {
      if (file.type === 'html') {
        return { ...file, content: file.content.replace('</body>', '<!-- publié avec Silex --></body>') }
      }
      return file
    },
  })
  return {}
}

addPublicationTransformers ajoute vos transformateurs après ceux par défaut. N'appelez pas resetPublicationTransformers() : il retire le transformateur par défaut, qui règle les liens entre pages et les chemins des assets dans le CSS. Voir Transformateurs de publication pour les méthodes et leurs arguments.

Options du CMS¶

Le CMS est actif par défaut. Modifiez config.cmsConfig pour le régler :

export default async function (config) {
  config.cmsConfig = {
    enabled: true,
    cacheBuster: false,
    dataSources: [{
      id: 'blog',
      label: 'Blog',
      type: 'graphql',
      url: 'https://example.com/graphql',
      method: 'POST',
      headers: {},
    }],
  }
  return {}
}

Option	Par défaut	Effet
`enabled`	`true`	`false` désactive le plugin CMS
`dataSources`	`[]`	sources de données ajoutées à tous les sites
`cacheBuster`	`false`	ajoute un cache buster aux requêtes GraphQL
`esModule`	`true`	`true` écrit les fichiers de données Eleventy en modules ES, `false` en CommonJS
`fetchPluginSettings`	d'après les réglages du site	options du plugin fetch d'Eleventy, ou `false`
`i18nPlugin`	non défini	`true` active l'option i18n pour tous les sites et la verrouille dans les réglages

Propriétés de ClientConfig¶

Propriété	Usage
`grapesJsConfig`	config GrapesJS, voir plus haut
`cmsConfig`	options du CMS, voir plus haut
`addPlugin(plugin, options)`	charge un plugin Silex `(config, options) => {}`
`addPublicationTransformers(t)`	ajoute un transformateur ou un tableau
`getEditor()`	l'éditeur GrapesJS, après `silex:grapesjs:end`
`websiteId`, `storageId`, `lang`, `rootUrl`	lus dans l'URL de l'éditeur
`fontsServerUrl`, `fontsApiUrl`, `fontsApiKey`	l'API Google Fonts ou un serveur compatible
`replacedElements`	balises qui affichent les propriétés `object-fit` dans le panneau de style
`api`	fonctions qui appellent l'API du serveur Silex
`debug`	mettez-le à `true` dans votre fichier pour afficher la config dans la console du navigateur

Dans le navigateur, window.silex.config est le même objet.

Voir aussi¶

Éditer cette page sur GitLab