Grav Kısa Kodlar (Shortcodes) ve Kullanımları

Grav ile ilgili bilgi aktarımına shortcodes yani içerik içerisinde kullanabileceğimiz ve belirli işlemleri daha pratik hale getirmemizi sağlayan özelleştirilmiş kısa kodlarla devam edelim.
AA

Grav içerik yönetim sistemi bu amaçla bize Grav Shortcode Core eklentisini sunmakta1. Bu eklenti, eklenti kapsamında yer alan tanımların yanı sıra bize kendi tanımlarımızı da yapma imkanı vermekte, peki nasıl? Öncelikle eklenti ayarlarına ve eklentinin sunduğu shortcode tanımlarına bir bakalım.

Grav Shortcode Core Plugin

Shortcode Core Grav tarafından sunulan resmi bir eklenti2 ve bu eklenti ayrıca daha pek çok özelleştirilmiş eklenti için de kaynak teşkil etmekte. Eklenti içerisindeki tanımlar plugins > shortcode-code > classes > shortcodes yolu altında yer almaktadır. Eklentiyi web sitenize indirmenizin ardından bu yol üzerinden ilgili tanımlara ulaşabilir ve düzenleme işlemi yapabilirsiniz. Ancak, unutmamak gerekir ki eklentiyi güncellediğinizde düzenlemelerinizi kaybedebilirsiniz. Yazının alt bölümünde ayrıca kendi düzenlemelerimizi nasıl yapabileceğimize değindim, isterseniz doğrudan bu başlığa geçebilirsiniz. Şimdi, eklenti ile birlikte gelen tanımlardan bazılarına ve nasıl kullanılabileceklerine bakalım. Tanımların tamanına ve kullanım örneklerine eklentinin GitHub sayfasından ulaşabilirsiniz1.

Underline

Herhangi bir metnin altı çizmenizi (underline) sağlar. underline Bu shortcode tanımı UnderlineShortcode dosyası içerisinde yer almaktadır. Tanım herhangi bir parametre (class, style vb.) almamaktadır. font-style ile ilişkilidir.

[u]metin[/u]

Font-size

Tanım içerisinde belirttiğiniz metinleri boyutlandırmanızı sağlar ve [size=30]büyük yazı[/size] şeklinde kullanıma sahiptir. İlgili tanım SizeShortcode dosyası içerisinde yer almaktadır. Herhangi bir parametre tanımı bulunmamaktadır. font-size ile ilişkilidir.

Align

Belirttiğiniz metinlerin nasıl hizalanacağını belirtmek için bu tanımdan faydalanabilirsiniz. left, center ve right tanımları olarak kullanılabilmektedir. İlgili tanımlar AlignShortcode dosyası içerisinde yer almaktadır. text-align ile ilişkilidir, harici bir parametre almaz.

[left]sola dayalı metin[/left]
[center]ortalı metin[/center]
[right]sola dayalı metin[/right]

Div

Bir alanı kapsayıcı (div) içerisine almak ve parametreler ile özelleştirmek için bu tanımı kullanabilirsiniz. Bu sayede markdown özelliklerinden de faylanmaya devam edebiliriz.

[div class="text-center"]
**Ortalı** metin.
[/div]
[div class="table table-striped"]
| header 1 | header 2 |
|----------|----------|
| A 1      | B 1      |
| A 2      | B 2      |
| A 3      | B 3      |
[/div]

Özellikle CSS framwork veya bir JavaScript fonksiyonu kullanıyor ve belirli elementleri class ya da id ile işaretlemeniz gerekiyorsa bu tanım işinize oldukça yarayacaktır. İlgili tanıma DivShortcode dosyası üzerinden ulaşabilirsiniz. Tanım, id ve class parametreleri alabilmekte.

Headers

Tanım, başlıklar oluşturabilmenizi sağlar. h1...h6 seviyesindeki başlıkları [h1]...[\h1], [h2]...[\h2] şeklinde belirtmeniz yeterli olacaktır. class ve id parametreleri alabilmektedir. İlgili tanıma HShortcode dosyası üzerinden ulaşabilirsiniz.

[h1 class="major"]Ana Başlık[/h1]
[h2 class="subtitle"]Ana Başlık[/h2]

Ekstra bir özellik sunmadığı, ilgili id ve class tanımlarına markdown extra ile ayrıca ulaşabildiğim için pek tercih etmemekteyim3.

## Başlık {.deneme #deneme}
## Başlık ## {.deneme #deneme}

Span

Belirtilen alanı span etiketleri içerisine almanızı sağlar. class ve id parametrelerini alabilir. İlgili tanım SpanShortcode dosyası içerisinde yer almaktadır.

