Configuration client et plugins¶

Personnalisez l'éditeur Silex avec des plugins, des transformateurs de publication et des sections de paramètres.

Aperçu¶

Le fichier de configuration client s'exécute dans le navigateur au chargement de l'éditeur. Il vous permet d'ajouter des plugins (GrapesJS ou personnalisés), de définir comment les sites web sont publiés et d'étendre l'interface des paramètres. Comme la configuration serveur, c'est un plugin qui reçoit un objet ClientConfig.

Prérequis¶

Serveur configuré avec la variable d'environnement SILEX_CLIENT_CONFIG pointant vers votre fichier de configuration
Compréhension des transformateurs de publication
Connaissances de base en JavaScript

Installation¶

1. Créer un fichier de configuration client¶

Créez client-config.js dans le répertoire de votre instance Silex :

// client-config.js
export default async function (config) {
  console.log('Client config loading')
  // Add plugins, transformers, settings here
}

2. Configurer le serveur pour le servir¶

Définissez la variable d'environnement :

SILEX_CLIENT_CONFIG=./client-config.js npm start

Ou dans Docker :

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

Montez le fichier dans le conteneur :

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

3. Le fichier est chargé au démarrage¶

Lorsque les utilisateurs ouvrent l'éditeur, Silex récupère votre configuration client depuis http://your-silex.com/client-config.js?version et l'exécute. Les modifications sont prises en compte au rechargement de la page.

API ClientConfig¶

class ClientConfig extends Config {
  // Properties
  websiteId: WebsiteId
  storageId: ConnectorId
  lang: string
  rootUrl: string
  debug: boolean
  addHashInCssFileName: boolean
  replacedElements: string[]
  grapesJsConfig: EditorConfig
  clientConfigUrl: string
  fontsApiKey: string
  fontsServerUrl: string
  fontsApiUrl: string
  cmsConfig: Partial<EleventyPluginOptions> & { enabled?: boolean }
  publicationTransformers: Array<PublicationTransformer>

  // Methods
  getEditor(): Editor
  initGrapesConfig(): void
  addPlugin(plugin: Plugin | Plugin[], options?: any): Promise<void>
  addPublicationTransformers(
    transformers: PublicationTransformer | PublicationTransformer[]
  ): void
  resetPublicationTransformers(): void
  addDefaultPlugins(): Promise<void>
  addSettings(                           // deprecated
    section: SettingsSection,
    siteOrPage: 'site' | 'page',
    position?: 'first' | 'last' | number
  ): void
  removeSettings(id: string, siteOrPage: 'site' | 'page'): void
}

Ajouter des plugins¶

Plugins GrapesJS¶

Chargez n'importe quel plugin GrapesJS via npm :

// client-config.js
import grapesJsCustomCode from 'grapesjs-custom-code'
import grapesJsTooltip from 'grapesjs-tooltip'

export default async function (config) {
  // Add plugins to the GrapesJS editor
  config.grapesJsConfig.plugins = [
    ...config.grapesJsConfig.plugins,
    grapesJsCustomCode,
    grapesJsTooltip,
  ]

  // Plugin options (optional)
  config.grapesJsConfig.pluginsOpts = {
    ...config.grapesJsConfig.pluginsOpts,
    [grapesJsCustomCode]: { /* options */ },
    [grapesJsTooltip]: { /* options */ },
  }
}

Plugins personnalisés¶

Créez votre propre module de plugin :

// plugins/my-plugin.js
export default {
  name: 'MyPlugin',
  async init(editor, options) {
    console.log('My plugin initialized', options)

    // Add a custom block
    editor.Blocks.add('my-block', {
      label: 'My Block',
      content: '<div>Custom block</div>',
      category: 'Basic',
      media: '<svg>...</svg>',
    })

    // Listen to editor events
    editor.on('canvas:render', () => {
      console.log('Canvas rendered')
    })
  },
}

Puis chargez-le dans votre configuration :

