Updates a Lutece FO (Front Office) template by replacing raw HTML with the FO FreeMarker macros from lutece-core. Use when the user asks to migrate, convert or update a skin/FO template with Lutece macros.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Updates a Lutece FO (Front Office) template by replacing raw HTML with the FO FreeMarker macros from lutece-core. Use when the user asks to migrate, convert or update a skin/FO template with Lutece macros.
argument-hint
template-path
Updating Lutece FO templates
You must update a Lutece FO template by replacing all raw HTML with the FO FreeMarker macros defined in lutece-core/webapp/WEB-INF/templates/skin/themes/.
Steps
Read the template target provided by the user
Identify all raw HTML elements replaceable by FO macros
Consult the macros if needed by reading the definition files in lutece-core/webapp/WEB-INF/templates/skin/themes/lutece/macros/
Rewrite the template using FO macros exclusively
Do not modify i18n files unless necessary and requested
HTML → FO Macros mapping table
Structure and Layout
HTML
Macro FO
Notes
<div class="container">
<@cContainer>
Can take class, type
<div class="row">
<@cRow>
Can take class, id
<div class="col-...">
<@cCol>
Use cols='12 col-md-X'
generic <div>
<@cBlock>
type='div' by default
<section>
<@cSection>
Dedicated macro. <@cBlock type='section'> also possible
<article>
<@cArticle>
Dedicated macro
<header>
<@cHeader>
Dedicated macro
<aside>
<@cBlock type='aside'>
No dedicated macro — use cBlock with type
<footer>
<@cBlock type='footer'>
No dedicated macro — use cBlock with type
<main>
<@cBlock type='main'>
No dedicated macro — use cBlock with type
Text and Titles
HTML
Macro FO
Notes
<h1> to <h6>
<@cTitle level=N>
N = 1 to 6
<p>
<@cText>
type='p' by default
<span>
<@cInline>
type='span' by default. Not self-closing — always </@cInline>
<em>, <strong>, <small>
<@cInline type='em'>, etc.
Via the type parameter
<time datetime="...">
<@cInline type='time' params='datetime="..."'>
No dedicated macro — pre-build the date with <#assign>
<i class="ti ti-xxx">
<@cIcon name='xxx' />
Prefer <@cIcon> — shortcut with automatic ti ti- prefix
Lists
HTML
Macro FO
Notes
<ul>
<@chList>
type='u' by default, type='o' for ordered
<ol>
<@chList type='o'>
<li>
<@chItem>
Components
HTML
Macro FO
Notes
<div class="alert ...">
<@cAlert>
Use type='warning', type='danger', etc.
<div class="card ...">
<@cCard>
Parameters: title, header, headerLevel, headerLabelClass, class, titleLevel, etc.
<div class="modal ...">
<@cModal>
<div class="accordion ...">
<@cAccordion>
<div class="progress">
<@cProgress>
Parameters: label, progressId, color, value, min, max, text
Links and Buttons
HTML
Macro FO
Notes
<a href="...">
<@cLink href='...' label='...'>
Standard link
<a class="btn ...">
<@cBtn href='...' class='...'>
Link styled as a button
<button>
<@cBtn>
type='submit' by default
inline SVG/icon inside a button
Use <@cIcon> nested inside <@cBtn>
nestedPos='before' (default) or 'after'
Images
HTML
Macro FO
Notes
<img>
<@cImg src='...' alt='...'>
class='img-fluid' by default
<figure> + <figcaption>
<@cFigure caption='...'> + <@cImg> nested
The macro handles the <figcaption> via the caption parameter
Forms
HTML
Macro FO
Notes
<form>
<@cForm>
method='post', action
<input>
<@cInput>
<input type="hidden">
<@cInput type='hidden' class='' />
Always add class=''
<input type="password">
<@cInput type='password'> or <@cInputPassword>
cInputPassword for the full version with toggle
<label>
<@cLabel>
Label + Input grouped
<@cField label='...' required=true>
Prefer cField, use required=true instead of appending * to the label
With <@cOption> nested. Supports errorMsg and helpMsg. Class: form-select (Bootstrap 5), do not use form-control
<textarea>
<@cTextArea>
<fieldset>
<@cFieldset>
<div class="input-group">
<@cInputGroup>
Can take class, size (lg or sm). The <@cBtn> go directly nested, no<@cInputGroupAddonText>
Tables
HTML
Macro FO
Notes
<table>
<@cTable>
<thead>
<@cThead>
<tbody>
<@cTbody>
<tr>
<@cTr>
<th>
<@cTh>
<td>
<@cTd>
cTable → chList + cCard (optional, on request)
A table listing entities can be replaced by a list of cards only if the user explicitly requests it. Do not apply it systematically during a template update.
<@cStepNext>: upcoming step, self-closing, no nested content.
<@cStepNext step='3' title='#i18n{...}' />
Never inline a FreeMarker condition in the title parameter of the cStep* macros — use an <#assign> variable defined inside <@cTpl> (just after line 1) and pass it without quotes:
Never use BO macros (admin/Tabler) in an FO (skin) template. BO macros such as <@messages>, <@aButton>, <@button>, <@box>, <@formGroup>, <@tform>, <@select>, <@option> are not available in the FO context
<@aButton href='...' size='sm'> → <@cBtn href='...' class='outline-secondary btn-sm'> (choose the color according to the context: outline-primary, outline-secondary, etc.)
<@button> → <@cBtn>
<@tform> → <@cForm>
<@formGroup> → <@cField> or <@cBlock>
<@select> / <@option> → <@cSelect> / <@cOption>
cFieldset - Replacing fieldset/legend
<fieldset> + <legend> → <@cFieldset legend='...'> — the macro handles the legend rendering
<#-- BEFORE -->
<fieldset>
<legend>My title</legend>
...content...
</fieldset>
<#-- AFTER -->
<@cFieldset legend='My title'>
...content...
</@cFieldset>
form-group → cRow/cCol
Replace <@cBlock class='form-group'> with <@cRow> / <@cCol> for form button groups
Add class='mt-3' on the <@cRow> for vertical spacing
<#-- BEFORE -->
<@cBlock class='form-group'>
<@cBtn .../>
</@cBlock>
<#-- AFTER -->
<@cRow class='mt-3'>
<@cCol>
<@cBtn .../>
</@cCol>
</@cRow>
style attribute on macros
Do not use style='...' directly as a macro parameter — it is not a valid parameter of <@cCol>, <@cTitle>, <@cTd>, etc.
Use params='style="..."' if absolutely necessary, or prefer a CSS class:
For alerts displaying a list of messages (several infos or errors), use a block <#assign> to concatenate the messages, then pass the result to the title parameter:
<#-- INCORRECT — nested content with <#list> -->
<@cAlert type='danger' id='messages_errors_div'>
<#list errors as error>
<@cIcon name='alert-circle' /> ${error.message}
</#list>
</@cAlert>
<#-- CORRECT — assign + title -->
<#assign errorMsg><#list errors as error>${error.message}</#list></#assign>
<@cAlert type='danger' id='messages_errors_div' title=errorMsg />
The <@cAlert> macro handles its own icon according to the type — no need to add <@cIcon> manually
cInline - Span / em / time / strong and other inlines
Not self-closing: always requires a closing tag </@cInline>, even when the content is empty
The label='' parameter is mandatory; the card content goes nested.
Empty lists filled by JS
For a <ul> that will be populated on the JS side (TOC, autocomplete, etc.), use <@chList> with an id and empty nested content:
<@chList id='bl-toc'></@chList>
The JS can then do document.getElementById('bl-toc') and appendChild(li) normally.
Dead / duplicated code
During a migration, always re-read the result to detect any buggy copy-paste (e.g. a duplicated <#assign breadcrumbItems...> in another container without use)
Remove commented-out HTML blocks (<!-- ... -->) that are not genuinely useful as documentation
Remove <!-- TOC -->, <!-- BODY --> etc. comments whose intent is obvious in the structured FreeMarker code
jQuery → Vanilla JS - Mandatory conversion
The jQuery library is no longer loaded by the theme. Any JavaScript using $(...), jQuery(...) or jQuery plugins must be systematically rewritten in vanilla JS when migrating a template — it is non-negotiable, otherwise the code breaks at runtime.
Standard mapping of the most common jQuery operations:
event.key (' ', 'Enter', 'Escape'...) or event.code
$(this) in handler
this (the handler receives this = the triggering element) or event.currentTarget
$el.animate({ scrollLeft: '+=305' }, 'slow')
el.scrollBy({ left: 305, behavior: 'smooth' })
$el.animate({ scrollTop: 0 }, 'slow')
window.scrollTo({ top: 0, behavior: 'smooth' })
$.ajax(...) / $.get(...) / $.post(...)
fetch(url, { method, headers, body }).then(r => r.json())
$(document).ready(fn)
document.addEventListener('DOMContentLoaded', fn) (already the standard practice)
$.trim(s)
s.trim()
$.each(arr, fn)
arr.forEach(fn)
Recurring patterns to factor out into helpers when used several times in the same <script>:
// Helper to toggle disabled (class + attribute)functionsetDisabled(btn, value) {
if (!btn) return;
if (value) {
btn.classList.add('disabled');
btn.setAttribute('disabled', 'disabled');
} else {
btn.classList.remove('disabled');
btn.removeAttribute('disabled');
}
}
Mandatory safeguards:
Always check the existence of the element after querySelector: if (!el) return; or if (el) { ... } — querySelector returns null if not found, el.classList.add(...) then crashes whereas $el.addClass(...) was silent on an empty collection.
Prefer event.key over event.which (deprecated) or event.keyCode (deprecated).
Catch dead jQuery code: some jQuery selectors are poorly written (e.g. $el.children('.a .b') which never matches — .children() filters direct children with a simple selector). When converting, flag the presumed intent to the user rather than literally translating a no-op.
cText - Correct usage
<@cText> renders a <p> tag — do not use it as a layout container (flex, grid, columns)
For layout wrappers with Bootstrap utility classes, use <@cBlock>, <@cRow> or <@cCol>:
Do not add JavaScript unless requested or required by a macro
Do not use deprecated macro parameters
Do not wrap a <@cAlert> in an unnecessary <@cBlock> or <@cCard>
Do not duplicate the btn btn- prefix in the class of <@cBtn>
Do not leave orphan <li> without a parent <@chList>
Do not wrap each <@chItem> in a <@cRow>/<@cCol> — list items go directly inside <@chList>
Do not leave raw HTML tags (<br>, <hr>, <b>, <i>, etc.) when a macro exists or when they are unnecessary — remove formatting <br>
Do not use <@cCol cols='xs-12'> — simply use <@cCol> (full-width column by default)
Do not use — replace with a normal space or remove if unnecessary
Do not use style='...' on macros — use class with Bootstrap utilities or params='style="..."' as a last resort
Do not mix BO and FO macros — check that all the macros used exist in the skin/FO context
Do not use > / < in FreeMarker conditions — use gt / lt
Do not self-close <@cInline> — always </@cInline>, even when the content is empty
Do not inline FreeMarker in the class parameter of a macro — pre-build the string with <#assign> (also applies to href, id, etc.)
Do not inline ?string('yyyy-MM-dd') directly in params='datetime="..."' — nested quotes break the FreeMarker parser. Pre-build with <#assign>.
Do not keep a separate <figcaption> — use the caption parameter of <@cFigure>
Do not use <@cBtn> for clickable cards — use <@cLink class='ma-card' label=''> when it is a clickable area not styled as a button
Do not keep duplicated/dead code during the migration — re-read the result to spot buggy copy-paste and unnecessary <!-- ... --> comments
NEVER keep jQuery in a migrated template ($(...), jQuery(...), .on(), .addClass(), .animate(), $(document).ready(), etc.) — the jQuery lib is no longer loaded by the theme, the code would crash at runtime. Always rewrite in vanilla JS (see the dedicated section)