[span class="text-center has-text-dark"]
Bu metin **ortalı** ve koyu renkte olarak sunulmaktadır.
[/span]

Columns

Bu tanım CSS Multi-column Layout özelliğini kullanarak belirttiğiniz metni sütunlara bölmenizi sağlar. columns, width, gap ve rule ile sütunlar özelleştrilebilmektedir. count metnin kaç sütuna bölünmesini istediğinizi, width sütunların genişliğini, gap sütunlar arasındaki boşluğu, rule ise sütunlar arasındaki ayracı kontrol etmek amacıyla kullanılmaktadır. İlgili tanıma ColumnShortcode dosyasından ulaşabilirsiniz.

[columns]
### Headline

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat.
[/columns]
[columns count=3 width=200px gap=30px rule="1px dotted #930"]
### Headline

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat.
[/columns]

Raw

Belirtilen metnin yorumlanmamasını sağlar.

Bu alan [u]altı çizili[/u] metin içermektedir.

E-mail

Metin içerisinde e-posta adresi belirtmeniz gerekiyor ancak e-posta adresini örümceklerden gizlemek istiyorsanız bu tanımdan faydalanabilirsiniz. İlgili tanıma SafeEmailShortcode dosyasından ulaşabilirsiniz. Tanım autolink ve icon parametrelerine sahiptir. autolink ile belirttiğinzi e-posta adresinin bağlantı özelliğine sahip olmasını, icon ile de bağlantı içerisinde simge kullanılmasını sağlayabilirsiniz. Simgeler için fontawesome kullanılmaktadır.

E-posta: [safe-email autolink="true" icon="envelope-o"]kullanici@alanadi.com[/safe-email]

Section

Çok amaçlı alanlar oluşturabilmemizi ve bu alanları farklı alanlarda tekrar kullanabilmemizi sağlar.

[section name="author"]
![](author.jpg?cropResize=100,100&classes=left)
### Johnny Appleseed
Johnny Appleseed was an American pioneer nurseryman who introduced apple trees to large parts of Pennsylvania, Ontario, Ohio, Indiana, and Illinois, as well as the northern counties of present-day West Virginia. He became an American legend while still alive, due to his kind, generous ways, his leadership in conservation, and the symbolic importance he attributed to apples.
[/section]

[section name="quote"]
> Some are born great, some achieve greatness, and some have greatness thrust upon them.
  Read more at http://www.brainyquote.com/quotes/topics/topic_great.html#tdqt3strtEYBCH43.99
> <cite>William Shakespeare</cite>

Regular **Markdown** content that will be output as `page.content`
[/section]

Yukarıdaki tanım yorumlanmasıyla birlikte Grav tarafından önbelleğe alınır ve bu sayede tekrar tekrar erişilebilir hale gelir.

<div id="author">{{ shortcode.section.author }}</div>

<div id="article">
    <div class="left">
        {{ page.content }}
    </div>
    <div class="right">
        {{ shortcode.section.quote }}
    </div>
</div>

Ayrıca, farklı bir sayfadan da section kullanılan sayfa belirtilmek koşulu ile oluşturduğumuz tanımlara erişebiliriz.

<div id="author">{{ page.find('/my/custom/page').contentMeta.shortcodeMeta.shortcode.section.author }}</div>

İlgili tanım SectionShortcode dosyası içerisinde yer almaktadır.

Figure

HTML5 Semantic olarak görseller, grafikler, videolar gibi kendi alanını oluşturan (self-contained units) elementler için figure etiketi önerir. Yine bu etiket içerisinde de caption ile içeriğe dair bilgi sunabilmekteyiz.

<figure id="l4">
 <figcaption>Listing 4. The primary core interface API declaration.</figcaption>
 <pre><code>interface PrimaryCore {
 boolean verifyDataLine();
 undefined sendData(sequence&lt;byte> data);
 undefined initSelfDestruct();
}</code></pre>
</figure>

Figure tanımı bize bu etiketten faydalanma imkanı sunmaktadır. Çünkü, HTML olarak kullanımımız markdown doğrulama aşamalarında hatalarla/uyarılarla karşılaşmamıza neden olabilmektedir.

[figure id="fig1" class="image" caption="**Fig. 1** A beautiful figure."]
![Gorgeous image](image.png)
[/figure]

İlgili tanım FigureShortcode dosyası içerisinde yer almaktadır. class, id ve caption parametrelerine sahiptir. caption içerisinde belirtilen ifade figcaption etiketleri içerisinde sunulmaktadır.

Language

Language tanımı, Grav web siteniz çok dilli ise belirli blokların dillere göre görüntülenmesini sağlamak amacıyla kullanılmaktadır.

[lang=en]
Or kind rest bred with am shed then.
[/lang]

