WordPress Block Editörü için bir block kodlamaya başlamıştık. Bunun için bir önceki dersimizde, WordPress tarafından geliştirilen @wordpress/create-block adındaki npm paketi ile sc-cards adında bir block eklentisi oluşturmuştuk. Bu dersi görmediyseniz ya da tekrar bir göz atmak isterseniz aşağıdaki bağlantıya tıklayabilirsiniz:

• WordPress Block Editörü İçin Bir Block Oluşturma (@wordpress/create-block ile)

Kullandığımız @wordpress/create-block adındaki npm paketi, hem eklentiyi hem de block dosya ve klasörlerini bizim için oluşturmuştu.

Bu dersimizde, oluşturulan bu dosya ve klasörlerin ne anlama geldiğini açıklamaya çalışacağız.

@wordpress/create-block Paketi ile Oluşturulan Block Eklentisinin Dosya Yapısı

• @wordpress/create-block paketi ile oluşturulan bir block eklentisinin dosya dizini şöyle olmuştu:

• Daha sonra yine bir npm paketi olan @wordpress/scripts paketini yüklemiş ve ardından npm start komutu ile dosya yapısını son haline getirmiştik:

Block Dizinindeki Klasör ve Dosyalar

Şimdi gelin, sırasıyla, sc-cards dizinindeki bütün klasör ve dosyaların anlamını ve ne işe yaradıklarını öğrenelim.

“build” Klasörü

• Burada hiç bir dosyaya tek satır bile kod yazmayacağız.
• Bu klasör ve altındaki dosyalar, @wordpress/scripts paketi tarafından bizim için itina ile oluşturulur.
• Aslında oluşturduğumuz block bu klasördedir. İşimiz bittiğinde, bloğumuzu başka bir WordPress kurulumuna yüklemek istersek;
  • sc-cards klasörünü sadece, içindeki build klasörü ve sc-cards.php dosyası ile buradan alıp o WordPress kurulumunun plugins dizinine yüklememiz yeterli olacaktır.
• build klasöründeki dosya ve kodlarının nereden geldiğini src klasörünü okurken daha iyi anlayacaksınız.

“node_modules” Klasörü

• Bu klasör oldukça hacimli bir klasörüdür ve bizim aktif olarak müdahale ettiğimiz bir klasör değildir.
• Block kodlamak için ihtiyaç duyduğumuz paket ya da kütüphaneler burada saklanır.
• npm komutu ile yüklediğimiz scriptler buraya kaydedilir.
• İhtiyaç duyulan scriptler buradan gerekli yerlerde import edilir ve kullanılır.
• Bloğumuzu kullanmak üzere taşırken bu klasör bizimle gelmeyecek, burada kalacaktır.

“src” Klasörü

• Bütün kodlama işlerini bu klasörde yaparız.
• Burası bizim mutfağımızdır, burada bloğumuzu kodlarız.
  • Kodlarımızda ESNext ve JSX gibi henüz tarayıcıların anlamadığı diller de kullanabiliriz.
  • İşte npm start komutu tam da burada imdadımıza yetişir.
  • Bu komut, bizim kodlarımızı alır, tarayıcıların anlayacağı standartlara sokar ve build klasöründeki ilgili dosyalara dağıtır (bu olaya kısaca WepPack diyoruz.).
  • npm start komutuna, neler yapacağını, @wordpress/scripts paketi söyler.
• Kodlarımızı test etmek için, terminalin komut satırı sc-cards dizininde iken, npm start komutunu çalıştırırız.
  • npm start komutunun bir defa çalıştırılması yeterlidir. Bu komut bir defa çalıştıktan sonra bizi dinlemeye devam eder ve dosyalarımızda yaptığımız her kaydet (ctrl + s) işleminde otomatik olarak tekrar çalışır.
  • npm start komutunu durdurmak için “ctrl + c” tuş kombinasyonuna basmamız ve ardından sorulan soruya; önce “y” tuşuna sonra da enter tuşuna basarak cevap vermemiz gerekir.
• Bloğumuz kullanmak üzere taşırken, bu klasör bizimle gelmeyecek burada kalacaktır.
• src klasöründeki dosyaların yapısı ve görevleri şöyledir:

