Dokumentatsioon

Mirage Templates praktiline süntaks küljenduse juhtimiseks

Mallikihi piir

Mirage on mõeldud HTML-i ja teksti esitamiseks. Selle kaudu saab sektsioone ümber paigutada, kaarte ja pealkirju muuta, dekoratiivseid konteinereid lisada, klasse juhtida ning ettevalmistatud loendeid ja lokaliseeritud silte kuvada. Mall ei tohi käivitada SQL-i, määrata õigusi, muuta andmeid ega asendada mooduli marsruudikontrolli. Kui vajalikku välja sisendkontekstis pole, ei saa seda ainult küljenduse muudatusega usaldusväärselt luua.

Avalikud mallid asuvad kaustas skins/<Layout>/<Skin>/<Module>/, haldusmallid kaustas adminskins/... ja moderaatorimallid kaustas moderatorskins/.... Enne muutmist määrake aktiivsed Layout ja Skin. Sama failinimi võib esineda mitmes puus ning mitteaktiivse koopia muutmine lehte ei muuda.

HTML-i jaoks põgenev väljund

Peamine ja turvaline väljundivorm on topeltlooksulud:

<h1>{{ Context.Table("page").Data("title") }}</h1>
<p>{{ Context.Table("page").Data("summary") }}</p>

Tekst põgenetakse HTML-i jaoks, mistõttu andmetes olevad märgid ei muutu siltideks ega atribuutideks. Kasutage seda vormi pealkirjade, nimede, atribuutides olevate URL-ide, siltide, otsinguteksti ja kõigi kasutaja sisestatud väärtuste jaoks.

Toorväljundit tähistab hüüumärk:

{{! Former.BuildHTML(Context.Table("form").Data("submit_ir")) }}

See on lubatud ainult allikale, mis juba vastutab turvalise HTML-i eest, näiteks Formeriga loodud elemendile, Echeloni tsoonile või eelnevalt serialiseeritud JSON-LD-le. Ärge asendage tavaväljundit raw-väljundiga selleks, et kasutajavälja „silt tööle hakkaks”. Nii muutuvad andmed aktiivseks märgenduseks.

Nimega Context-tabelid

Kasutage uutes mallides Context.Table. Üks leht võib saada tabelid meta, page, assets ja moodulitabelid eesliitega __. Põhikutsed on:

Context.HasTable("items") – tabeli olemasolu kontrollimine;
Context.Table("items").Data("title") – aktiivse rea välja lugemine;
RowCount() – ridade arvu saamine;
Rewind() – kursori algusesse viimine;
NextRow() – järgmisele reale liikumine.

Ühilduv süntaks Table.Data(...) jääb vanematesse ühe tabeliga mallidesse, kuid seda ei tohiks põhjuseta nimega kontekstiga segada.

Tingimused, väärtused ja kommentaarid

{% if Context.Table("page").Data("status") == "published" %}
  <span class="badge badge--live">{{ Boardwords("status_published") | default("Avaldatud") }}</span>
{% elif Context.Table("page").Data("status") == "draft" %}
  <span class="badge badge--draft">{{ Boardwords("status_draft") | default("Mustand") }}</span>
{% else %}
  <span class="badge">{{ Boardwords("status_unknown") | default("Tundmatu") }}</span>
{% endif %}

