comment_form() – wszystko co powinieneś wiedzieć (cz.1)

W starszych wersjach WordPress (do 2.9) jedyną metodą na wstawienie formularza komentarzy było wpisanie całego kodu do pliku comments.php. Metoda ta była mało elastyczna, więc wraz z WordPress 3.0 wprowadzono funkcję comment_form(). W ten sposób ponad 40 linijek mieszanki kodu HTML, PHP oraz tekstów można zastąpić jedną linijką.

Oczywiście dodanie funkcji, nie oznacza, że poprzednia metoda wyszła z użycia. Wiele szablonów, również tych nowych, korzysta ze starszego rozwiązania. W takim przypadku cały kod niezbędny do wyświetlenia formularza znajduje się w pliku comments.php, gdzie można swobodnie edytować teksty, oraz HTML. Dla osób mniej „technicznych” może się to wydawać lepszym rozwiązaniem, ponieważ nawet bez znajomości PHP można stosunkowo łatwo samodzielnie wprowadzać drobne zmiany.

Korzystając z gotowych szablonów masz znikomy wpływ na to, z której metody skorzystał jego twórca. Jednak przy odrobinie cierpliwości, można ujarzmić również funkcję comment_form(), o czym przeczytasz poniżej.

W zależności od tego jak bardzo potrzebujemy ingerować w formularz komentarzy, mamy do dyspozycji dwie podstawowe metody:

• poprzez wywołanie funkcji comment_form() z odpowiednimi argumentami, lub
• korzystając z dostępnych filtrów i akcji.

W tym wpisie skupię się na pierwszej z wymienionych metod.

Argumenty

Podstawowy sposób wywołania funkcji comment_form() nie wymaga podawania żadnych parametrów.

<?php comment_form(); ?>

Wywołanie w ten sposób sprawi, że wyświetlony zostanie formularz komentarzy z domyślnymi ustawieniami.

Funkcję można również wywołać z parametrami:

<?php comment_form($args, $post_id); ?>

$post_id jest ID wpisu dla którego wyświetlany jest formularz. Domyślnie jest to aktualny wpis, więc w większości zastosowań nie ma potrzeby podawania tego parametru.
$args jest tablicą argumentów, za pomocą których kontrolujemy formularz. Jest to zatem klucz do wprowadzania zmian w formularzu i właśnie na argumentach skupimy się tej chwili.

fields

Jest to argument który zawiera tablicę standardowych pól formularza – podpis, email i strona www.
Domyślna wartość:

$commenter = wp_get_current_commenter();
$req = get_option( 'require_name_email' );

comment_form(
	array(
		'fields' => array(
					'author' => '<p class="comment-form-author">' . '<label for="author">' . __( 'Podpis' ) . '</label> ' . ( $req ? '<span class="required">*</span>' : '' ) . '<input id="author" name="author" type="text" value="' . esc_attr( $commenter['comment_author'] ) . '" size="30" /></p>',
					'email' => '<p class="comment-form-email"><label for="email">' . __( 'E-mail' ) . '</label> ' . ( $req ? '<span class="required">*</span>' : '' ) . '<input id="email" name="email" type="text" value="' . esc_attr(  $commenter['comment_author_email'] ) . '" size="30" /></p>',
					'url' => '<p class="comment-form-url"><label for="url">' . __( 'Strona WWW' ) . '</label>' . '<input id="url" name="url" type="text" value="' . esc_attr( $commenter['comment_author_url'] ) . '" size="30" /></p>',		)
	)
);

W tym przykładzie wywołałam funkcję comment_form() z argumentem fields. Powyższy kod możesz wykorzystać, jeśli potrzebujesz dokonać zmian w kodzie HTML (np. zamienić element p na div lub dodać własną klasę), albo zmienić opis pól.

Możliwe jest również dodanie dodatkowego pola, jednak jest to już bardziej złożone zagadnienie. Jeśli chcesz się dowiedzieć więcej na ten temat, zapraszam do lektury mojego wpisu gościnnego na blogu wpninja.pl, pt. „Dodatkowe pola w formularzu komentarzy WordPress”.

comment_field

Ten argument pozwala na manipulację kodem odpowiedzialnym za wyświetlanie pola tekstowego przeznaczonego na treść komentarza. Tak jak argument fields pozwala na ingerencję w kod HTML oraz zmianę opisu. Domyślna wartość:

comment_form(
	array(
		'comment_field' => '<p class="comment-form-comment"><label for="comment">' . _x( 'Komentarz', 'noun' ) . '</label><textarea id="comment" name="comment" cols="45" rows="8" aria-required="true"></textarea></p>'
		)
);

must_log_in

Argument odpowiedzialny za tekst oraz HTML wyświetlany użytkownikom niezalogowanym, jeśli dodawanie komentarzy wymaga logowania. Domyślna wartość:

<?php
comment_form(
	array(
		'must_log_in' => '<p class="must-log-in">' .  sprintf( __( 'Musisz się <a href="%s">zalogować</a>, aby móc dodać komentarz.' ), wp_login_url( apply_filters( 'the_permalink', get_permalink( ) ) ) ) . '</p>'
		)
);
?>

logged_in_as

Argument odpowiedzialny za wyświetlanie komunikatu dla zalogowanych użytkowników, z linkami do profilu użytkownika oraz do wylogowania. Domyślna wartość:

<?php
comment_form(
	array(
		'logged_in_as' => '<p class="logged-in-as">' . sprintf( __( 'Zalogowano się jako <a href="%1$s">%2$s</a>. <a href="%3$s" title="Wyloguj się z tego konta">Wylogować się?</a>' ), admin_url( 'profile.php' ), $user_identity, wp_logout_url( apply_filters( 'the_permalink', get_permalink( ) ) ) ) . '</p>'
		)
);
?>

comment_notes_before

Argument, dzięki któremu możesz dodać własny komunikat dla nie zalogowanych użytkowników, wyświetlany tuż nad formularzem. Domyślnie zawiera on informację o tym, że adres email nie zostanie opublikowany a pola wymagane są oznaczone gwiazdką. Domyślna wartość:

<?php
comment_form(
	array(
		'comment_notes_before' => '<p class="comment-notes">' . __( 'Twój adres e-mail nie zostanie opublikowany.' ) . ( $req ? $required_text : '' ) . '</p>'
		)
);
?>

Jeśli nad formularzem nie chcesz wyświetlać żadnego komunikatu, możesz to zrobić korzystając z poniższego fragmentu:

<?php
comment_form(
	array(
		'comment_notes_before' => ''
		)
);
?>

comment_notes_after

Jest to argument który odpowiada za komunikat wyświetlany pod formularzem, tuż pod polem tekstowym a nad przyciskiem publikacji. Domyślnie zawiera informacje o tagach HTML, które można wykorzystywać w treści komentarza. Domyślna wartość:

<?php
comment_form(
	array(
		'comment_notes_after' => '<p class="form-allowed-tags">' . sprintf( __( 'Możesz użyć następujących tagów oraz atrybutów <abbr title="HyperText Markup Language">HTML</abbr>: %s' ), ' <code>' . allowed_tags() . '</code>' ) . '</p>'
		)
);
?>

Tego komunikatu również można się pozbyć, postępując analogicznie jak w przypadku comment_notes_before.

id_form

Argument, który pozwalają na dodanie własnego atrybutu ID do elementu form.
Domyślna wartość:

<?php
comment_form(
	array(
		'id_form' => 'commentform'
		)
);
?>

id_submit, label_submit

Atrybuty, które pozwalają na manipulację przyciskiem publikacji komentarza.
id_submit pozwala zdefiniować własny atrybut ID dla elementu przycisku, natomiast label_submit pozwala zmienić tekst na przycisku. Domyślne wartości:

<?php
comment_form(
	array(
		'id_submit' => 'submit',
		'label_submit' => __( 'Opublikuj komentarz' )
		)
);
?>

title_reply

Tekst nagłówka wyświetlanego nad formularzem (i nad komunikatem comment_notes_before) – jego tutł.
Domyślna wartość:

<?php
comment_form(
	array(
		'title_reply' => __( 'Dodaj komentarz' )
		)
);
?>

title_reply_to oraz cancel_reply_link

Przy włączonej opcji zagnieżdżonych komentarzy, komentujący ma możliwość udzielenia odpowiedzi na konkretną wypowiedź. W takim przypadku można nieco zmienić tekst nagłówek nad formularzem.
W trakcie pisania odpowiedzi do komentarza, wyświetlany jest link pozwalający na anulację odpowiedzi. Jego treść możemy zmienić za pomocą argumentu cancel_reply_link.
Domyślne wartości:

<?php
comment_form(
	array(
		'title_reply_to' => __( 'Dodaj komentarz do %s' ),
		'cancel_reply_link' => __( 'Anuluj pisanie odpowiedzi' )
		)
);
?>

Zastosowanie

Funkcję comment_form() można wywołać z dowolną kombinacją podanych powyżej argumentów, na przykład tak:

<?php
comment_form(
	array(
		'label_submit' => __('Wyślij'),
		'title_reply' => __('Co o ty tym myślisz?')
	)
);
?>

Dla wszystkich pozostałych argumentów, użyte zostaną ich wartości domyślne, które podawałam przy każdym z nich. Informacje na ten temat znajdziesz również w oficjalnej dokumentacji.
We wszystkich przykładach podaję domyślne komunikaty i teksty po polsku (dla WordPress w wersji polskiej).

Podsumowanie

Myślę, że mając taką ściągę z łatwością zapanujesz nad swoim formularzem komentarzy. W części drugiej przeczytasz o nieco bardziej zaawansowanych zagadnieniach, czyli o wprowadzaniu zmian poprzez filtry i akcje.

Related posts:

1. comment_form() – wszystko co powinieneś wiedzieć (cz.2)