“block.json” Dosyası

block.json

{
	"$schema": "https://schemas.wp.org/trunk/block.json",
	"apiVersion": 2,
	"name": "create-block/sc-cards",
	"version": "0.1.0",
	"title": "Sc Cards",
	"category": "widgets",
	"icon": "smiley",
	"description": "Example block written with ESNext standard and JSX support – build step required.",
	"supports": {
		"html": false
	},
	"textdomain": "sc-cards",
	"editorScript": "file:./index.js",
	"editorStyle": "file:./index.css",
	"style": "file:./style-index.css"
}

• Oluşturduğumuz block hakkındaki temel bilgiler ve değişkenler bu dosyada saklanır.
• Bu dosyada gördüğümüz ifadeler şu anlama gelir:
  • "$schema": Dosyanın şemasını kontrol eden satırdır. Olduğu gibi bırakırız.
  • "apiVersion": Kullandığımız API’nin versiyonudur. Bizimle ilgili bir satır değildir, olduğu gibi bırakırız.
  • "name": Bloğumuz adıdır. Bu ifadenin değerini, üst-isim/block-adi şablonuna sadık kalarak dilediğimiz gibi değiştirebiliriz.
    • Fakat, burada yaptığımız değişikliği, aynı dizindeki index.js dosyasına da taşımamız gerekir.
  • "version": Oluşturduğumuz bloğun versiyonudur. Değeri tamamen bize bağlıdır.
  • "title": Bloğun adıdır. Bu isim block editörde bloğumuz adı olarak görünür. Dilediğimiz gibi değiştirebiliriz.
  • "category": Bloğumuzun diğer bloklar arasındaki yerleşimini belirler.
    • WordPress ile varsayılan olarak gelen block kategorileri şunlardır:
      1. text
      2. media
      3. design
      4. widgets
      5. theme
      6. embed
    • Kendinize ait bir kategori oluşturup bloğunuzu o kategoride de yayınlayabilirsiniz.
      • Bunun için, aşağıdaki kodları, sc-cards.php dosyasının sonuna eklemeniz yeterlidir:

sc-cards.php

function sc_add_custom_block_category( $categories ) {
	
	$categories[] = array(
		'slug'  => 'benim-blocklarim',
		'title' => 'Benimkiler'
	);

	return $categories;
}

if ( version_compare( get_bloginfo( 'version' ), '5.8', '>=' ) ) {
	add_filter( 'block_categories_all', 'sc_add_custom_block_category' );
} else {
	add_filter( 'block_categories', 'sc_add_custom_block_category' );
}

Bu koddan sonra; block.json dosyasında kategori kısmına şöyle demeliyiz: "category": "benim-blocklarim"

• block.json dosyasını tanımaya devam ediyoruz:
  • "icon": Oluşturduğumuz block, editörde bu ikon ile temsil edilir.
    • Burada, WordPress dashiconlarından herhangi birini de kullanabiliriz.
    • Mesela "dashicons-admin-post" adındaki dashiconu kullanmak için burada;
      • "icon": "admin-post" kodunu kullanırız.
  • "description": Blok için block editörde gösterilecek olan açıklamadır.
    • Bloğumuzu kısa ve etkili bir şekilde tanıtabilmemiz için harika bir yedir.
    • Bu satır, block editörde şöyle görünür:
      
  • "supports": Bloğun hangi ayarları destekleyeceğine burada karar veriyoruz.
    • Mesela burada şöyle bir kod kullanırsak:
      "supports": { "html": true }
      bloğumuza şöyle bir özellik eklenir:
      
  • "textdomain": Burası, bloğumuzu tercüme etmek için gereklidir. Değerini dilediğimiz gibi değiştirebiliriz.
    • Tercümeye hazır textler oluştururken, buraya yazdığımız değeri kullanırız.
  • "editorScript": Sadece editörü ilgilendiren scriptlerin nereye derleneceğini ifade eder. Mümkün olduğunca kurcalanmamalıdır.
  • "editorStyle": Sadece editörü ilgilendiren CSS’in nereye derleneceğini ifade eder. Mümkün olduğunca kurcalanmamalıdır.
  • "style": Bloğumuz ile ilgili CSS’in nereye derleneceğini ifade eder. Mümkün olduğunca kurcalanmamalıdır.

