Ср. Окт 16th, 2019

Ещё один сайт на WordPress

Требования Envato к написанию и оформлению кода

Требования Envato к написанию и оформлению кода

Эта статья частично является переводом статьи Envato WordPress Theme Coding Requirements. В отличие от оригинала, она дополнена многими разъяснениями, которые будут понятны русскоязычному читателю.

Общие требования

Файлы темы не должны включать неиспользуемые фрагменты кода: закомментированный код; закомментированный список задач или руководство как что-то сделать; или любые другие комментарии, которые не способствуют пониманию кода.

Темы не должны каким-либо образом запутывать или скрывать код, в том числе с использованием кодировки base64.

Как правильно указывать название файлов, классов, хуков и т.д.

Требования Envato к написанию и оформлению кода

— Префиксы обязательно

Чтобы избежать конфликтов с плагинами и другими темами, для каждого названия файла темы, скрипта/стилей, классы/идентификаторы должен использоваться уникальный префикс.

Ниже приведен список элементов, которые должны иметь уникальные префиксы. Но, такие файлы, или код нужно создавать лишь в том случае, если подобной функции нет в движке WordPress.

Что это означает? Вы не имеете права создавать свою функцию вывода меню или сайдбара, или любого другого элемента или решения, если она уже есть в движке WordPress. Если в WordPress таких функций или решений нет, то подобные решения должны иметь свое уникальное название, чтобы в случае чего, не конфликтовать с другими уникальными функциями из файлов темы или плагинов:

  • Функций
  • Классов
  • WordPress хуков
  • общедоступных / глобальных переменных (public/global variables)
  • хуков действий / фильтров (action/filter hooks)
  • пользовательских размеров изображений
  • констант
  • записей базы данных
  • специфичных для темы скриптов и специфичных для темы стилей

Другими словами, используем стандартные WordPress-функции, если их предоставляет движок WordPress, если нет, то делаем свои, но с соблюдением уникального названия для: файлов, классов, хуков; содержащих код.

Как правильно назвать: файлы, функции, хуки и т.д.

Требования Envato к написанию и оформлению кода

В требованиях Envato указано, что префиксы в названиях должны состоять из: themename_, authorname_ или frameworkname_. Что это значит? Ваша тема называется “cooltheme”, а функция называется post_views() , в таком случае ее нужно переименовать в — cooltheme_post_views()

Допускается использование нескольких префиксов (тематических, каркасных и внешних библиотек PHP), они должны быть непротиворечивыми, не менее трех символов и уникальными (т.е. не использовать общий термин, к примеру — «seo»).

К примеру, наша тема называется firefly. Ниже, вы можете ознакомится, как должны выглядеть названия: функций, классов, переменных и т.д.

— Имена функций:

x

v

— Имена классов:

x

v

— Глобальные переменные:

x

v

— Экшены:

x

v

— Фильтры:

x

v

— Подключение скриптов:

x

v

— Подключение стилей:

x

v

— Названия размеров изображений:

Разрешено нижнее подчеркивание или дефис

x

v

! Убедительная просьба не копировать код из этой статьи и вставлять в свою тему. Прошу это исключительно из-за того, что в данном коде есть примеры правильного названия, и все. Если в коде есть ошибки или устаревшие функции, скопировав их к себе, виновниками в неправильной работе темы или ошибках, будете только вы. Я предупредил 😊

Сторонние скрипты

Сторонние скрипты/стили не должны иметь префикс или суффикс, чтобы избежать двойной загрузки. К примеру случайно могут быть загружен скрипт в теме с одним именем, и случайно с таким же именем скрипт из плагина:

Зарезервированные префиксы для имен файлов

Префикс wp_ зарезервирован только для основных функций, предоставляемых движком WordPress, и не должен быть использован в теме. Кроме того префиксы никогда не должны начинаться с нижнего подчеркивания или дефиса. Другими словами, нельзя создать функцию и называть ее wp_function_name(). Префикс wp_ не используем.

Загружаемые файлы

В теме не должны присутствовать при подключении файлов жестко-закодированные URI.
К примеру, стили должны подключаться только через ф-цию в файле functions.php —

, а не через следующий код в head сайта:

Все вспомогательные функции, которые предоставляет движок WordPress, должны использоваться там, где это возможно.

Подключение стилей/скриптов в дочерних темах

Рекомендуется использовать следующие функции WordPress 4.7+, поскольку они значительно улучшают дочерние темы темы:

Также следующую функцию следует использовать, вместо устаревших: basename, dirname, pathinfo:

x (используется dirname):

v

Еще примеры

x

v

Подключение стилей CSS

