WordPress.org

Дванаеста радионица за израду Вордпрес тема је одржана у суботу, 16 марта у новосадском Стартит Центру. Овај термин смо посветили прилагођавачу (Customizer).

Објекти прилагођавача

Прилагођавач је сачињен од четири типа објекта: панел, секција, подешавање и контрола. Сваки од њих има три метода, add_, get_ и remove_, који нам омогућавају да прилагодимо прилагођавач различитим потребама. За било какво прилагођавање користимо customize_register копчу акције.

Панел

Подразумевани прилагођавач нема регистрованих панела али их је лако додати помоћу add_panel метода. Панел може садржавати једну или више секција. Уколико ће имати само једну секцију, онда је за корисничко искуство много корисније да та секција буде самостална.

Важно је имати у виду да панел мора да има бар једну секцију да би био видљив у прилагођавачу. Исто тако, да би секција била видљива у прилагођавачу, мора да садржи бај деан пар подешавања и контроле.

Доступне методе: add_panel, get_panel и remove_panel.

Секција

Секција може бити самостална а може и да, поред других секција, припада панелу. Све подразумеване секције су самосталне. За додавање нове секције користимо add_section метод WP_Customize_Manager објекта док за уклањање користимо remove_section. За промену било ког аргумента подразумеване секције користимо get_section.

Подразумеване секције су:

Назив	ID	Приоритет (Редослед)
Site Title & Tagline	title_tagline	20
Colors	colors	40
Header Image	header_image	60
Background Image	background_image	80
Menus (Panel)	nav_menus	100
Widgets (Panel)	widgets	110
Static Front Page	static_front_page	120
default		160
Additional CSS	custom_css	200

Доступне методе: add_section, get_section и remove_section.

Подешавање

Подешавање увек иде у пару са контролом. Овде се дефинише да ли ће вредност контроле бити сачувана као option или theme_mod, подразумевана вредност контроле, начин приказивања промене у самом прилагођавачу итд.

Препоручује се да јединствени назив подешавања, ID, буде исти као и контролин јер ово омогућава лакше динамичко приказивање вредности код неких контрола, као што су select и radio.

Доступне методе: add_setting, get_setting и remove_setting.

Контрола

Котрола је заправо поље обрасца помоћу кога добијамо жељену вредност од корисника.

Подразумевана подешавања и контроле:

Назив	ID	Секција
Site Title	blogname	title_tagline
Tagline	blogdescription	title_tagline
Display Site Title and Tagline	header_text	title_tagline
Site Icon	site_icon	title_tagline
Logo	custom_logo	title_tagline
Header Text Color	header_textcolor	colors
Background Color	background_color	colors
Header Image	header_image	header_image
Header Image Data	header_image_data	header_image
Header Video	header_video	header_image
External Header Video	external_header_video	header_image
Background Image	background_image	background_image
Preset	background_preset	background_image
Image Position	background_position	background_image
Image Size	background_size	background_image
Repeat Background Image	background_repeat	background_image
Scroll with Page	background_attachment	background_image
Your homepage displays	show_on_front	static_front_page
Homepage	page_on_front	static_front_page
Posts page	page_for_posts	static_front_page
CSS code	custom_css	custom_css

Доступне контроле:

• text,
• textarea,
• email,
• url,
• radio,
• select,
• number,
• checkbox,
• dropdown-pages,
• password,
• hidden и
• date.

Доступне напредне контроле:

• WP_Customize_Image_Control,
• WP_Customize_Color_Control,
• WP_Customize_Media_Control,
• WP_Customize_Upload_Control,
• WP_Customize_Background_Image_Control,
• WP_Customize_Background_Position_Control,
• WP_Customize_Cropped_Image_Control,
• WP_Customize_Site_Icon_Control,
• WP_Customize_Theme_Control,
• WP_Customize_Code_Editor_Control,
• WP_Customize_Date_Time_Control

Доступне методе: add_control, get_control и remove_control.

Селективно освежавање

Како би корисничко искуство живог прегледа промена у прилагођавачу било што ефикасније, уместо освежавања целе странице, могуће је освежавање само елемента који се мења на страници. Ово се постиже transport параметром у подешавању и додавањем подешавања у selective_refresh објект.

Санитизација

Сваку вредност коју добијамо као унос корисника је неопходно припремити за похрањивање у базу података. Тај процес се назива санитизација.

