Coloration Syntaxique

Pourquoi un nouveau plugin ?

L’objectif du plugin est d’ajouter très simplement la possibilité de partager des portions de codes informatique au sein de vos contenus éditoriaux (articles, rubriques, etc...).

Le plugin coloration_code permet lui aussi de coloriser vos portions de code mais il utilise la librairie HighlightJS alors que ce plugin utilise PrismJS. Vous avez donc maintenant le choix en fonction de vos besoins si vous préférez HighlightJS ou PrismJS.

Le but de ce plugin est de rester très minimaliste, selon le principe « KISS, Keep It Simple, Stupid ».

Il ne dépend d’aucun autre plugin et charge les css/javascript de coloration syntaxique uniquement si il y a des balises <code> dans la page pour optimiser et alléger le rendu des pages.

Fonctionnalités

• Le plugin ajoute la coloration syntaxique à tous les langages de programmation supportés par la librairie PrismJS. Il inclut aussi la prise en charge des langages spip (pour la typographie SPIP) et spip-squelette (pour les squelettes SPIP) pour faciliter le partage au sein de la communauté SPIP 😊.
• Une unification de l’utilisation des raccourcis typographiques <cadre>, <frame>, et <code> est faite
  pour afficher le même résultat quelque soit le raccourci utilisé.
• Le raccourci <pre> est quant à lui échappé et sécurisé sans traitement des balises <code> qu’il peut contenir.
• Le raccourci typographique backtick simple markdown (ex. `ligne de code...`) est maintenant traité lors de l’appel de la fonction typo(), permettant ainsi d’ajouter du code sur une ligne au fil du texte dans vos titres, sous-titres et autres champs apparentés.
• Le plugin facilite le copier-coller des blocs de code. En survolant un bloc de code, un bouton « Copier » s’affiche et au clic le contenu est copié dans le presse-papier.
• Le plugin corrige aussi un bug du core SPIP qui affiche parfois en base64 des parties d’une portion de code (par exemple : <span class="base64" title="PGNvZGUgY2xhc3M9J3NwaXBfY29kZSBzcGlwX2NvZGVfaW5saW5lJyBkaXI9J2x0cic+dGVzdDwvY29kZT4="></span>).
• Unification de la coloration syntaxique avec le squelette inclure/coloration_syntaxique.html pour pouvoir être utilisé directement depuis un squelette ou un raccourci typographique.
• Chargement des css/javascript de coloration syntaxique uniquement si il y a des balises <code> dans la page pour optimiser et alléger le rendu des pages.
• Un nouveau raccourci typographique SPIP <exemple_de_code> pour présenter proprement un exemple de code html ou spip.

Compatibilité et prérequis du plugin SPIP

Le plugin est compatible avec :

• SPIP 4.2+
• PHP 8.1+

Utilisation

Le plugin utilise le plugin porte_plume pour ajouter des boutons à la barre d’édition de code informatique.

Code en ligne

`...votre portion de code...`

Le raccourci «backtick» simple, comme en Markdown [1], est utilisé pour afficher du code informatique au fil du texte. Cette portion de code informatique se trouve au sein d’un texte et reprend les caractéristiques typographiques de celui-ci tout en étant encadré.

Bloc de code

Pour afficher des portions de code informatique de plusieurs lignes, le triple «backtick» doit être utilisé (comme en Markdown [1]). Cela permet de bien restituer les indentations au début de chaque ligne.

Coloration syntaxique

Consultez la liste des langages de programmation supportés pour connaitre la référence d’un langage de programmation.

Il est possible de préciser un langage de programmation pour activer une coloration syntaxique du code. Pour cela, ajouter la référence du langage concerné juste après les 3 premiers «backtick». Par exemple pour du code HTML, commencez votre portion de code avec la référence : html.

Exemples

CSS

Le code suivant :

```css
.container {
	width: 900px;
}
.container div {
	display: inline-block;
	width: 300px;
}
```

Affichera :

HTML

Le code suivant :

```html
<div class="container">
	<div><p>Lorem Elsass ipsum bredele [...]</p></div>
	<div><p>Lorem Elsass ipsum bredele [...]</p></div>
	<div><p>Lorem Elsass ipsum bredele [...]</p></div>
</div>
```

Affichera :

Coloration syntaxique spécifique à SPIP

Pour faciliter le partage de portion de code SPIP et SQUELETTE, le plugin inclut la prise en charge des langages spip (pour la typographie SPIP) et spip-squelette (pour les squelettes SPIP).

Le code suivant :

```spip
{{{ Un intertitre }}}

Du texte avec {de l’italique} et {{du gras}} ou un {{ {mélange des deux} }}.
Un retour à la ligne avec [un lien externe->https://www.spip.net], [un lien interne->art2] et un lien interne avec un titre automatique [->rubrique2].

-* Une liste
-* Une liste
-** Sous élément de liste

-# Une liste ordonnée
-# Une liste ordonnée
-## Sous élément de liste ordonnée

Un séparateur
----
```

Affichera :

Le code suivant :