“edit.js” Dosyası

edit.js

/**
 * Retrieves the translation of text.
 *
 * @see https://developer.wordpress.org/block-editor/packages/packages-i18n/
 */
import { __ } from '@wordpress/i18n';

/**
 * React hook that is used to mark the block wrapper element.
 * It provides all the necessary props like the class name.
 *
 * @see https://developer.wordpress.org/block-editor/packages/packages-block-editor/#useBlockProps
 */
import { useBlockProps } from '@wordpress/block-editor';

/**
 * Lets webpack process CSS, SASS or SCSS files referenced in JavaScript files.
 * Those files can contain any CSS code that gets applied to the editor.
 *
 * @see https://www.npmjs.com/package/@wordpress/scripts#using-css
 */
import './editor.scss';

/**
 * The edit function describes the structure of your block in the context of the
 * editor. This represents what the editor will render when the block is used.
 *
 * @see https://developer.wordpress.org/block-editor/developers/block-api/block-edit-save/#edit
 *
 * @return {WPElement} Element to render.
 */
export default function Edit() {
	return (
		<p { ...useBlockProps() }>
			{ __( 'Sc Cards – hello from the editor!', 'sc-cards' ) }
		</p>
	);
}

Ben yorumları temizleyip kullanıyorum:

edit.js (yorumsuz)

import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';
import './editor.scss';

export default function Edit() {
	return (
		<p { ...useBlockProps() }>
			{ __( 'Sc Cards – hello from the editor!', 'sc-cards' ) }
		</p>
	);
}

• Bloğumuzun editör görünümüne ait kodları buraya yazarız.
• Buradaki kodlar, yönetim paneli tarafında çalışır, bloğun tema görünümünü etkilemez.
  • Mesela yukarıdaki haliyle, bloğumuz editörde şöyle görünür:
    
• İlerleyen derslerde, daha havalı hale getireceğiz.

“editor.scss” Dosyası

editor.scss

/**
 * The following styles get applied inside the editor only.
 *
 * Replace them with your own styles or remove the file completely.
 */

.wp-block-create-block-sc-cards {
	border: 1px dotted #f00;
}

• Sadece editör tarafında çalışacak SCSS kodlarını buraya yazarız.
  • SCSS, CSS kodu yazmanın daha pratik bir yoldur. Bir kaç basit kuralı vardır. Bilmiyorsanız da normal CSS kodları, bu dosyada çalışacaktır.
  • Yazılan SCSS kodları, npm start komutu ile sonrasında da ctrl + s tuş kombinasyonu ile, otomatik olarak derlenir ve build klasöründe ilgili yerlere gönderilir.
• Bu dosyaya girdiğimiz SCSS kodları, burada anlatılanların dışında bir yol izlemezsek tema görünümünü etkilemez, sadece editör görünümünü etkiler.
• Dosya, yukarıda gördüğünüz şekilde gelir.

“index.js” Dosyası

index.js

/**
 * Registers a new block provided a unique name and an object defining its behavior.
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/
 */
import { registerBlockType } from '@wordpress/blocks';

/**
 * Lets webpack process CSS, SASS or SCSS files referenced in JavaScript files.
 * All files containing `style` keyword are bundled together. The code used
 * gets applied both to the front of your site and to the editor.
 *
 * @see https://www.npmjs.com/package/@wordpress/scripts#using-css
 */
import './style.scss';

/**
 * Internal dependencies
 */
import Edit from './edit';
import save from './save';

/**
 * Every block starts by registering a new block type definition.
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/
 */
registerBlockType( 'create-block/sc-cards', {
	/**
	 * @see ./edit.js
	 */
	edit: Edit,

	/**
	 * @see ./save.js
	 */
	save,
} );

• Bloğumuz için yazdığımız bütün kodlar burada toplanır.
• Bloğumuzun ana dosyasıdır.
• Bu dosyaya çağırılmayan kodlar ve dosyalar bloğumuzda kullanılamaz.
• Bu dosya ile genellikle işimiz olmayacak, bu haliyle kalacak.

