Hyvä alt temasını (child theme) doğru şekilde oluşturmak

Neredeyse her Hyvä mağazası aynı kararla başlar: varsayılan temayı doğrudan değiştirmek mi, yoksa üzerine bir alt tema (child theme) oluşturmak mı? Doğru yanıt her zaman alt temadır. Alt temayı nasıl kurduğunuz ise Hyvä güncellemelerinin bir öğleden sonra mı yoksa bir hafta mı süreceğini belirler.

Bu rehberde müşteri mağazaları ve kendi demo mağazamız için Hyvä alt temalarını nasıl kurduğumuzu anlatıyoruz. Gereken dosyaları, neleri geçersiz kılmanız ve nelere dokunmamanız gerektiğini ve bize başvuran mağazalarda en sık gördüğümüz hataları ele alıyoruz. İlgili hizmetimiz: Hyvä projesi.

Neden kopya değil de alt tema?

Hyvä varsayılan temasını bir Composer paketi olarak sunar. Hyvä bir düzeltme ya da iyileştirme yayınladığında, Composer bu paketi vendor klasöründe günceller.

Bu dosyaları doğrudan düzenlerseniz, değişiklikleriniz bir sonraki güncellemede kaybolur. Temanın tamamını kendi klasörünüze kopyalarsanız değişikliklerinizi korursunuz; ancak artık hiçbir şey orijinalden türemediği için gelecekteki tüm iyileştirmeleri kaçırırsınız.

Alt tema (child theme) bu ikisinin arasında yer alır. Magento’nun tema fallback mekanizması önce sizin temanıza bakar; sizin değiştirmediğiniz her şey için ana temaya döner. Farklılıklarınız sizde kalır, geri kalanını Hyvä yönetmeye devam eder.

• Üst temadaki güncellemeler mağazanıza otomatik olarak ulaşır.
• Farklarınız (diff) küçük kalır, böylece bir güncellemeyi incelemek hızlı olur.
• Geliştiriciler neyin özel, neyin standart olduğunu bir bakışta görebilir.

Gereken minimum dosyalar

Hyvä alt teması sıradan bir Magento 2 temasıdır ve app/design/frontend/Vendor/theme klasöründe yer alır; kaydı için iki küçük dosya gerekir.

İlki theme.xml; üst temayı (parent) belirtir:

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Vendor Default</title>
    <parent>Hyva/default</parent>
</theme>

İkincisi registration.php:

<?php
use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::THEME,
    'frontend/Vendor/default',
    __DIR__
);

Ardından web/tailwind klasörü gelir. Hyvä belgeleri bu klasörü ana temadan kopyalamanızı söyler, çünkü her tema kendi stil dosyasını derler. Bu klasörde Tailwind yapılandırması, kaynak CSS ve package.json ile derleme komutları gelir.

Bundan sonra şu komutu çalıştırın: bin/magento setup:upgrade, ardından temayı Content > Design > Configuration altında mağaza görünümünüze atayın ve CSS'i bir kez derleyin. Artık Hyvä default ile birebir aynı görünen, çalışan bir alt temanız var.

Mümkün olduğunca az şeyi geçersiz kılın

En sık gördüğümüz sorun, üst temanın yarısını içeren bir alt temadır. Birinin header'da tek bir satırı değiştirmesi gerekmiş ve bunun için Magento_Theme şablon klasörünün tamamını kopyalamıştır. İki yıl sonra bu dosyalardan hangilerinin gerçekten değiştirildiğini kimse bilmez.

Kuralımız basit: geçersiz kılınan bir şablon, kopyalanan bir dosya demektir. Bir şablonu kopyalamadan önce daha küçük bir değişikliğin yetip yetmeyeceğine bakarız.

1. Önce layout XML. Blokları taşımak, kaldırmak ya da eklemek bir şablon değişikliği değil, layout değişikliğidir. Temanızdaki bir default.xml ya da sayfaya özel bir layout dosyası, bunların çoğunu hiçbir .phtml dosyasına dokunmadan yapabilir.
2. Sonra Tailwind sınıfları. Görsel değişikliklerin çoğu yalnızca farklı renk, boşluk ya da yazı tipinden ibarettir. Bunların yeri kopyalanmış şablonlar değil, Tailwind yapılandırmasıdır.
3. En son şablonu geçersiz kılmak. HTML yapısının kendisi değişmek zorundaysa, yalnızca o şablonu temanızda aynı yola kopyalayın ve orada değiştirin.

Bir şablonu kopyaladığımızda en üstüne neyin neden değiştiğini anlatan kısa bir yorum ekliyoruz. On saniyenizi alır, ama bir sonraki güncellemede sizi çok fazla tahminden kurtarır.

Tailwind'in üst temayı görmeye devam etmesini sağlayın

Tailwind yalnızca kaynak dosyalarınızda bulduğu sınıflar için CSS üretir. Hyvä stil dosyalarının küçük olmasının nedeni budur: kullanılmayan yardımcı sınıflar derlemeye hiç girmez.

