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.
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.
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<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.