У Вордпресу постоје готове функције које врше санитизацију за одређене типове вредности. Називи већине ових функција започињу са sanitize_.

За вредности које можемо очекивати из прилагођавача а за које не постоје припремљене функције, санитизацију вршимо помоћу прилагођених функција. Вордпресов тим за преглед тема, WPTRT, је припремио низ примера доступних на Github-u.

---

Комплетан код са радионице се може преузети са званичног налога Вордпрес Србија заједнице на Github-u.

Следећи термин ћемо посветити напреднијом употребом прилагођавача помоћу Кирки додатка.

Радионице су бесплатне али је потребно пријавити се на Meetup групи Вордпрес Србија заједнице.

Десета радионица за израду Вордпрес тема је одржана у суботу, 16 фебруара у новосадском Стартит Центру. Бавили смо се подршком теме за нови уређивач, познат под називом Гутенберг.

Учитавање стилова и скрипти

За учитавање скрипти и стилова за блокове и њихов уређивач користимо исте функције као и до сада, wp_enqueue_scripts и wp_enqueue_styles. Разликују се једино имена копчи за које везујемо позиве.

еnqueue_block_assets – Примењује се и на уређивач блокова и на фронтенд. Корисно је када желимо да нам блокови изгледју и понашају се исто и у уређивачу и на фронтенду.  

enqueue_block_editor_assets – Примењује се само на уређивач те се најчешће користи у додацима.

Подршка теме

Нови уређивач је донео низ нових могућности које тема може да подржава.

add_theme_support( ‘align-wide’ );

Широко поравнање подразумева две нове могућности, широко поравнање и пуну ширину. У самом уређивачу се примењује одмах након додавања подршке док је за фронтенд потребан додатни CSS како би се нове ширине примениле.

add_theme_support( ‘wp-block-styles’ );

Сви блокови долазе са предефинисаним стиловима у уређивачу. Уколико желимо да применимо ове стилове и на фронтенд, то можемо урадити укључивањем подршке за стилове блокова. У зависности од теме и њених већ постојећих стилова, неопходно је додати мање или више CSS-а у стилове теме како би се сви стилови из уређивача применили и на фронтенд.

add_theme_support( ‘editor-font-sizes’ );

Уређивач дозвољава корисницима да мењају величину фонта. Осим неколико предефинисаних величина, корисници могу дефинисати било коју величину за текст који уносе. Ове предефинисане величине је могуће променити помоћу подршке за величину фонта.

За савку нову величину ће се генерисати нова класа по следећем моделу:

.has-{ВЕЛИЧИНА}-font-size  

При чему је ВЕЛИЧИНА заправо slug који смо доделили прилагођеној величини. Подразумеване величине за које класе већ постоје су: small, regular, medium, large, huge и larger.

add_theme_support( ‘disable-custom-font-sizes’ );

Уколико желимо да онемогућимо коришћење било које величине осим дефинисаних, можемо да укључимо подршку за онемогућавање прилагођених величина.

add_theme_support( ‘responsive-embeds’ );

Подршка за пуну ширину угњежђивања на свим уређајима, при чему су очуване пропорције на свакој величини екрана.

add_theme_support( ‘editor-color-palette’ );

Као и величине фонта, уређивач има предефинисане палете боја које се могу применити као боја текста и боја позадине за поједине елементе. Такође, CSS класе се генеришу по истом принципу као и за величину фонта.  

.has-{БОЈА}-color

.has-{БОЈА}-background-color

Предефинисане боје су: pale-pink, vivid-red, luminous-vivid-orange, luminous-vivid-amber, light-green-cyan, vivid-green-cyan, pale-cyan-blue, vivid-cyan-blue, very-light-gray, cyan-bluish-gray и very-dark-gray, а осим ових боја такође је могуће користити било коју боју.

Подразумеване боје је могуће заменити прилагођеном палетом путем подршке теме.

add_theme_support( ‘disable-custom-colors’ );

Такође, уколико желимо да онемогућимо коришћење боја које нису предефинисане, можемо то да урадимо укључивањем подршке теме.

---

Комплетан код са радионице се може преузети са званичног налога Вордпрес Србија заједнице на Github-u.

У следећем термину настављамо са уређивачем: правимо шаблоне блокова и мењамо појединости предефинисаних блокова уз помоћ доступних филтера.

Радионице су бесплатне али је потребно пријавити се на Meetup групи Вордпрес Србија заједнице.