// client-config.js
import myPlugin from './plugins/my-plugin.js'

export default async function (config) {
  config.grapesJsConfig.plugins = [
    ...config.grapesJsConfig.plugins,
    myPlugin,
  ]

  config.grapesJsConfig.pluginsOpts = {
    ...config.grapesJsConfig.pluginsOpts,
    MyPlugin: {
      someOption: 'value',
    },
  }
}

Ajouter des transformateurs de publication¶

Les transformateurs de publication contrôlent la manière dont les sites web sont rendus et publiés. Consultez Transformateurs de publication pour plus de détails.

Exemple : Transformer les chemins de fichiers pour un CDN :

export default async function (config) {
  config.addPublicationTransformers({
    transformPath(path, type) {
      // Rewrite CSS paths to a CDN
      if (type === 'css') {
        return path.replace(/\.css$/, '.min.css')
      }
      return path
    },

    transformPermalink(link, type, initiator) {
      // Point all assets to a CDN
      if (!link.startsWith('http')) {
        return 'https://cdn.example.com/' + link
      }
      return link
    },

    transformFile(file) {
      // Minify HTML (example using a hypothetical lib)
      if (file.type === 'html') {
        file.content = minifyHtml(file.content)
      }
      return file
    },
  })
}

Transformateurs multiples¶

Enchaînez plusieurs transformateurs :

export default async function (config) {
  // Transformer 1: Rewrite paths
  config.addPublicationTransformers({
    transformPath(path, type) {
      return path.startsWith('/') ? path : '/' + path
    },
  })

  // Transformer 2: Add cache busting
  config.addPublicationTransformers({
    transformFile(file) {
      const now = Date.now()
      file.name = file.name.replace(/\.(\w+)$/, `.${now}.$1`)
      return file
    },
  })
}

Les transformateurs s'exécutent dans l'ordre, chacun recevant la sortie du précédent.

Écouter les événements client¶

Accédez à l'éditeur et écoutez ses événements :

const { ClientEvent } = require('@silexlabs/silex/dist/client/events')

export default async function (config) {
  // Wait for GrapesJS to load
  config.on(ClientEvent.GRAPESJS_END, (editor) => {
    console.log('Editor is ready', editor)

    // Listen to publication events
    editor.on(ClientEvent.PUBLISH_START, (data) => {
      console.log('Publishing website:', data.siteSettings.name)
    })

    editor.on(ClientEvent.PUBLISH_END, (result) => {
      console.log('Publication result:', result)
    })

    editor.on(ClientEvent.SETTINGS_SAVE_START, (data) => {
      console.log('Saving settings')
    })
  })
}

Événements client¶

Événement	Émis sur	Rôle
`STARTUP_START`	config	Silex démarre (chargement de la page)
`STARTUP_END`	config	Silex est prêt
`GRAPESJS_START`	config	GrapesJS est sur le point de s'initialiser
`GRAPESJS_END`	editor	GrapesJS est prêt
`PUBLICATION_UI_OPEN`	editor	Boîte de dialogue de publication ouverte
`PUBLICATION_UI_CLOSE`	editor	Boîte de dialogue de publication fermée
`PUBLISH_BEFORE`	editor	Avant le début de la publication
`PUBLISH_START`	editor	La publication commence
`PUBLISH_PAGE`	editor	Publication d'une page unique
`PUBLISH_DATA`	editor	Avant l'envoi des données au serveur
`PUBLISH_END`	editor	Publication terminée
`PUBLISH_ERROR`	editor	La publication a échoué
`PUBLISH_LOGIN_START`	editor	Avant la connexion au connecteur
`PUBLISH_LOGIN_END`	editor	Après la connexion au connecteur
`SETTINGS_OPEN`	editor	Boîte de dialogue des paramètres ouverte
`SETTINGS_CLOSE`	editor	Boîte de dialogue des paramètres fermée
`SETTINGS_SAVE_START`	editor	Les paramètres sont sur le point d'être sauvegardés
`SETTINGS_SAVE_END`	editor	Paramètres sauvegardés