Все стили css добавляются на сайт только через функцию wp_enqueue_style();

Подключение скриптов JS

Все скрипты js добавляются на сайт только через функцию wp_enqueue_script();

Темы обязаны использовать скрипты подключаемые через WordPress, вместо того, чтобы включать свою собственную копию скриптов или использовать копию скриптов из CDN. Это касается подключения: jQuery, jQuery UI, Backbone, Underscore.

Если в тему включена версия библиотеки из CDN (разрешено, только если данная библиотека не поставляется движком WordPress), локальная копия библиотеки должна быть предоставлена в качестве запасного варианта. Другими словами код должен выглядеть соответствующим образом — если библиотека подключается через CDN, но на сервере сбой и библиотека не будет подключена, чтобы загружалась локальная версия из WordPress.

Все активные скрипты должны быть загружены в тему с использованием SSL-дружественного протокола(https://). Активные скрипты и стили должны быть выведены через следующие функции get_template_directory_uri () и get_stylesheet_directory_uri (). В этих функциях автоматически используется SSL-протокол.

Если скрипты (js) или стили(css) подключаются из внешних ресурсов, тема должна использовать is_ssl() или использовать формат протокола только //example.com/file.js, вместо http://example.com/file.js.

Важно: Авторы тем должны быть уверены в том, что каждый файл стилей или скриптов, загружаемый темой, будет загружаться только на той странице, на которой он используется.

Комбинированные скрипты

Сторонние скрипты и библиотеки не должны сочетаться. Они должны быть поставлены в индивидуальном порядке, чтобы обеспечить следующие условия:

  • Они не должны загружаться повторно(к примеру через плагин)
  • Владелец темы или возможно пользователь могут отменить регистрацию скриптов, если это необходимо

Загрузка шрифтов

Требования Envato к написанию и оформлению кода

При подключении шрифтов к теме запрещено использовать @Import, так как эти блоки загружаются параллельно и замедляют загрузку веб-страницы. Вместо этого шрифты должны загружаться через функцию wp_enqueue_style()

Если подключаются шрифты Google Fonts

В тему должны подключаться только те шрифты, которые будут использованы. Кроме этого код подключения шрифтов должен содержать в себе только те виды «насыщенности» шрифтов, которые также будут использованы.

В этом примере загружается только шрифт Inconsolata с насыщенностью шрифта 700:

Если подключается несколько видов шрифтов Google Fonts, то они должны подключаться через один HTTP запрос, используя вертикальный разделитель, как это показано в примере ниже:

Тема не должна включать раскрывающийся список шрифтов Google Fonts в настройках, так как это может запутать пользователей.

Также подумайте о выборе количества и комбинаций шрифтов, которые будут соответствуют дизайну темы.

WordPress код

Требования Envato к написанию и оформлению кода

Файлы темы не должны содержать устаревшие теги или функции.

Наличие следующих функций обязательно:

Тема должна позволять WordPress добавлять и управлять тегом

. Это становится возможным благодаря функции adding add_theme_support( ‘title-tag’ );, которая добавляется в файл functions.php, вместо использования wp_title() в head сайта.

Если в теме подключаются пользовательские файлы шаблонов, они должны подключаться через функции get_template_part() или locate_template(). К примеру:

Все файлы и директории WordPress темы, должны быть названы, используя символы нижнего регистра (с маленькой буквы, никаких заглавных). Слова должны быть отделены друг от друга только дефисом. Никаких верблюжихГорбов или нижних подчеркиваний. К примеру — front-page.php.

Следующие имена файлов, должны использоваться в теме там, где это необходимо:

Тема не должна добавлять никаких записей в админ-бар и не должна ничего удалять, прятать, или так или иначе блокировать админ-бар от отображения.

Переменная $content_width должна быть использована для определения максимальной допустимой длины для изображений, видео и других файлов отображаемых внутри темы. Эта функция подключается в файле functions.php

Темы не должны удалять любые фильтры добавляемые движком WordPress, к примеру: wpautop, wptexturize, и другие.

Стандартные css-классы WordPress должны быть указаны и оформлены в файле стилей. Примеры таких классов, можно посмотреть по следующей ссылке:

WP_Filesystem методы должны использоваться там, где они доступны, вместо прямых вызовов файловой системы PHP. К примеру: mkdir, fopen, fread, fwrite, fputs, и т.д. не должны быть использованы.

PHP код

Требования Envato к написанию и оформлению кода

Чтобы избежать ошибок, настоятельно рекомендуется следовать стандарту кода PHP для WordPress

Темы не должны содержать никаких PHP уведомлений, замечаний или ошибок. Чтобы избежать подобных проблем, включите в wp-config.php функцию WP_DEBUG, переведя ее до состояния true, и исправьте все ошибки в теме, если будут.

Команда create_function() перестала быть задействованной с версии PHP 7.2.0. и больше не используется.

Оператор «@» не должен использоваться для подавления сообщений об ошибках или уведомлений.

Не допустимо использовать PHP шорттеги

Для отступов в коде всегда используйте отступы через табы (Tabs), а не через пробел. Так код выглядит более легким и читабельным согласно Стандарту WordPress PHP Coding Standards.

В примере ниже можно заметить отступ в 1 таб или 4 пробела. Но если сказано про табы, то лучше не нарушать. Вам же больнее будет. Ситуация глупая, но при случае искать во всех стандартах из-за чего дали Hard Reject не особо приятно. Поверьте.

Пример:

Единственное исключение составляет похожий код, когда идет несколько переменных со значениями. В этом случае от самого длинного названия переменной ставим 1 пробел, и 1пробел после знака равенства. Все остальные переменные подгоняем под отступы от самого длинного названия. Чтобы знаки равенства (к примеру), выглядели на всех строчках одинаково, как в примере ниже. Самое длинное имя переменной [tab]$foo34, от нее и отталкиваемся.

Еще похожий пример:

Темы не должны включать код для поддержки PHP4. К примеру, темы недолжны использовать оператор &$this во время вызова add_action. Для большего понимания ситуации, читайте https://tomjn.com/2014/01/08/this/

Ссылки на PHP (т. е. Использование &) следует избегать, если это не является абсолютно необходимым.

Пример:

Чтобы не запутаться в собственном коде и не запутать проверяющих, просят такого не делать. Но в случае крайней необходимости делайте. Не забудьте указать в комментарии, почему такое решение было необходимо.

Не допустимо использовать глобальную PHP-переменную. Только в случае абсолютной необходимости, и если надумаете использовать, укажите правильное имя переменной. Про имена и префиксы читайте выше. Но когда будете проверять тему через плагин Envato Theme Check, он выдаст предупреждение.

Если используете конструкцию операторов if else, то обязательно с фигурными скобками. Рекомендуется в файлах шаблона использовать другую конструкцию. См пример ниже:

Не используйте:

Используйте:

В файлах шаблона можете использовать эту конструкцию:

Функция eval() не должна использоваться.

PHP версия

Темы должны уметь работать с последней версией PHP. Не существует обязательной минимальной поддерживаемой версии PHP, но:

  • Решение о том, какие версии поддерживать, должно приниматься с учетом статистики;
  • Требования должны быть понятны клиентам, чтобы избежать неудовлетворенности.

Требования Envato к написанию и оформлению кода

HTML/CSS код

Требования Envato к написанию и оформлению кода

Стили CSS не должны быть жестко вставлены где угодно в теме, либо встроены в тег

.

Все динамические стили CSS, кроме файла style.css, должны быть подключены через функцию wp_add_inline_style() в файле functions.php. Исключением является добавление фонового изображения к элементу. В этом случае будет разрешается следующее:

Любые другие стили для этого же элемента, такие как: background-size: cover; должны быть подключены через функцию wp_add_inline_style().
Динамические стили должны быть прикреплены к соответствующим таблицам стилей, чтобы предотвратить загрузку CSS там, где он не нужен. К примеру стили для WooCommerce должен содержаться в файле стилей woocommerce-inline-styles, а не в основном файле стилей.

Все классы и id должны быть названы соответствующим образом, исходя из назначения блока, и быть названными согласно стандарту BAM (в англ статье указано naming convention). Если к примеру возьмем блок с логотипом из блока header, то назван он должен быть соответствующе:

Если это блок с изображением логотипа

Код в файле стилей должен иметь удобную и хорошую читабельность, чтобы покупатель, смог зайти, разобраться в коде и подкорректировать если ему это будет нужно.

Требования Envato к написанию и оформлению кода

Начало файла стилей CSS — style.css, должно начинаться с закоментированной информации вверху файла: название темы, описание, об авторе, ссылка на страничку автора, теги и т.д. Также должно быть указано содержание файла стилей «TABLE OF CONTENTS», и если я скопирую название интересующего стиля, и попробую через CTRL+F поискать его на странице стилей, он должен быть найден. То есть содержание файла стилей вверху, должно иметь одинаковое название с элементами в самом содержании этого файла.

Ниже примеден пример верхушки файла стилей:

Каждый селектор должен быть назван так, чтобы пользователю было с названия понятно, где его можно найти на странице, и что в нем заключено.

Используйте следующий стиль синтаксиса — .container, вместо div.container.

Когда используете селекторы CSS для манипуляции элементами, то убедитесь в том, что только нужный элемент подлежит манипуляциям.
Например, при применении CSS к элементам jQuery, добавленным на страницу, вы должны убедиться, что все элементы jQuery, которые могут быть добавлены другим элементом, не затронуты.

И напоследок, проверьте весь код по валидатору W3. Не должно быть никаких ошибок и грубых замечаний. Как показала практика, даже в идеально-чистом коде могут быть замечания. К примеру валидатор не пропускает и жалуется на виджет календаря, так как в нем некоторые блоки имеют идентификатор id, и если его добавить несколько раз, возникает ошибка.

Кроме того валидатор жалуется на устаревший атрибут type=»text/css» и type=»text/javascript»

JavaScript код

Требования Envato к написанию и оформлению кода

JavaScript код должен располагаться во внешний файлах, когда это возможно.

Внешние JavaScript файлы должны быть правильно поставлены в очередь.

Если требуется, чтобы переменные PHP находились в коде JavaScript, тогда используйте функцию wp_localize_script().

Все файлы JavaScript обязаны быть подключены через футер, используя параметр $in_footer в функции wp_enqueue_script(), кроме тех случаев, когда необходимо разместить код в head страницы для его корректной работы.

Не должно быть никаких замечаний или ошибок в коде (проверять через консоль разраб. в браузере) и через сайт jshint.com.

Не использовать функцию eval().

Если используете jQuery, в таком случае вместо прямых функций .click(), .bind(), .hover() использовать .on().

Необходимо использовать strict mode для всего кода JavaScript. Ниже приведен пример с jQuery:

Резервные события не должны использоваться. Например, нет необходимости в нескольких событиях $(document).ready() или $(window).load().

Код разработки и отладки, такой как console.log(), должен быть удален.

Перевод темы

Требования Envato к написанию и оформлению кода

Интернационализация темы

Все текстовые строки темы, которые должны и могут быть переведены, должны быть обернуты в специальную функцию, позволяющую перевести именно данный текст, и правильно отображены, чтобы текстовые элементы темы могли быть переведены без изменения оригинального кода родительской темы.

Переменные для перевода

Все текстовые строки темы, которые должны и могут быть переведены, не должны содержать переменных или констант, так как динамический контент не может быть переведен. Вместо этого, используйте функцию семейства printf с плейсхолдером или заменой PHP аргументов (для нескольких переменных).

Домен перевода (текстовый домен)

Константы, переменные или определения не должны быть использованы в качестве текстового домена (домена перевода) темы. Текстовый домен должен использовать предпочтительнее тире чем нижнее подчеркивание, и быть написан с букв нижнего регистра (первая маленькая, остальные тоже).

Рекомендуется текстовый домен сделать таким, как название темы, чтобы нести в себе уникальность. Если тема называется firefly или Firefly(с большой буквы), то текстовый домен должен быть firefly.

Нерелевантные текстовые домены:

Текстовые домены, не связанные с названием темы или темой, не допускаются и должны быть удалены. Упакованные PHP-библиотеки (например, TGMPA), фреймворки и текстовые домены шаблонов плагинов являются релевантными и поэтому разрешены.

Файл перевода:

Файл локализации должен быть на английском языке и доставлен в виде файла .pot. Файл .pot должен иметь название темы и текстового домена. Файл .pot будет содержать все строки перевода. Имя файла .pot должно соответствовать теме-слагу (то есть firefly.pot).

Темы могут включать в себя конкретные файлы перевода (.po /.mo) для любого из выбираемых языков сайта (выбирается в настройках), но среди них не должно быть файлов en_US.mo или en_US.po, потому что английский уже подразумевается.

То есть, если тема переведена только на русский, может быть ru_RU.mo и ru_RU.po, но версия перевода для английского языка быть не должно.
В файле темы будет 3 файла: файл .pot и файлы ru_RU.mo и ru_RU.po. Теме не требуются файлы en_EN.mo и en_EN.po. Без них и так будет 2 перевода: английский (оригинальный, от которого пойдут все дальнейшие переводы) и русский, благодаря файлам ru_RU.mo и ru_RU.po.

Убедитесь, что файл перевода .pot обновлен и включает в себя абсолютно все функции для перевода темы. Наличие устаревшего файла .pot (к примеру если автор забыл доперевести некоторые элементы) ограничивает возможности перевода темы для любых языков, что негативно скажется на международных клиентах.

Рекомендуется, если есть возможность перевода темы, сделать поддержку письма справо на лево.

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *

Copyright © All rights reserved. | Newsphere by AF themes.