Девета радионица за израду Вордпрес тема је одржана у суботу, 02 фебруара у новосадском Стартит Центру. Упознали смо се са функцијама за интернационализацију и алатима за локализацију теме.

Једноставни текст

Када у кôду имамо једноставан текст без динамичких вредности или елемената специфичних за одређени језик (као што су бројеви, датум и време), можемо користити неколико функција за интернационализацију, у зависности од места на коме се текст налази и коју улогу игра.

__(), _e() – најједноставнија функција која враћа, одн. принта текст и замењује га локализованим преводом, уколико постоји.  

esc_html__(), esc_html_e() – преводи исто као и горе неведене функције, и врши escaping за HTML.

esc_attr__(), esc_attr_e() – преводи исто као и горе неведене функције, и врши escaping за атрибуте.

Контекст

Функције за додавање контекста не праве никакву разлику у самом процесу и функционалности локализације али су од великог значаја за преводиоца.

Конкретно у енглеском језику постоје речи које се исто пишу као глагол и као именица али имају потпуно другачије значење: post (именица: чланак; глагол: послати), book (именица: књига; глагол: резервисати) итд.

У оваквим случајевима контекст представља огромну помоћ да се, без потребе гледања у кôд, израз прецизно преведе.

_x(), _ex() – функција са контекстом која враћа, одн. принта текст и замењује га локализованим преводом, уколико постоји.

esc_html_x(), esc_attr_x() – преводе исто као и горе неведене функције, и врше escaping за HTML, одн атрибуте.

Једнина и множина

Функције за разликовање једнине и множине у зависности од прослеђеног броја такође могу бити са или без контекста.

Помоћу ових функција алати за локализацију препознају да треба да примењују адекватан формат множине за дати локал.

_n(), _nx() – у зависности од прослеђеног броја враћа стринг за једнину или за множину.

Формат броја

Функција за форматирање броја користи глобалну варијаблу $wp_locale, како би број био правилно форматиран за дати локал (сепаратор за хиљаде и децимална тачка).

Нпр.

САД – 1,024.00

РС – 1.024,00

number_format_i18n() – не ставља се у функцију за интернационализацију али се враћена врдност може користити за приказ броја у склопу локализованог стринга.

Најчешћи пример у Вордпресу се може наћи у шаблону за коментаре (приказ броја коментара) где имамо примену функције за форматирање броја као и за препознавање једнине и множине:

printf(
	/* translators: 1: number of comments, 2: post title */
	_nx(
		'%1$s Reply to %2$s',
		'%1$s Replies to %2$s',
		get_comments_number(),
		'comments title',
		'radionica'
	),
	number_format_i18n( get_comments_number() ),
	get_the_title()
);

Формат датума и времена

Као и код форматирања броја, функција за локализовање датума и времена користи глобалну варијаблу $wp_locale у којој су, између осталог, сачувани називи месеци и дана у недељи за сваки локал.

date_i18n() – такође се користи ван функције за интернационализацију али може да проследи своју вредност једној таквој функцији.

Језичка целина

Приликом писања кôда и припреме за интернационализацију, веома је важно имати у виду да различити локали имају различиту језичку синтаксу и користи различит редослед речи у реченици за исказивање исте садржине.

Због овога је важно задржати логичну језичку целину у истом стрингу. Ово није проблем уколико не постоји динамичка вредност унутар целине, међутим, у ситуацијама када се динамичке вредности нађу унутар целине девелопери понекад прибегавају “лакшем” решењу и исцепкају целину на мање делове. Ово треба по сваку цену избегавати.

Како би се сачувала целина најчешће се користе следеће PHP функције: sprintf() и printf().

Алати за локализацију

Од бројних алата за локализацију који су данас доступни, у радионици смо се упознали са два: Poedit и Loco додатак.

Poedit је самостални алат и захтева добру припрему пре самог генерисања стрингова за превод. Уколико не знате које све функције и у ком формату треба да буду кориштене као кључне речи за претагу кôда, јако тешко ћете постићи потпуну локализацију.

У подешавањима кључне речи изгледају овако (све функције за интернационализацију које смо користили):

"X-Poedit-KeywordsList: __;_e;_x:1,2c;_ex:1,2c;_n:1,2;_nx:1,2,4c;_n_noop:1,2;_nx_noop:1,2,3c;esc_attr__;esc_html__;esc_attr_e;esc_html_e;esc_attr_x:1,2c;esc_html_x:1,2c\n"