“save.js” Dosyası

save.js

/**
 * Retrieves the translation of text.
 *
 * @see https://developer.wordpress.org/block-editor/packages/packages-i18n/
 */
import { __ } from '@wordpress/i18n';

/**
 * React hook that is used to mark the block wrapper element.
 * It provides all the necessary props like the class name.
 *
 * @see https://developer.wordpress.org/block-editor/packages/packages-block-editor/#useBlockProps
 */
import { useBlockProps } from '@wordpress/block-editor';

/**
 * The save function defines the way in which the different attributes should
 * be combined into the final markup, which is then serialized by the block
 * editor into `post_content`.
 *
 * @see https://developer.wordpress.org/block-editor/developers/block-api/block-edit-save/#save
 *
 * @return {WPElement} Element to render.
 */
export default function save() {
	return (
		<p { ...useBlockProps.save() }>
			{ __(
				'Sc Cards – hello from the saved content!',
				'sc-cards'
			) }
		</p>
	);
}

• Bloğumuzun tema görünümü belirleyen kodlamalar burada yapılır.
• Yukarıdaki haliyle gelir fakat ben yorumları silip kullanmayı tercih ederim:

save.js (yorumsuz)

import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';
export default function save() {
	return (
		<p { ...useBlockProps.save() }>
			{ __(
				'Sc Cards – hello from the saved content!',
				'sc-cards'
			) }
		</p>
	);
}

• Bu hali ile, bloğumuzun tema görünümü şöyle olacaktır:
  

“style.scss” Dosyası

style.scss

/**
 * The following styles get applied both on the front of your site
 * and in the editor.
 *
 * Replace them with your own styles or remove the file completely.
 */

.wp-block-create-block-sc-cards {
	background-color: #21759b;
	color: #fff;
	padding: 2px;
}

• Hem editör hem de tema tarafında çalışacak SCSS kodlarını buraya yazarız.
  • Yazılan SCSS kodları, npm start komutu ile sonrasında da ctrl + s tuş kombinasyonu ile, otomatik olarak derlenir ve build klasöründe ilgili yerlere gönderilir.
• Dosya, yukarıda gördüğünüz şekilde gelir.

“.editorconfig.scss” Dosyası

.editorconfig.scss

# This file is for unifying the coding style for different editors and IDEs
# editorconfig.org

# WordPress Coding Standards
# https://make.wordpress.org/core/handbook/coding-standards/

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = tab

• .editorconfig: Bu dosya, kod editörümüze kod yapımız ile ilgili olarak bazı bilgiler verir.
  • Hangi editörler ile konuşabilir, ne kadar konuşabilir açıkçası araştırmadım. Bilenler yorum olarak yazarsa müteşekkir olurum.
• Yukarıdaki haliyle gelir.

“.gitignore.scss” Dosyası

.gitignore.scss

# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Coverage directory used by tools like istanbul
coverage

# Compiled binary addons (https://nodejs.org/api/addons.html)
build/Release

# Dependency directories
node_modules/

# Optional npm cache directory
.npm

# Optional eslint cache
.eslintcache

# Output of `npm pack`
*.tgz

# Output of `wp-scripts plugin-zip`
*.zip

# dotenv environment variables file
.env

• Göz ardı edilmesi gereken, takip edilmesi gerekemeyen dosya ve klasörleri belirtir.

“package-lock.json” Dosyası

• Kodlarımızın çalışması için gerekli olan bütün paketlerin bir listesini tutar.
• npm install dediğimizde, gerekli paketlerin tastamam indirilmesini sağlar.
• Aslında bizim manuel olarak herhangi bir işlem yapmayacağımız bir dosyadır.
• npm paketi gerekli olan her şeyi otomatik olarak halledecektir.
• Oldukça kalabalık bir dosyadır.

“package.json” Dosyası

package.json

