# Text & Image Content Block

Metin ve görsel kombinasyonları için esnek ve çok yönlü içerik bileşeni.

## 📍 Konum

```
packages/my_site_package/ContentBlocks/ContentElements/text-image/
```

## 🎯 Genel Bakış

Text & Image bileşeni, metin içeriğini görselle birleştiren, farklı layout seçenekleriyle esnek kullanım sunan bir içerik bileşenidir. Blog yazıları, ürün tanıtımları, hizmet açıklamaları ve daha birçok alanda kullanılabilir.

## ✨ Özellikler

- ✅ Esnek görsel pozisyonu (üst, alt, sol, sağ)
- ✅ Ayarlanabilir görsel genişliği
- ✅ Çoklu görsel desteği
- ✅ Header layout seçenekleri (H1-H5)
- ✅ Zengin metin düzenleyici
- ✅ İsteğe bağlı link desteği
- ✅ Görsel galeri desteği
- ✅ Responsive tasarım
- ✅ Backend preview

## 📋 Alan Referansı

### 1. Header (Başlık)

**Tip**: Text (Mevcut Alan)  
**Zorunlu**: Hayır  
**Maksimum Karakter**: 255

Bölüm başlığı.

**Kullanım Örnekleri**:

```
Yeni Ürünümüz
Hizmetlerimiz
Müşteri Hikayeleri
Ekibimiz Hakkında
```

**Fluid Template**:

```html
<f:if condition="{data.header}">
  <f:render section="Header" arguments="{_all}" />
</f:if>
```

---

### 2. Header Layout

**Tip**: Select (Mevcut Alan)  
**Zorunlu**: Hayır  
**Varsayılan**: 2 (H2)

Başlık HTML etiketi seçimi.

**Seçenekler**:

| Değer | HTML Etiketi | Kullanım             |
| ----- | ------------ | -------------------- |
| 0     | Default (H2) | Standart kullanım    |
| 1     | H1           | Sayfa ana başlığı    |
| 2     | H2           | Bölüm başlıkları     |
| 3     | H3           | Alt bölüm başlıkları |
| 4     | H4           | Küçük başlıklar      |
| 5     | H5           | En küçük başlıklar   |

**SEO Notları**:

- Sayfa başına sadece bir H1 kullanın
- Başlık hiyerarşisine dikkat edin (H2 → H3 → H4)
- İçeriğe uygun başlık seviyesi seçin

**Fluid Template**:

```html
<f:section name="Header">
  <f:switch expression="{data.header_layout}">
    <f:case value="1"><h1>{data.header}</h1></f:case>
    <f:case value="2"><h2>{data.header}</h2></f:case>
    <f:case value="3"><h3>{data.header}</h3></f:case>
    <f:case value="4"><h4>{data.header}</h4></f:case>
    <f:case value="5"><h5>{data.header}</h5></f:case>
    <f:defaultCase><h2>{data.header}</h2></f:defaultCase>
  </f:switch>
</f:section>
```

---

### 3. Bodytext (İçerik Metni)

**Tip**: Textarea (Mevcut Alan)  
**Zorunlu**: Hayır  
**RichText**: Aktif

Ana içerik metni. HTML formatlamayı destekler.

**RichText Editor Özellikleri**:

- **Bold**: Kalın metin
- **Italic**: İtalik metin
- **Underline**: Altı çizili metin
- **Lists**: Sıralı/sırasız listeler
- **Links**: Bağlantılar
- **Headings**: Alt başlıklar
- **Tables**: Tablolar

**Kullanım Örnekleri**:

```html
<!-- Basit paragraf -->
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>

<!-- Listeler -->
<ul>
  <li>Özellik 1</li>
  <li>Özellik 2</li>
  <li>Özellik 3</li>
</ul>

<!-- Formatlı metin -->
<p>
  Şirketimiz <strong>2010</strong> yılında kurulmuştur ve
  <em>1000'den fazla</em> projeyi başarıyla tamamlamıştır.
</p>

<!-- Bağlantılar -->
<p>Daha fazla bilgi için <a href="/iletisim">iletişime geçin</a>.</p>
```

**Fluid Template**:

```html
<f:if condition="{data.bodytext}">
  <div class="text-image__description">
    <f:format.html>{data.bodytext}</f:format.html>
  </div>
</f:if>
```