Loco је додатак за Вордпрес који служи искључиво за локализацију. За разлику од осталих додатака, он посетиоцима веб места не даје могућност пребацивања садржаја на све доступне локале. Он приказује само онај локал који је изабран у контролној табли.

Међутим, оно што овај додатака издваја од осталих је могућност генерисања свих стрингова за превод и превођења директно из контролне табле. За овај додатак је довољно да само изаберете локал и он ће сам прегледати све функције.

Осим ових, постоје и напредни алати помоћу којих се могу генерисати датотеке за локализацију. Поменућемо два:

WP-CLI

wp i18n make-pot path/to/your-theme-directory

grunt-wp-i18n

Транслитерација

Српски језик је један од ретких који користи два писма, ћирилицу и латиницу. Како се транслитерација врши само из ћирилице у латиницу (обрнути смер даје грешке у многим ситуацијама), иницијални превод се врши на ћирилици.

Затим је транслитерацију могуће остварити путем додатака, ми смо користили SrbTransLatin али он није једини додатак који обавња ову функцију.

Датотеке

Постоје три врсте датотека које учествују у процесу локализације Вордпреса.

POT (Portable Object Template)

.pot – Генерише се из gettext функција у кôду. Ова датотека која садржи све стрингове за превођење, пронађене у теми, додатку или било којој претходно изабраној фасцикли. Стрингови су најчешће на енглеском језику.

Стринг из .pot датотеке:

#. 1: number of comments, 2: post title
#: template-localisation.php:182
#, php-format
msgctxt "comments title"
msgid "%1$s Reply to %2$s"
msgid_plural "%1$s Replies to %2$s"
msgstr[0] ""
msgstr[1] ""

PO (Portable Object)

.po – Генерише се из .pot датотеке и ова датотека која је њена скоро идентична копија. Разлика је у дефинисању специфичности локала: назив језика, форма множине и сл. У ову датотеку се, ручно или путем неког алата, уписује превод на жељени локал.

Горе наведени стринг али из .po датотеке за српски локал:

#. 1: number of comments, 2: post title
#: template-localisation.php:182
#, php-format
msgctxt "comments title"
msgid "%1$s Reply to %2$s"
msgid_plural "%1$s Replies to %2$s"
msgstr[0] ""
msgstr[1] ""
msgstr[2] ""

MO (Machine Object)

.mo – Генерише се из .po датотеке, потпуно је нечитљива људима и ово је заправо датотека коју Ворпрес чита и користи за локализацију. За ову датотеку је јако важно како је названа и њено име ће да зависи од фасцикле у којој се налази.

Локација и име .mo датотеке

Када се у контролној табли Вордпреса промени језик, истог тренутка се у фасцикли wp-content генерише languages фасцикла. Ту су све датотеке за локализацију свих тема и додатака пронађених у инсталацији Вордпреса а које је Вордпрес преузео са translate.wordpress.org. Теме и додаци овде имају своје засебне фасцикле а именовање датотека се врши према шеми:

ИМЕ-ТЕМЕ-ЛОКАЛ.mo (radionica-sr_RS.mo, radionica-sr_RS.po)

Уколико датотеке за локализацију одређене теме или додатка не постоје на translate.wordpress.org, Вордпрес ће покушати да их пронађе у корену теме, одн. додатка. У ово случају се изоставља назив теме/додатка из назива датотеке и остаје само ознака за локал (sr_RS.mo, sr_RS.po). Да бисмо могли на овај начин да користимо датотеке за локализацију, неопходно је омогућити локализацију у кôду.

load_theme_textdomain( 'radionica' );

Ради веће прегледности и боље организације, могуће је померити датотеке за локализацију у засебну фасциклу, најчешће languages. Да би ово функционисало неопходно је додати нову локацију у претходну функцију. Датотеке и овде задржавају само ознаку за локал у свом називу.

load_theme_textdomain( 'radionica', get_theme_file_path( '/languages' ) );

Комплетан код са радионице се може преузети са званичног налога Вордпрес Србија заједнице на Github-u.

У следећем термину се бавимо подршком теме за нови уређивач, познат под називом Гутенберг.

Радионице су бесплатне али је потребно пријавити се на Meetup групи Вордпрес Србија заједнице.