```spip-squelette
<footer class="footer clearfix" role="contentinfo">
	<p class="colophon">
		<BOUCLE_annee(ARTICLES){par date}{0,1}>[(#DATE|annee|!={#VAL{Y}|date}|oui)[(#DATE|annee)]]</BOUCLE_annee> - </B_annee>[(#DATE|annee) ]#NOM_SITE_SPIP
		<br /><a rel="contents" href="#URL_PAGE{plan}" class="first"><:plan_site:></a>[
		(#SESSION{id_auteur}|non) | <a href="[(#URL_PAGE{login}|parametre_url{url,#SELF})]" rel="nofollow" class='login_modal'><:lien_connecter:></a>][
		(#AUTORISER{ecrire})| <a href="#CONST{_DIR_RESTREINT_ABS}"><:espace_prive:></a>][
		(#SESSION{id_auteur}|oui) | <a href="#URL_LOGOUT" rel="nofollow"><:icone_deconnecter:></a>] | 
		<a rel="nofollow" href="#URL_PAGE{contact}"><:contact:></a> |
		<a href="#URL_PAGE{backend}" rel="alternate" title="<:syndiquer_site:>" class="last">RSS&nbsp;2.0</a>
	</p>
	[<small class="generator"><a href="https://www.spip.net/" rel="generator" title="<:site_realise_avec_spip:>" class="generator spip_out">(#CHEMIN{spip.svg}|balise_svg{'',SPIP})</a></small>]
</footer>
```

Affichera :

Nouveau raccourci SPIP : <exemple_de_code>

Une fois activé, le plugin permet l’utilisation du raccourci <exemple_de_code>...</exemple_de_code> dans vos contenus éditoriaux. Ce raccourci permet de présenter proprement un exemple de code html ou spip qui affichera successivement le rendu puis le code source de l’exemple.

Paramètres

Comme pour les modèles SPIP des paramètres sont disponibles :

• langage (spip par défaut)
• titre (Exemple de code : $langage$ par défaut)

Exemples d’utilisations

Avec les paramètres par défaut :

<exemple_de_code>
	Du texte avec {de l’italique} et {{du gras}} ou un {{ {mélange des deux} }}.
</exemple_de_code>

Avec un titre personnalisé :

<exemple_de_code|titre=Titre personnalisé>
	Du texte avec {de l’italique} et {{du gras}} ou un {{ {mélange des deux} }}.
</exemple_de_code>

Avec du code HTML :

<exemple_de_code|html>
	<div class="container">
		<div><p>Lorem Elsass ipsum bredele [...]</p></div>
		<div><p>Lorem Elsass ipsum bredele [...]</p></div>
		<div><p>Lorem Elsass ipsum bredele [...]</p></div>
	</div>
</exemple_de_code>

2 nouveaux squelettes SPIP pour afficher des portions de code informatique

Vous trouverez une explication plus détaillée des paramètres d’inclusions directement dans le code source de chaque squelette.

inclure/coloration_syntaxique

#SET{code,#CHEMIN{demo/coloration_syntaxique_code.html}|spip_file_get_contents}
<INCLURE{
	fond=inclure/coloration_syntaxique,
	langage=html,
	code=#GET{code},
}>

inclure/exemple_de_code

#SET{code,#CHEMIN{demo/coloration_syntaxique_exemple_de_code.spip}|spip_file_get_contents}
<INCLURE{
	fond=inclure/exemple_de_code,
	code=#GET{code},
}>

3 nouveaux pipelines SPIP

2 pipelines pour vos CSS et Javascript

Pour alléger le chargement des pages, le plugin déclenche dynamiquement le chargement des CSS/Javascript nécessaire à
la coloration syntaxique uniquement si une portion de code est présente dans la page.

Pour ajouter vos propres CSS/Javascript vous pouvez utiliser les pipelines suivant en indiquant le chemin du fichier CSS/Javascript
à charger dynamiquement :

• coloration_syntaxique_css
• coloration_syntaxique_javascript

/**
 * @pipeline coloration_syntaxique_css
 * 
 * @param array $flux
 * 
 * @return $flux
 **/
function nomdevotreplugin_coloration_syntaxique_css($flux) {

	// exemple pour 2 feuilles de styles CSS chargées dynamiquement :

	// 1. Feuille de style CSS sous forme de squelette `css/coloration_syntaxique_nomdevotreplugin_squelette.css.html`
	$flux['css/coloration_syntaxique_nomdevotreplugin_squelette.css'] = produire_fond_statique('css/coloration_syntaxique_nomdevotreplugin_squelette.css');

	// 2. Feuille de style CSS simple `css/coloration_syntaxique_nomdevotreplugin.css`
	$flux['css/coloration_syntaxique_nomdevotreplugin.css'] = timestamp(find_in_path('css/coloration_syntaxique_nomdevotreplugin.css'));

	return $flux;
}

1 pipeline pour personnaliser l’affichage du code source d’un exemple de code

Lors de l’affichage d’un exemple_de_code, vous pouvez utiliser le pipeline exemple_de_code_source.

/**
 * @pipeline exemple_de_code_source
 * 
 * @param array $flux => [
 *     'args' => [
 *         'code'              => {string}, // code source de l'exemple
 *         'langage',          => {string}, // langage de l'exemple (spip|html)
 *         'titre',            => {string}, // titre de l'exemple
 *         'nombre_de_lignes', => {int},    // nombre de lignes du code source de l'exemple
 *     ],
 *     'data' => {string}, // rendu HTML de l'affichage du code source de l'exemple
 * ]
 * 
 * @return $flux
 **/
function nomdevotreplugin_exemple_de_code_source($flux) {

	// ne pas afficher le code source de l'exemple sur l'espace privé
	if ( test_espace_prive() ) {
		return '';
	}
	else {
		$exemple = '<div style="text-align:center;">';
		$exemple .= '<p><strong>Titre :</strong> '.$flux['args']['titre'].'</p>';
		$exemple .= '<p><strong>Langage :</strong> '.$flux['args']['langage'].'</p>';
		$exemple .= '<p><strong>Nombre de lignes :</strong> '.$flux['args']['nombre_de_lignes'].'</p>';
		$exemple .= '</div>';

		$flux['data'] .= $exemple;
	}

	return $flux;
}