Xporter-syntaxis: wat werkt
Een eerlijk overzicht van hoe sjabloonsyntaxis in Xporter-stijl wordt behandeld wanneer u een Word-document uploadt in de Word-sjabloonmodus. Het weerspiegelt de migratiescanner die bij elke upload draait — dezelfde classificaties die u in het compatibiliteitsrapport van de editor ziet.
De eerlijke belofte
Exportelier is niet Xporter-compatibel, is geen vervanger van Xporter en voert Xporter-sjablonen niet uit. Wat het wel doet, is u helpen migreren: bij het uploaden herkent de scanner gangbare syntaxis in Xporter-stijl en vertelt u per constructie of die al werkt, automatisch te converteren is, handmatig herschreven moet worden of bewust buiten bereik valt.
Twee harde garanties:
- Vreemde syntaxis wordt alleen herkend, nooit uitgevoerd. De scanner leest de vorm van een constructie —
#{for …},${dateformat(…)}— en niets uit een geüpload sjabloon wordt ooit als code geëvalueerd. - Er wordt geen code van derden gekopieerd. De detectiepatronen en aliassuggesties zijn door Exportelier zelf geschreven op basis van publiek gedocumenteerde syntaxisvormen.
Elke bevinding valt in een van vier klassen.
1. Werkt ongewijzigd
Gebruikt uw sjabloon al de canonieke syntaxis van Exportelier, dan werkt het gewoon. Dat levert een informatieve notitie op, geen waarschuwing.
| Constructie | Voorbeeld |
|---|---|
| Waardetoken | ${issue.key} |
| Lus | ${#each issue.subtasks as sub}…${/each} |
| Voorwaarde | ${#if issue.assignee}…${#else}…${/if} |
2. Automatisch converteerbaar
Gangbare Xporter-syntaxis met een veilig een-op-een-equivalent. De editor toont een waarschuwing en biedt een kopieerbare vervanging.
| Xporter-constructie | Equivalent in Exportelier | Opmerkingen |
|---|---|---|
${Key}, ${Summary}, ${Status}, … | ${issue.key}, ${issue.summary}, ${issue.status}, … | Aliassen voor scalaire velden. |
${Assignee.displayName} | ${issue.assignee.displayName} | Bekende hoofdalias; de rest van het pad blijft behouden. |
#{for comments} | ${#each comments as c} | Begin van een lus. |
#{if(Assignee)} | ${#if issue.assignee} | Eenvoudige aanwezigheidscontrole. |
#{else} | ${#else} | Else-markering. |
Herkende scalaire aliassen (16): Key, Summary, Description, Status, Priority, Resolution, Assignee, Reporter, Creator, Created, Updated, DueDate, IssueType, Type, Project, Labels.
Herkende collectie-aliassen (5): Comments, Attachments, Subtasks, Links, Worklogs.
Een suggestie heeft de juiste vorm, maar het doel moet nog steeds een echte koppeling uit de tokenreferentie zijn. Sommige aliassen vragen om handmatige aanpassing:
- Niet koppelbaar:
Creator→issue.creator,Resolution→issue.resolution,Project→issue.project,IssueType/Type→issue.issuetype. Geen daarvan is een tier-A-koppeling. - Verschil in hoofdletters:
DueDatewordt voorgesteld alsissue.duedate; de koppeling isissue.dueDate. - Verkeerd soort:
Labelswordt als scalair voorgesteld, maarissue.labelsis een collectie — gebruik${#each issue.labels as l}…. - Issuekoppelingen:
Linkswordt voorgesteld alslinks, maar de echte koppeling isissue.issueLinks.
3. Niet ondersteund maar verklaarbaar
Geen schone een-op-een-vertaling, maar wel een duidelijke manier om dezelfde bedoeling uit te drukken. De editor legt de herschrijving uit; dit is een waarschuwing, geen blokkade.
| Xporter-constructie | Waarom | Wat u in plaats daarvan doet |
|---|---|---|
${Comments[0].Body} | Paden kennen geen indexering met blokhaken. | Itereer: ${#each comments as c}${c.body}${/each}. |
#{end} | Eén generieke afsluiting. | Gebruik de bijbehorende afsluiting: ${/each} of ${/if}. |
#{if(votes > 0)} | Voorwaarden toetsen alleen de aanwezigheid van één pad; er zijn geen operatoren. | Toets aanwezigheid: ${#if issue.votes}. |
#{elseif(…)} | elseif bestaat niet. | Nest de voorwaarden. |
Elke andere #{…}-directive | Wordt niet herkend. | Vervang door ${…}-syntaxis. |
Niet-sluitende ${#each}/${/if}, verkeerd pad, niet-afgesloten ${ | Wordt door de parser opgemerkt. | Corrigeer het token; het rapport noemt de exacte positie. |
4. Onveilig of niet ondersteund
Bewust buiten bereik: ondersteuning zou het sjabloon in een scripting-engine veranderen, en dat is Exportelier met opzet niet. De editor toont een fout en de constructie wordt nooit uitgevoerd.
| Xporter-constructie | Status | Wat u in plaats daarvan doet |
|---|---|---|
${dateformat("yyyy-MM-dd")} en andere functie- of filteraanroepen | Functies worden nooit uitgevoerd. | Gebruik de vaste set formatters, bijv. ${issue.created | date("yyyy-MM-dd")}. |
${jql("project = ABC")} / #{JQL: …} | JQL wordt nooit vanuit een sjabloon uitgevoerd. | Kies de issues via de exportcontext. |
| JavaScript, Groovy, Velocity, FreeMarker, JS-filters | Het is geen scripttaal. | Druk de lay-out uit met tokens, lussen, voorwaarden en formatters. |
set-variabelen, break/continue, rekenkunde, expressies | Het is geen scripttaal. | Bouw het om met de ondersteunde constructies. |
Wat de validator met deze bevindingen doet
Bij het uploaden wordt elke bevinding een diagnose met een ernstniveau:
- info — werkt ongewijzigd, geen actie nodig.
- warning — automatisch converteerbaar of verklaarbaar; de export gaat door, maar een waarde kan leeg blijven als de koppeling onbekend is.
- error — onveilige of niet-ondersteunde syntaxis, een onveilig pad of een parseerfout.
Constructies die Word bewaart maar niet invult — tekstvakken, voetnoten, inhoudsbesturingselementen, veldcodes, opmerkingen en bijgehouden wijzigingen — worden apart gemeld als unsupported-location-waarschuwingen. Het document behoudt ze, maar de tokens erbinnen worden niet ingevuld.