{
	"name": "sc-cards",
	"version": "0.1.0",
	"description": "Example block written with ESNext standard and JSX support – build step required.",
	"author": "The WordPress Contributors",
	"license": "GPL-2.0-or-later",
	"main": "build/index.js",
	"scripts": {
		"build": "wp-scripts build",
		"format": "wp-scripts format",
		"lint:css": "wp-scripts lint-style",
		"lint:js": "wp-scripts lint-js",
		"packages-update": "wp-scripts packages-update",
		"plugin-zip": "wp-scripts plugin-zip",
		"start": "wp-scripts start"
	},
	"devDependencies": {
		"@wordpress/scripts": "^23.3.0"
	}
}

• Projemizin temel bilgilerini ve kullandığımız npm paketlerini, scriptleri içeren bir dosyadır.
• Bu dosya da npm paketi tarafından otomatik olarak oluşturulur.
• Genelde npm paketinin otomatik olarak çekip çevirdiği, bizim de kendi haline bıraktığımız bir dosyadır.

“package.json” Dosyası

readme.txt

=== Sc Cards ===
Contributors:      The WordPress Contributors
Tags:              block
Tested up to:      5.9
Stable tag:        0.1.0
License:           GPL-2.0-or-later
License URI:       https://www.gnu.org/licenses/gpl-2.0.html

Example block written with ESNext standard and JSX support – build step required.

== Description ==

This is the long description. No limit, and you can use Markdown (as well as in the following sections).

For backwards compatibility, if this section is missing, the full length of the short description will be used, and
Markdown parsed.

== Installation ==

This section describes how to install the plugin and get it working.

e.g.

1. Upload the plugin files to the `/wp-content/plugins/sc-cards` directory, or install the plugin through the WordPress plugins screen directly.
1. Activate the plugin through the 'Plugins' screen in WordPress


== Frequently Asked Questions ==

= A question that someone might have =

An answer to that question.

= What about foo bar? =

Answer to foo bar dilemma.

== Screenshots ==

1. This screen shot description corresponds to screenshot-1.(png|jpg|jpeg|gif). Note that the screenshot is taken from
the /assets directory or the directory that contains the stable readme.txt (tags or trunk). Screenshots in the /assets
directory take precedence. For example, `/assets/screenshot-1.png` would win over `/tags/4.3/screenshot-1.png`
(or jpg, jpeg, gif).
2. This is the second screen shot

== Changelog ==

= 0.1.0 =
* Release

== Arbitrary section ==

You may provide arbitrary sections, in the same format as the ones above. This may be of use for extremely complicated
plugins where more information needs to be conveyed that doesn't fit into the categories of "description" or
"installation." Arbitrary sections will be shown below the built-in sections outlined above.

• Bir text dosyasıdır ve bloğumuzun çalışmasında aktif bir görevi yoktur.
• Bloğumuzun geliştiricisi, versiyonları, lisans durumu gibi konularda bilgiler verilir.
• Bloğumuz ile ilgili bilinmesi gereken önemli veya kritik noktaları burada dilediğimiz gibi belirtiriz.
• Eklentimiz için bir nevi “help” görevi görür.

“sc-cards.php” Dosyası

sc-cards.php

<?php
/**
 * Plugin Name:       Sc Cards
 * Description:       SiteCenneti.com tarafından geliştirilmiş harika bir card bloğudur.
 * Requires at least: 5.8
 * Requires PHP:      7.0
 * Version:           0.1.0
 * Author:            Muzaffer KAYA
 * Author URI: 	      https://sitecenneti.com/iletisim/
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       sc-cards
 *
 * @package           create-block
 */

/**
 * Registers the block using the metadata loaded from the `block.json` file.
 * Behind the scenes, it registers also all assets so they can be enqueued
 * through the block editor in the corresponding context.
 *
 * @see https://developer.wordpress.org/reference/functions/register_block_type/
 */
function create_block_sc_cards_block_init() {
	register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'create_block_sc_cards_block_init' );

• Eklentimizi WordPress veritabanına tanıtan dosyadır.
• Bu dosyanın başındaki yorum kısmında verilen bilgiler, yönetim panelinin “Eklentiler” sayfasında, karşımıza çıkar.
• Eklentimiz ile ilgili gerekli PHP kodları bu dosyaya girilir.