**CSS Özellikleri**:

```css
.text-image__description {
  line-height: 1.6;
}
```

---

### 4. Image (Görseller)

**Tip**: File (Mevcut Alan)  
**Zorunlu**: Hayır  
**Maksimum**: Sınırsız  
**İzin Verilen Tipler**: Tüm görsel formatları

Birden fazla görsel yüklenebilir.

**Görsel Meta Verileri**:

- **Alternative Text**: SEO ve erişilebilirlik için
- **Title**: Hover tooltip
- **Description**: Görsel açıklaması (caption olarak gösterilir)
- **Link**: Görsele tıklandığında açılacak link

**Fluid Template**:

```html
<f:if condition="{data.image}">
  <div class="text-image__images">
    <div class="text-image__image-gallery">
      <f:for each="{data.image}" as="image">
        <div class="text-image__image-item">
          <f:image
            image="{image}"
            alt="{image.alternative}"
            title="{image.title}"
            width="800"
          />
          <f:if condition="{image.description}">
            <div class="text-image__image-caption">{image.description}</div>
          </f:if>
        </div>
      </f:for>
    </div>
  </div>
</f:if>
```

**CSS - Görsel Galerisi**:

```css
.text-image__image-gallery {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
  gap: 1rem;
}
```

**Önerilen Boyutlar**:

- Tek görsel: 800-1200px genişlik
- Galeri görselleri: 400-600px genişlik
- Dosya boyutu: Max 500KB (optimize edilmiş)

---

### 5. Image Position

**Tip**: Select (Single)  
**Zorunlu**: Hayır  
**Varsayılan**: right

Görselin metin içeriğine göre konumu.

**Seçenekler**:

| Değer   | Etiket        | CSS Class           | Layout     | Kullanım     |
| ------- | ------------- | ------------------- | ---------- | ------------ |
| `above` | Above text    | `text-image--above` | Vertical   | Görsel üstte |
| `below` | Below text    | `text-image--below` | Vertical   | Görsel altta |
| `left`  | Left of text  | `text-image--left`  | Horizontal | Görsel solda |
| `right` | Right of text | `text-image--right` | Horizontal | Görsel sağda |

**Layout Tipleri**:

**Vertical Layout (above/below)**:

```
┌─────────────────────┐
│                     │
│      Görsel         │
│                     │
├─────────────────────┤
│                     │
│      Metin          │
│                     │
└─────────────────────┘
```

**Horizontal Layout (left/right)**:

```
┌──────────┬──────────┐
│          │          │
│  Görsel  │   Metin  │
│          │          │
└──────────┴──────────┘
```

**CSS Implementasyonu**:

```css
.text-image--above,
.text-image--below {
  flex-direction: column;
}

.text-image--left {
  flex-direction: row;
}

.text-image--right {
  flex-direction: row-reverse;
}
```

**Mobile Davranış**:

- Horizontal layout'lar mobilde vertical'e dönüşür
- Görsel her zaman üstte görünür

---

### 6. Image Width

**Tip**: Number  
**Zorunlu**: Hayır  
**Varsayılan**: 50  
**Minimum**: 20  
**Maksimum**: 80  
**Birim**: Yüzde (%)

Yatay layout'larda (left/right) görselin genişliği.

**Kullanım Senaryoları**:

| Genişlik | Kullanım                  | Görünüm           |
| -------- | ------------------------- | ----------------- |
| 20-30%   | Küçük önizleme görselleri | Metin odaklı      |
| 40-50%   | Dengeli görsel-metin      | Standart kullanım |
| 60-70%   | Büyük görseller           | Görsel odaklı     |
| 70-80%   | Çok büyük görseller       | Galeri benzeri    |

**Örnek Hesaplama**:

- Image Width: 40%
- Text Width: 60% (otomatik)

**Fluid Template**:

```html
<f:variable
  name="imageWidthStyle"
  value="{f:if(
        condition: '{data.image_position} == left || {data.image_position} == right', 
        then: '--image-width: {data.image_width}%;'
    )}"
/>

<div class="text-image" style="{imageWidthStyle}">...</div>
```

**CSS**:

```css
.text-image--left .text-image__images,
.text-image--right .text-image__images {
  width: var(--image-width, 50%);
}
```

**Not**: Vertical layout'larda (above/below) bu ayar etkisizdir.

