Функция cot_rc_link в Cotonti

Разберём функцию cot_rc_link подробно, с объяснением её назначения, использования, рекомендаций и комментариями.

Назначение функции

Функция cot_rc_link предназначена для быстрого формирования HTML-ссылки <a>. Она принимает URL, текст внутри тега и дополнительные атрибуты, создавая корректный HTML-код.

Разбор параметров функции
$url

Тип: строка.
Это обязательный параметр, указывающий ссылку (href) для тега <a>.

$text

Тип: строка.

Это текст или содержимое внутри HTML-тега <a>.

$attrs

Тип: строка или ассоциативный массив.
Этот параметр используется для задания дополнительных атрибутов ссылки, например class, id, target и других.
Если передаётся строка, она добавляется к тегу как есть. Если передаётся массив, то атрибуты преобразуются в строку с помощью вспомогательной функции cot_rc_attr_string.

Пример работы функции cot_rc_link

Пример 1: Минимальная ссылка

echo cot_rc_link('https://example.com', 'Click here');

Результат:

<a href="https://example.com">Click here</a>

Пример 2: Ссылка с дополнительными атрибутами (строка)

echo cot_rc_link('https://example.com', 'Visit', 'class="btn btn-primary" target="_blank"');

Результат:

<a href="https://example.com" class="btn btn-primary" target="_blank">Visit</a>

Пример 3: Ссылка с атрибутами (массив)

echo cot_rc_link('https://example.com', 'Learn More', ['class' => 'btn btn-secondary', 'target' => '_blank']);

Результат:

<a href="https://example.com" class="btn btn-secondary" target="_blank">Learn More</a>

Рекомендации по применению
Используйте для создания динамических ссылок.
Функция удобна, если ссылки или их параметры формируются программно.

Безопасность.

Все атрибуты и значения автоматически преобразуются в безопасный HTML-код благодаря функции cot_rc_attr_string.
Убедитесь, что параметры $url и $text безопасны и не содержат нежелательных данных.
Преимущество массивов.
Рекомендуется использовать массив для атрибутов, так как это упрощает их управление и добавление.

Комментарии внутри кода функции cot_rc_link

/**
 * Быстрая генерация HTML-ссылки
 *
 * Функция принимает URL, текст ссылки и дополнительные атрибуты,
 * формирует тег <a> с корректной HTML-структурой.
 *
 * @param string $url Ссылка (атрибут href)
 * @param string $text Текст внутри тега <a>
 * @param string|array<string, string> $attrs Дополнительные атрибуты в виде строки или массива
 * @return string HTML-код ссылки
 */
function cot_rc_link($url, $text, $attrs = '')
{
    // Преобразуем дополнительные атрибуты в строку с помощью cot_rc_attr_string
    $link_attrs = cot_rc_attr_string($attrs);

    // Формируем HTML-код ссылки
    return '<a href="' . $url . '"' . $link_attrs . '>' . $text . '</a>';
}

Пример применения функции cot_rc_link

Разберём выражение с вызовом функции cot_rc_link в контексте логики PHP-фреймворка Cotonti.

Выражение:

'FORUMS_TOPICS_TITLE_TOPICS' => cot_rc_link($title_urls['title'], Cot::$L['forums_topics'].' '.cursort($o == 'title', $w), 'rel="nofollow"'),

1. Назначение выражения
Это выражение создаёт HTML-ссылку с помощью функции cot_rc_link. Оно используется в шаблонах или ресурсах Cotonti для динамической генерации ссылок на разделы, темы, страницы и т.д. В данном случае ссылка формируется для заголовков тем форума.

2. Разбор параметров функции cot_rc_link

Функция cot_rc_link принимает три параметра:

cot_rc_link($url, $text, $attrs);

2.1 $url
Переданное значение:

$title_urls['title']
Это URL для ссылки.

Переменная $title_urls['title'] скорее всего содержит адрес темы или раздела форума, сформированный заранее.
Обычно такие ссылки генерируются через функции Cotonti, например cot_url, которая формирует безопасный и корректный URL на основе маршрута и параметров.

2.2 $text
Переданное значение:

Cot::$L['forums_topics'].' '.cursort($o == 'title', $w)
Cot::$L['forums_topics']

Это элемент языкового файла, содержащий текстовый ресурс.
В данном случае это строка, соответствующая "Темы форума" или её переводу на выбранный язык сайта.
cursort($o == 'title', $w)

Это вызов функции cursort, которая динамически добавляет символ сортировки (например, стрелки вверх или вниз) рядом с текстом заголовка.

Аргументы:
$o == 'title' проверяет, выбрана ли сортировка по названию.
$w указывает направление сортировки (например, ASC или DESC).
Итоговый текст ссылки будет, например:

"Темы форума ↑" или "Темы форума ↓"

2.3 $attrs
Переданное значение:

'rel="nofollow"'

Это строка с дополнительными HTML-атрибутами.
Атрибут rel="nofollow" сообщает поисковым системам, что эта ссылка не должна передавать "вес" (значимость) страницы, на которую она указывает.
Используется для предотвращения спама и управления SEO.

3. Итоговое выражение
Собранное выражение вызова функции:

cot_rc_link($title_urls['title'], Cot::$L['forums_topics'].' '.cursort($o == 'title', $w), 'rel="nofollow"');

Результат:
HTML-код ссылки с динамическим URL, текстом и атрибутами:

<a href="URL_ТЕМЫ" rel="nofollow">Темы форума ↑</a>

4. Подробные комментарии в коде

Добавим разъясняющие комментарии для начинающих.

'FORUMS_TOPICS_TITLE_TOPICS' => cot_rc_link(
    // URL ссылки (обычно сгенерирован заранее)
    $title_urls['title'],
    
    // Текст внутри ссылки
    // Берётся из языкового ресурса + символ сортировки
    Cot::$L['forums_topics'] . ' ' . cursort($o == 'title', $w),
    
    // Дополнительные атрибуты для тега <a>
    // В данном случае используется "nofollow" для SEO
    'rel="nofollow"'
),

 

5. Рекомендации по использованию
Динамическая генерация ссылок.
Используйте cot_rc_link в случаях, когда URL или текст ссылки формируются программно.

Языковые ресурсы.
Обязательно подключайте текстовые ресурсы через Cot::$L для поддержки мультиязычности.

SEO-атрибуты.
Добавляйте rel="nofollow" для ссылок, которые не должны передавать значимость (например, ссылки на внешние ресурсы или динамические страницы).

Сортировка.
Если требуется отображать направление сортировки (как в данном примере), используйте функцию cursort или её аналоги.