Lipud saabuvad sageli stringidena "1" ja "0", seega võrrelge neid selgesõnaliselt. Ajutise muutuja jaoks kasutatakse {% set name = value %} ning kommentaar kirjutatakse kujul {# selgitus #} ja seda HTML-i ei lisata.

Varuväärtuse jaoks sobivad kaks vormi:

{{ Context.Table("meta").Data("title") ?? "Pealkiri puudub" }}
{{ Boardwords("catalog_title") | default("Kataloog") }}

Ternaaravaldis sobib lühikese klassiväärtuse jaoks, kuid suured plokid on parem vormistada tavalise if-iga:

{{ Context.Table("page").Data("compact") == "1" ? "card--compact" : "card--wide" }}

Turvaline tsükkel üle ridade

Nimega tabel ei muutu automaatselt objektimassiiviks. Kasutage täielikku kursorimustrit:

{% if Context.Table("products").RowCount() > 0 %}
  {% set __ = Context.Table("products").Rewind() %}
  <div class="product-grid">
    {% for _ in range(0, Context.Table("products").RowCount(), 1) %}
      {% if Context.Table("products").NextRow() %}
        <article class="product-card{% if loop.even %} product-card--even{% endif %}">
          <h3>{{ Context.Table("products").Data("title") }}</h3>
          <p>{{ Context.Table("products").Data("summary") }}</p>
        </article>
      {% endif %}
    {% endfor %}
  </div>
{% else %}
  <p>{{ Boardwords("products_empty") | default("Praegu pole midagi") }}</p>
{% endif %}

Järjekord on kohustuslik: kontrollige ridu, käivitage Rewind(), läbige vahemik ja kutsuge välja NextRow() enne Data() lugemist. Tsüklis on saadaval loop.index, loop.first, loop.last, loop.odd ja loop.even.

Lokaliseerimine, vormid ja tsoonid

Staatilised kasutajasildid väljastage Boardwords abil koos arusaadava fallback-väärtusega. Nii säilib disaini skin-puude vahel kopeerimisel tõlgitavus. Kui vormiväli saabub kujul *_ir, ärge koostage input-elementi käsitsi:

<label>{{ Boardwords("profile_name") | default("Profiili nimi") }}</label>
{{! Former.BuildHTML(Context.Table("profile").Data("name_ir"), "class", "profile-form__input") }}

Mirage juhib konteinerit, ruudustikku ja klassi, Former aga HTML-juhtelementi. Ka Echelon Zone'i sisu väljastatakse raw-kujul ainult seetõttu, et tsoon on fragmendi usaldatud tootja; suvalisel tabeliväljal sellist staatust ei ole.

Muudatuse kontrollimine

Tehke aktiivses mallis kitsas muudatus ilma kogu shell'i kopeerimata.
Kontrollige lehte andmetega, tühja loendiga ja puuduvate valikuliste väljadega.
Kontrollige erimärke tekstis ja atribuutides.
Kontrollige kõiki saadaolevaid keeli ja Boardwordsi fallback-väärtusi.
Kontrollige desktop- ja mobile-vaadet ning haldusvormi puhul valideerimisvigu.
Veenduge, et raw-väljundit kasutatakse ainult usaldatud HTML-i tootjatele.

Kui mall vajab uusi õigusi, SQL-i või ärireeglit, peatage töö: ülesanne on väljunud Mirage'i piiridest. Õige laiendus valmistab andmed esmalt moodulis ette ning mall jääb prognoositavaks esitluskihiks.

Lehe koostamine ja dünaamilised fragmendid

Redigeerige ühist shell'i, menüüd ja rakendusmooduli sisu eraldi. Ärge kandke kogu karkassi ühe kaardi malli: see tekitab dubleerimist ja rikub skin'i vahetamise. Filtri, pager'i või vahekaardiga uuendatava fragmendi jaoks kasutage Mirage'iga kokkulepitud AJAX-keskkonda. Esmase kuva ja SEO jaoks olulise kanoonilise avaliku teksti jätke tavapärasesse leherenderdusse.

Kui mall kasutab callback-paketi lisanimiruumi, näiteks kuupäeva vormindamist, veenduge, et pakett on siht-runtime'is olemas. Selline callback on konkreetse malli sõltuvus. Lisage arusaadav fallback seal, kus disain seda lubab, ja ärge püüdke puuduvat callback'i keerukate stringavaldistega jäljendada.

Turvalise review praktika

Võrrelge enne ja pärast muudatust lõplikku HTML-i, mitte ainult `.mirage` lähtekoodi. Kontrollige siltide tasakaalu, id-de unikaalsust, label'ite ligipääsetavust, linkide kehtivust ja pesastatud interaktiivsete elementide puudumist. Loendite puhul testige üht ja mitut rida: kursorivead pole ainsa kirje korral sageli nähtavad. Malli skin-puude vahel teisaldamisel kontrollige tabeli- ja väljanimesid uuesti, sest visuaalselt sarnased moodulid ei pea saama sama konteksti.