---

### 7. Link (İsteğe Bağlı Link)

**Tip**: Link  
**Zorunlu**: Hayır  
**Autocomplete**: Aktif

Tüm bileşeni tıklanabilir yapar. Overlay link olarak uygulanır.

**Link Tipleri**:

| Tip      | Format          | Örnek                   | Kullanım             |
| -------- | --------------- | ----------------------- | -------------------- |
| Sayfa    | t3://page?uid=X | t3://page?uid=123       | İç sayfalara link    |
| Dış Link | https://...     | https://example.com     | Dış sitelere link    |
| Email    | mailto:...      | mailto:info@example.com | Email göndermek için |
| Telefon  | tel:...         | tel:+905551234567       | Telefon aramak için  |
| Dosya    | t3://file?uid=X | t3://file?uid=456       | Dosya indirmek için  |

**Accessibility**:

```html
<f:if condition="{data.link}">
  <f:link.typolink
    parameter="{data.link}"
    class="text-image__overlay-link"
    additionalAttributes="{
            style: 'position: absolute; inset: 0; text-decoration: none;'
        }"
  >
    <span class="visually-hidden">Read more</span>
  </f:link.typolink>
</f:if>
```

**CSS - Overlay Link**:

```css
.text-image {
  position: relative; /* overlay için gerekli */
}

.text-image--linked {
  cursor: pointer;
  transition: transform 0.3s ease;
}

.text-image--linked:hover {
  transform: translateY(-2px);
}
```

**UX Notları**:

- Link eklendiğinde tüm bileşen tıklanabilir olur
- Hover efekti otomatik eklenir
- Screen reader'lar için hidden text eklenir

---

### 8. Appearance (TYPO3 Standart)

**Tip**: Basic  
**Kapsam**: TYPO3/Appearance

TYPO3'ün standart görünüm ayarları.

---

## 💻 Kullanım Örnekleri

### Örnek 1: Ürün Tanıtımı

**Yapılandırma**:

```yaml
Header: "Yeni Ürünümüz: Pro X1000"
Header Layout: H2
Bodytext: |
  <p>Sektörün en gelişmiş ürünü artık sizlerle!</p>
  <ul>
    <li>Yüksek performans</li>
    <li>Uzun pil ömrü</li>
    <li>Premium tasarım</li>
  </ul>
Image: [product-image.jpg]
Image Position: right
Image Width: 40%
Link: t3://page?uid=45 (Ürün detay sayfası)
```

**Sonuç**: Sağda %40 genişlikte ürün görseli, solda açıklama metni.

---

### Örnek 2: Ekip Üyesi

**Yapılandırma**:

```yaml
Header: "Ahmet Yılmaz - CEO"
Header Layout: H3
Bodytext: "15 yıllık deneyime sahip teknoloji lideri..."
Image: [team-member.jpg]
Image Position: left
Image Width: 30%
```

**Sonuç**: Solda küçük profil fotoğrafı, sağda biyografi.

---

### Örnek 3: Görsel Galeri

**Yapılandırma**:

```yaml
Header: "Proje Görselleri"
Header Layout: H2
Bodytext: "Tamamlanan projemizden görüntüler"
Image: [image1.jpg, image2.jpg, image3.jpg, image4.jpg]
Image Position: below
```

**Sonuç**: Üstte başlık ve metin, altta grid formatında görsel galerisi.

---

### Örnek 4: Blog Post Preview

**Yapılandırma**:

```yaml
Header: "TYPO3 v13 Yenilikleri"
Header Layout: H2
Bodytext: "TYPO3'ün yeni versiyonunda neler var?..."
Image: [blog-featured.jpg]
Image Position: above
Link: t3://page?uid=789 (Blog detay sayfası)
```

**Sonuç**: Tıklanabilir blog preview kartı, üstte featured image.

---

## 🎨 Layout Kombinasyonları

### Dengeli Layout (50-50)

```
Image Position: left/right
Image Width: 50%
```

En yaygın kullanım, görsel ve metin eşit öneme sahip.

### Metin Odaklı (70-30)

```
Image Position: left/right
Image Width: 30%
```

Metne daha fazla alan, görsel sadece destek.

### Görsel Odaklı (30-70)

```
Image Position: left/right
Image Width: 70%
```