[lang=fr]
Marche diable ombres net non qui.
[/lang]

[lang=de]
Genie dahin einem ein gib geben allen.
[/lang]

İlgili tanım LanguageShortcode dosyası içerisinde yer almaktadır ve herhangi bir parametreye sahip değildir.

Twig İçerisinde Kullanım

Yukarıda eklenti ile birlikte gelen tanımlardan bazılarını gördük. Elbette farklı eklentilerle veya biz temamız içerisinde farklı tanımlara yer verebilmekteyiz. Grav bize bu tanımları twig ile birlikte kullanım imkanı da sunar.

{% set twig_text = "This is [size=30]bigger text[/size] and this is [color=green]green text[/color]" %}

Yukarıda bir shortcode tanımı twig_text isimli değişkene atanmakta. Artık bu değişken vasıtasıyla ilgili tanıma ulaşabiliriz. Ancak, doğrudan çağırmamız durumunda shortcode yorumlanmaz. Yorumlama işlemini |shortcodes ile gerçekleştiririz.

{{ twig_text|shortcodes }}

Grav Makdown İçerik Yazımı başlıklı yazımda twig kodlarını nasıl markdown içeriklerimizde değerlendirebileceğimizden bahsetmiştim, görüldüğü üzere Grav CMS bize çok az kod müdahalesi ile oldukça esnek ve özelleştirilebilir bir yapı sunmakta.

Özel Tanımlar

Gelelim asıl konumuza, kendimiz nasıl shortcode oluşturabiliriz?

Grav bize Shortcode Core ile kendi tanımlarımızı yapabilme imkanı sunar. Bu işlem için eklentiye ait tanımlar arasında yeni dosyalar oluşturabileceğimiz gibi eklenti ayarlarından farklı bir dizin belirterek buradaki tanımların işleme alınmasını sağlayabiliriz. İlk durum, eklenti güncellendiğinde özelleştirmeleri veya dosyaları kaybetme gibi bir sorunla karşılaşmamıza neden olabilir. Ayrıca, temanın önemli bir parçası konumunda tanımlar oluşturacaksak bu tanımların tema klasörü içerisinde bulunmaları daha pratik olacaktır. Bu nedenle ikinci yol üzerinden ilerlemek doğru bir karar olacaktır. Peki, bu tanımı nasıl yapacağız?

<?php
namespace Grav\Plugin\Shortcodes;
use Thunder\Shortcode\Shortcode\ShortcodeInterface;
class StrikeShortcode extends Shortcode {
    public function init() {
        $this->shortcode->getHandlers()->add('strike', function(ShortcodeInterface $sc) {
            return '<del>'.$sc->getContent().'</del>';
        });
    }
}

shortcode oluşturduğumuz tanımı nasıl belirteceğimizi ifade eder. Yani, bu kod parçacığına göre [strike]...[/strike] ile işlemler gerçekleştirebiliriz. return bu tanımın görevini ifade eder. Yani [strike]...[/strike] ile işaretlediğimiz satır yorumlandıktan sonra <del>...</del> şeklinde sunulur. Peki, parametre eklemek istersek?

Şimdi, yukarıdaki kod parçacığına class parametresini ekleyelim.

<?php
namespace Grav\Plugin\Shortcodes;
use Thunder\Shortcode\Shortcode\ShortcodeInterface;
class StrikeShortcode extends Shortcode {
    public function init() {
        $this->shortcode->getHandlers()->add('strike', function(ShortcodeInterface $sc) {
            $class = $sc->getParameter('class');
            return '<del class="'. $class .'">'.$sc->getContent().'</del>';
        });
    }
}

Evet, class parametremizi de shortcode ile ilişkilendirdik. İsterseniz class parametresi için ön tanımlar ve kontroller de ekleyebilirsiniz.

<?php
namespace Grav\Plugin\Shortcodes;
use Thunder\Shortcode\Shortcode\ShortcodeInterface;
class StrikeShortcode extends Shortcode {
    public function init() {
        $this->shortcode->getHandlers()->add('strike', function(ShortcodeInterface $sc) {
            $class = $sc->getParameter('class');
            $class_output = ($class) ? $class : 'has-text-weight-bold';
            return '<del class="'. $class_output .'">'.$sc->getContent().'</del>';
        });
    }
}

İşlemlerimiz bu kadar. Bu sayede markdown içerikleriniz içerisinde uyarılar oluşturmayacak şekilde özelleştirmeler yapabilir ve tekrarlanan işlemleri daha pratik bir şekilde çözümleyebilirsiniz.

  1. Grav Shortcode Core Plugin ↩ ↩
  2. Grav Plugins ↩
  3. PHP Markdown Extra ↩
Yorum alanını göster
Beğendim
Beğenmedim