Vitrin Blokları

Uygulamanız mağazanın tema editörüne kendi bloklarını ekleyebilir. Mağaza sahibi bu blokları Uygulamalar grubunda görür ve sayfasında istediği yere yerleştirir. Bloğun başlığını, rengini ve diğer ayarlarını editörden değiştirir.

Kargo takip kutusu, ürün sayfasında taksit tablosu, sayaç ya da yorum özeti bu yolla eklenir.

Bloğun HTML'i mağazada sunucu tarafında çizilir. Sayfa açılırken içerik hazırdır ve Tailwind sınıfları mağazanın stil dosyasına girer. Etkileşim (veri çekme, tıklama) uygulamanızın embed script'inden gelir.

Paket yapısı

Bloklar, vitrin eklentisi paketinizin bir modülüdür. Paket yalnız bloklardan da oluşabilir. Embed script'i gerekmiyorsa eklemeyin.

package.json
modules/
  block/
    kargo-takip.twig
embed/
  v1/
    content.js        # isteğe bağlı: bloğa davranış ekler

{
  "name": "Kargo Takip",
  "prefix": "app.kargo-takip",
  "version": "1.0.0",
  "modules": [
    {
      "type": "block",
      "data": [
        {
          "handle": "kargo-takip",
          "name": { "tr": "Kargo takip", "en": "Shipment tracking" },
          "settings": [
            { "key": "title", "type": "text", "label": { "tr": "Başlık", "en": "Title" }, "default": "Kargom nerede?", "translatable": true },
            { "key": "layout", "type": "select", "label": "Görünüm", "default": "card",
              "options": [{ "label": "Kart", "value": "card" }, { "label": "Satır", "value": "inline" }] },
            { "key": "show_logo", "type": "checkbox", "label": "Kargo logosunu göster", "default": true },
            { "key": "accent", "type": "color", "label": "Vurgu rengi", "default": "#2563eb" }
          ]
        }
      ]
    },
    { "type": "embed", "data": [{ "location": "3", "script": "content.js" }] }
  ]
}

Bir pakette en fazla 10 blok olur, her şablon en fazla 32 KB'tır.

Şablon

Şablon Twig'dir ama mağazanın tema Twig'inden ayrı, dar bir ortamda çizilir. Ürün, sepet, çerez ya da başka dosya okunamaz. Şablon yalnız aşağıdaki değişkenleri görür:

<section class="rounded-lg border p-4 md:p-6">
  {% if block.settings.show_logo %}<span class="mb-2 block text-xs text-gray-500">T-Soft Kargo</span>{% endif %}
  <h2 class="text-lg font-semibold" style="color: {{ block.settings.accent|default('#2563eb') }}">
    {{ block.settings.title|default('Kargom nerede?') }}
  </h2>
  <div class="mt-3 flex gap-2" data-role="lookup">
    <input name="code" class="flex-1 rounded border px-3 py-2" placeholder="Takip numarası">
    <button type="button" class="rounded bg-gray-900 px-4 py-2 text-white">Sorgula</button>
  </div>
  <div data-role="result" class="mt-3 hidden"></div>
</section>

İzinli etiketler: if, for, set, verbatim.

İzinli filtreler: escape/e, default, length, lower, upper, trim, join, first, last, slice, date, number_format, url_encode, json_encode.

Değerler otomatik olarak HTML'e kaçışlanır. Fonksiyon, metot çağrısı, include, macro, raw ve .. aralık operatörü kullanılamaz.

Tailwind

Şablondaki Tailwind sınıfları, uygulama kurulduğunda ya da güncellendiğinde mağazanın stil dosyasına derlenir. Sınıfları script'le sonradan eklerseniz derlemeye girmezler. Görünüm şablonda, davranış script'te olsun.

Davranış: embed script'i

Mağaza her bloğu şu kabın içine koyar:

<div data-app-block="app.kargo-takip/kargo-takip" data-app-block-id="812" data-settings='{"title":"Kargom nerede?","layout":"card",…}'>
  …şablonunuzun çıktısı…
</div>

Embed script'iniz bloklarını bu öznitelikle bulur:

document.querySelectorAll('[data-app-block^="app.kargo-takip/"]').forEach((root) => {
  const settings = JSON.parse(root.dataset.settings || '{}');
  root.querySelector('[data-role="lookup"] button').addEventListener('click', async (event) => {
    const code = root.querySelector('input[name="code"]').value;
    const result = root.querySelector('[data-role="result"]');
    result.textContent = (await lookup(code, settings)).status;
    result.classList.remove('hidden');
  });
});

Kurulum, güncelleme, kaldırma

• Kurulum: Bloklar tüm temaların editöründe görünür. Mağaza sahibi yerleştirene kadar vitrinde hiçbir şey değişmez.
• Güncelleme: Onaylanan yeni sürüm şablonu ve ayar şemasını yeniler. Mağazanın girdiği değerler korunur; kaldırdığınız bir ayarın değeri silinir.
• Kaldırma: Uygulama kaldırılınca bloklar ve tüm yerleşimleri silinir.

Bir bloğu paketten çıkarmak, onu yerleştiren mağazaların sayfalarından da kaldırır. Bu yüzden blok silen sürüm yeni bir ana sürüm (ör. 2.0.0) olmalıdır.

İnceleme

Herkese açık uygulamaların her sürümü T-Soft incelemesinden geçer. İnceleme ekranında bloklarınız, ayarları ve şablon dosyaları görünür. Geliştirme mağazanızda sürümü onaydan önce deneyebilirsiniz.