Configurer GrapesJS¶

Modifiez le comportement de l'éditeur avant son chargement :

export default async function (config) {
  // Customize GrapesJS config
  config.grapesJsConfig = {
    ...config.grapesJsConfig,
    canvas: {
      styles: ['https://fonts.googleapis.com/css?family=Roboto'],
      scripts: [],
    },
    allowScripts: 0, // Disable script tags in canvas
    blockManager: {
      blocks: [], // Clear default blocks
    },
  }
}

Configurer le CMS¶

Le CMS est intégré à Silex et activé par défaut. Personnalisez-le :

export default async function (config) {
  config.cmsConfig = {
    enabled: true,
    enable11ty: true,
    cacheBuster: false,
    dataSources: [],
    dir: {
      input: '',
      html: '',
      assets: 'assets',
      css: 'css',
    },
    urls: {
      css: '/css',
      assets: '/assets',
    },
  }
}

Pour les détails de la configuration CMS, consultez Configuration de build awesome.

Exemple complet¶

// client-config.js
import grapesJsCustomCode from 'grapesjs-custom-code'
import myPlugin from './plugins/my-plugin.js'
import { ClientEvent } = require('@silexlabs/silex/dist/client/events')

export default async function (config) {
  // Add plugins
  config.grapesJsConfig.plugins = [
    ...config.grapesJsConfig.plugins,
    grapesJsCustomCode,
    myPlugin,
  ]

  config.grapesJsConfig.pluginsOpts = {
    ...config.grapesJsConfig.pluginsOpts,
    [grapesJsCustomCode]: { languages: ['javascript', 'css'] },
    MyPlugin: { apiKey: process.env.MY_API_KEY },
  }

  // Add publication transformers
  config.addPublicationTransformers({
    transformPath(path, type) {
      return path.replace(/\.html$/, '')
    },
    transformPermalink(link) {
      if (!link.startsWith('http') && !link.startsWith('/')) {
        return '/' + link
      }
      return link
    },
  })

  // Listen to events
  config.on(ClientEvent.GRAPESJS_END, (editor) => {
    editor.on(ClientEvent.PUBLISH_END, (result) => {
      if (result.success) {
        console.log(`Published to ${result.url}`)
      } else {
        console.error(`Publication failed: ${result.message}`)
      }
    })
  })

  // Customize CMS
  config.cmsConfig.dataSources = [
    {
      id: 'wordpress',
      type: 'graphql',
      url: 'https://my-wordpress.com/graphql',
    },
  ]
}

Dépannage¶

Le fichier de configuration ne se charge pas¶

Vérifiez la console du navigateur pour les erreurs de récupération :

Ouvrez les DevTools (F12)
Vérifiez l'onglet Console pour les erreurs 404 ou de syntaxe
Vérifiez l'onglet Network : client-config.js?version devrait retourner un statut 200

Assurez-vous que SILEX_CLIENT_CONFIG est défini :

env | grep SILEX_CLIENT_CONFIG

Les plugins ne se chargent pas¶

Ajoutez des journaux de débogage :

export default async function (config) {
  console.log('Client config is running')
  console.log('GrapesJS config:', config.grapesJsConfig)
  // ... add plugins
}

Vérifiez la console du navigateur pour les erreurs lors de l'initialisation des plugins.

Les transformateurs de publication ne s'appliquent pas¶

Vérifiez qu'ils sont ajoutés avant le transformateur par défaut :

export default async function (config) {
  // Add custom transformer FIRST
  config.resetPublicationTransformers()
  config.addPublicationTransformers(myTransformer)
}

Voir aussi¶

Configuration côté serveur
Transformateurs de publication — Transformateurs de publication
Création de plugins — Création de plugins

Éditer cette page sur GitLab