Büyük görseller, kısa açıklama metni.

### Tam Genişlik Görsel

```
Image Position: above/below
Image Width: (etkisiz)
```

Görsel tam genişlikte, metin altında/üstünde.

---

## 🔧 Teknik Detaylar

### Dosya Yapısı

```
text-image/
├── config.yaml                 # Alan tanımları
├── assets/
│   └── icon.svg               # Backend ikonu
├── language/
│   └── labels.xlf             # Çeviriler (EN)
└── templates/
    ├── frontend.html          # Frontend template
    └── backend-preview.html   # Backend preview
```

### CSS Grid - Görsel Galerisi

```css
.text-image__image-gallery {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
  gap: 1rem;
}
```

**Davranış**:

- 1 görsel: Tek sütun, tam genişlik
- 2-3 görsel: İki sütun
- 4+ görsel: Üç sütun (büyük ekranlarda)

### Responsive Breakpoints

```css
@media (max-width: 768px) {
  /* Horizontal layout'lar vertical'e dönüşür */
  .text-image--left,
  .text-image--right {
    flex-direction: column;
  }

  /* Genişlik ayarı kaldırılır */
  .text-image--left .text-image__images,
  .text-image--right .text-image__images {
    width: 100%;
  }
}
```

---

## 🐛 Sorun Giderme

### Görsel Galerisi Düzgün Görünmüyor

**Çözüm**: CSS grid desteğini kontrol edin. Alternatif:

```css
.text-image__image-gallery {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;
}
```

### Link Çalışmıyor

1. Link alanının doldurulduğunu kontrol edin
2. Link formatının doğru olduğunu kontrol edin
3. Overlay z-index çakışması olup olmadığına bakın

### Mobile'da Layout Bozuk

1. Responsive CSS'in yüklendiğini kontrol edin
2. Viewport meta tag'in olduğunu kontrol edin
3. Browser cache'i temizleyin

---

## 📝 Best Practices

### Görsel Optimizasyonu

- **Format**: WebP > JPG > PNG
- **Boyut**: Max 500KB
- **Çözünürlük**: 72-96 DPI yeterli
- **Alt Text**: Her zaman ekleyin

### İçerik Yazımı

- **Başlıklar**: Açıklayıcı ve kısa
- **Paragraflar**: 2-3 cümle ideal
- **Listeler**: Uzun metinleri bölmek için
- **Linkler**: Açıklayıcı anchor text

### Accessibility

- **Alt Text**: Görseli tanımlayan metin
- **Heading Hierarchy**: Düzgün H1-H5 kullanımı
- **Link Text**: "Tıklayın" yerine açıklayıcı
- **Color Contrast**: WCAG AA standardı

### SEO

- **Heading Structure**: Düzgün hiyerarşi
- **Image Alt Text**: Anahtar kelime içeren
- **Content Quality**: Özgün ve değerli içerik
- **Internal Links**: İç sayfa bağlantıları

---

## 🎓 İleri Seviye Kullanım

### Custom CSS Hook'ları

```css
/* Özel varyasyon */
.text-image[data-variant="product"] {
  border: 2px solid #e0e0e0;
  border-radius: 8px;
  padding: 2rem;
}

/* Hover efekti */
.text-image--linked:hover .text-image__images img {
  transform: scale(1.05);
  transition: transform 0.3s ease;
}

/* Dark mode desteği */
@media (prefers-color-scheme: dark) {
  .text-image {
    background-color: #1a1a1a;
    color: #ffffff;
  }
}
```

### JavaScript Etkileşimi

```javascript
// Lightbox için görsel tıklama
document.querySelectorAll(".text-image__image-item img").forEach((img) => {
  img.addEventListener("click", function (e) {
    // Lightbox açma kodu
  });
});

// Lazy loading
if ("loading" in HTMLImageElement.prototype) {
  document.querySelectorAll(".text-image img").forEach((img) => {
    img.loading = "lazy";
  });
}
```

---

## 📚 İlgili Dokümantasyon

- [Hero Section](hero-section.md) - Daha etkileyici hero bölümleri için
- [TYPO3 Content Blocks](https://docs.typo3.org/p/friendsoftypo3/content-blocks/)
- [TYPO3 Fluid Documentation](https://docs.typo3.org/other/typo3/view-helper-reference/)