Madalyonun öbür yüzü şu: Tailwind'in mağazanızın kullandığı her şablonu taraması gerekir. Buna alt temanızdaki şablonlar da, vendor klasöründeki üst temadan sunulmaya devam eden şablonlar da dahildir. Hyvä'dan kopyaladığınız Tailwind yapılandırması zaten üst temayı gösterir; düzenlerken bu yolu korumalısınız.

Hyvä uyumlu modüller de kendi şablonlarını ve Tailwind kaynaklarını getirebilir. Hyvä bunun için bir komut sunar: bin/magento hyva:config:generate; bu komut, derlemenin dikkate alacağı modül yollarının listesini oluşturur. Hyvä uyumlu bir modül eklediğinizde ya da kaldırdığınızda bu komutu çalıştırın.

Bir sınıf geliştirme ortamında çalışıp canlı ortamda kayboluyorsa, nedeni genellikle eksik bir içerik yoludur. Derleme sürecinin tamamını şu yazımızda anlatıyoruz: Tailwind tasarım token'ları ve derleme süreci.

Çeviriler, dosyalar ve tema ayarları

Alt temaya ait olan ve kolayca unutulan birkaç şey daha var.

• Çeviriler. Tema düzeyindeki metinler, temanızın içindeki i18n/de_DE.csv ve benzeri dosyalara yazılır. Mağaza görünümüne özel ifadeler, çok dilli demo mağazamızda karşılaştığımız tuzaklardan biriydi; bu yüzden yalnızca varsayılan görünümü değil, her mağaza görünümünü test edin.
• Görseller ve yazı tipleri. Ana sayfa kutucukları gibi tema görselleri, temanın web klasöründe yer alır. Demo mağazamızda görseller WebP formatında, 720 piksel genişliğinde ve yaklaşık 72 kalite ayarıyla sıkıştırılmış.
• Ekibinizin değiştirmek isteyebileceği renkler. Header ve marka renklerini Stores > Configuration altında sunuyoruz; böylece pazarlama ekibi bunları geliştiriciye ihtiyaç duymadan değiştirebilir. Tailwind token'ları, dağıtım sırasında yapılandırma ve tema dosyalarından yeniden oluşturulur.

Yazı tipleri için kısa bir not: Tek bir yazı tipi ailesini az sayıda kalınlıkla kendi sunucunuzda barındırmak, genellikle üçüncü taraf bir servisten birkaç aile yüklemekten daha hafiftir.

CSS'i her dağıtımda derleyin

Derlenmiş stil dosyası bir derleme çıktısıdır. Elle düzenlenmemeli ve birinin dizüstü bilgisayarında derleme yaptıktan sonra commit edilmemeli; dağıtım sırasında oluşturulmalıdır.

Tipik bir dağıtım adımı şöyle görünür:

bin/magento hyva:config:generate
npm --prefix app/design/frontend/Vendor/default/web/tailwind ci
npm --prefix app/design/frontend/Vendor/default/web/tailwind run build-prod
bin/magento setup:static-content:deploy -f en_GB de_DE

Derleme komutunun tam adı Hyvä sürümünüze bağlıdır; bu yüzden temanızdaki package.json dosyasını kontrol edin. Kendi altyapımızda Magento'yu canlı modda ve statik içerik dağıtımıyla (static content deploy) çalıştırıyoruz; bu yüzden CSS derlemesi her zaman statik içerik oluşturulmadan önce çalışır.

En sık düzelttiğimiz hatalar

Mevcut bir Hyvä mağazasını incelediğimizde en sık karşılaştığımız sorunlar bunlar.

Hız açısından en önemlisi üçüncü satır. Luma JavaScript'ini yükleyen tek bir eski eklenti, Hyvä'nın kazandırdıklarının büyük kısmını geri alabilir. Bu yüzden geçişten önce tüm eklentileri inceliyoruz.

SSS

Birden fazla alt temam olabilir mi?

Evet. Magento tema zincirlerini destekler; ortak çalışmalar için temel bir alt temanız, onun üzerinde de her marka ya da mağaza görünümü için ikinci bir temanız olabilir. Zinciri kısa tutun, çünkü her seviye hata ayıklamayı biraz daha zorlaştırır.

Hyvä default'tan mı, yoksa Hyvä UI'dan mı başlamalıyım?

Üst tema her zaman Hyvä default'tur. Hyvä UI ise ihtiyaç duydukça temanıza kopyaladığınız hazır bileşenlerden oluşan bir kütüphanedir. İki yaklaşım da aynı noktaya varır: kendi şablonlarınızı içeren, Hyva/default'tan türetilmiş bir alt tema.

Yalnızca renkleri değiştiriyorsam da alt temaya ihtiyacım var mı?

Evet. Küçük değişikliklerin de güncellemelerden etkilenmeyecek bir yerde durması gerekir. Şablon içermeyen, yalnızca Tailwind yapılandırmasından oluşan bir alt tema tamamen geçerlidir ve bakımı en kolay olan türdür.

Güncellemesi kolay kalan bir Hyvä teması mı istiyorsunuz? Nasıl çalıştığımızı görmek için şu sayfaya göz atın: Hyvä tema geliştirme sayfası, ya da bize ulaşın ; mağazanızı birlikte konuşalım.