T-SOFT/Tema Geliştirme/Snippet

Snippet

Snippet'lar, birden çok yerde kullanılan küçük Twig parçalarıdır. Örneğin bir ürün kartı (product-card) ürün listesi, öne çıkan ürünler ve ilgili ürünler section'larında tekrar kullanılabilir.

snippets/product-card.twig

<a href="{{ product.url }}"
   class="block group">
  <img src="{{ product.image }}"
       alt="{{ product.title }}"
       class="w-full aspect-square object-cover rounded"
       loading="lazy">

  <h3 class="mt-3 text-sm font-medium text-body group-hover:text-primary">
    {{ product.title }}
  </h3>

  <span class="block mt-1 font-semibold text-primary">
    {{ product.price|money }}
  </span>
</a>

Çağıran taraf:

{% for product in section.products %}
  {{ snippet('product-card', { product: product }) }}
{% endfor %}

`snippet()` fonksiyonu

Snippet'ları snippet() global fonksiyonu ile çağırırsınız — Twig'in {% raw %}{% include %}{% endraw %} etiketini kullanmazsınız.

{# Parametresiz — snippet, çağıran şablonun değişkenlerini görür #}
{{ snippet('_cookie-law') }}
{{ snippet('social-login') }}

{# Loop içinde — snippet aynı kapsamdaki P değişkenine erişir #}
{% for key, P in PRODUCTS %}
  {{ snippet('product-list.product-card.default') }}
{% endfor %}

{# Parametreli — ikinci argüman bir nesne (hash), ek değişken geçirir #}
{{ snippet('product-card', { product: P }) }}
{{ snippet('skeleton-loader', { type: 'comments' }) }}
{{ snippet('skeleton-loader', { type: 'installment' }) }}

Snippet, çağıran şablonun değişkenlerine örtük olarak erişebilir. Yukarıdaki for döngüsünde P snippet'a açıkça geçirilmez, ancak snippet P değerine erişebilir. Bu kısa kullanım sağlar; taşınabilirlik gereken durumlarda kritik parametreleri açıkça geçirin.

Bir snippet'a hangi parametreler ve global'ler geldiğini görmek içinT-Soft Theme Devtools Chrome eklentisi → Blok Değişkenleri sekmesini açın. Snippet aktifken o bloğa enjekte edilen tüm değişkenler canlı olarak listelenir.

Snippet içinde parametreler isimlerine göre erişilir:

snippets/skeleton-loader.twig

{% if type == 'comments' %}
  <div class="animate-pulse h-24 bg-form"></div>
{% elseif type == 'installment' %}
  <div class="animate-pulse h-12 bg-form"></div>
{% else %}
  <div class="animate-pulse h-8 bg-form"></div>
{% endif %}

Klasör hiyerarşisi ve nokta notasyonu

Snippet'lar gruplandığında nokta notasyonu ile çağrılır. Her nokta bir klasör seviyesine karşılık gelir.

snippets/

snippets/
├── product-card.twig
├── _cookie-law.twig
├── social-login.twig
└── product-detail/
    ├── variant-1/
    │   ├── default.twig
    │   └── select.twig
    ├── variant-2/
    │   ├── default.twig
    │   └── select.twig
    └── related/
        └── default.twig

Çağrı karşılıkları:

Çağrı	Dosya
`snippet('product-card')`	`snippets/product-card.twig`
`snippet('_cookie-law')`	`snippets/_cookie-law.twig`
`snippet('product-detail.variant-1.select')`	`snippets/product-detail/variant-1/select.twig`
`snippet('product-detail.related.default')`	`snippets/product-detail/related/default.twig`

Gruplama mantıklı olduğunda klasöre alın.product-detail altında 8–10 varyant snippet'i varsa, hepsini düz dizinde tutmak yerine alt klasörlere bölün. Hem aramada kolaylık olur, hem de IDE klasörlemesi çalışır.

Alt çizgi (`_`) konvansiyonu

Alt çizgi ile başlayan snippet'lar dahili / private olarak işaretlenir — yani başka bir snippet veya section dışından doğrudan çağrılmaması beklenir:

{{ snippet('_influencer-bar') }}
{{ snippet('_web-notification') }}
{{ snippet('_cookie-law') }}

Bu teknik bir kısıt değil, adlandırma anlaşmasıdır. Amaç, snippet'ın doğrudan sayfadan değil bağlı olduğu üst bileşen üzerinden kullanılacağını belirtmektir.

Snippet'tan snippet çağırma

Snippet'lar birbirini çağırabilir. product-card, içinde price-badge snippet'ını çağırabilir:

snippets/product-card.twig

<a href="{{ product.url }}">
  <img src="{{ product.image }}" alt="{{ product.title }}">
  <h3>{{ product.title }}</h3>
  {{ snippet('price-badge', { price: product.price, compare: product.compare_at_price }) }}
</a>

Döngüsel çağrıdan kaçının.a snippet'i b'yi, b de a'yı çağırıyorsa motor sonsuz döngüye girer. Snippet bağımlılığını tek yönlü tutun.

Section mi, snippet mı?

Soru	Section	Snippet
Panelden eklenebilir mi?	✅ Evet	❌ Hayır
Ayarları var mı?	✅ Var	❌ Yok (parametre alır)
Mağaza sahibi sırasını değiştirebilir mi?	✅ Evet	❌ Hayır
Bir sayfaya bağımsız eklenir mi?	✅ Evet	❌ Sadece içeride çağrılır
Genellikle ne kadar büyük?	Tam bir bölüm	Küçük bir parça

Genel kural: Mağaza sahibinin panelden ekleyip kaldırması gereken yapı section olmalıdır. Birden fazla yerde tekrar kullanılan küçük Twig parçaları için snippet kullanın.

Bir snippet'ı AJAX ile sonradan yüklemek içinsnippet_uri() fonksiyonuyla URI üretip JS tarafında çağırabilirsiniz — imza ve örnekler için bkz. Twig Fonksiyonları. Asorti tablosu ve ürün görsel slider'ı gibi kopyala-kullan örnekler için bkz. Pratik Çözümler.

En iyi uygulamalar

Snippet kendine yetsin

Tüm verilerini parametre olarak alsın. Global değişkenlerden olabildiğince az faydalansın.

Parametre varsayılanı verin

{{ size|default('md') }} — eksik parametrede hata vermesin.

`_` ile özelini işaretle

Bir üst bileşene bağlı snippet'i _isim ile adlandırın.

Adı sayfa diliyle ver

product-card, price-badge — sade ve anlaşılır. card2 veya helper-1 değil.

Sıradaki adım

Locale & Çeviriler

Snippet'larda metin yerelleştirme — {{ t.x }} ve placeholder'lar.

Asset'ler

CSS, JS ve görsel organizasyonu.