Створюємо кастомний WordPress-віджет для Twitter своїми руками

Немає потреби особливо представляти TwitterТому що сьогодні цей соціальний сервіс допомагає достукатися до найширшої аудиторії не тільки людям, а й компаніям. Помістити стрічку своїх твітів у блог чи на сайт можна досить просто. На цьому посту ми розберемося, як самому створити свій віджет Twitter і додати його на сайт.

Що ми матимемо?

Результатом наших зусиль стане віджет для WordPress, який можна помістити в бічну панель. Так, ваші відвідувачі зможуть бути завжди в курсі ваших новин та цікавих посилань з мікроблогу. Нижче скріншот покаже вам, як це виглядає в дії.

Умови використання Twitter

Оскільки цей віджет налаштовується користувачем, ви самі контролюєте, що і як відображатиметься. Почитайте вимоги самого Twitter: "Developer Display RequirementsДеякі з цих правил для простоти можна проігнорувати, але ви все ж таки не зловживайте.

Врахуйте, що вимоги треба виконувати в повному обсязі, бо інакше ризикуєте виявитися заблокованим у цьому соціальному сервісі, і тоді ваш віджет взагалі нічого не показуватиме.

Крок 1. Створюємо додаток для Twitter

Перш ніж приступити до написання коду, розберемося з тим, як працює API Twitter. Весь процес роботи описаний на відео, яке Ви бачите нижче:

Якщо ви не хочете дивитися відео, то ось вам коротко про основні кроки, які треба зробити:

1. Заходимо в Twitter - розділ для розробників.
2. Переходимо до секції "Мої програми", клікнемо на "Створіть новий додаток".
3. Заповнюємо обов'язкові поля, приймаємо правила надання послуг та натискаємо на кнопку "Створіть свою програму TwitterПоле зворотної веб-адреси вам не потрібно, тому можна залишити це поле порожнім.
4. Після створення програми натискаємо кнопку "Створити мій маркер доступу".
5. От і все! Пізніше вам знадобляться такі дані:
   • consumer key
   • consumer secret
   • маркер доступу
   • access token secret

Крок 2. Додаємо деталі до додатку

Щоб швидко додати опції до нашої теми, будемо використовувати налаштувач тим, який є починаючи з WordPress 3.4.

Щоб забезпечити швидкий доступ до налаштування теми, радимо використовувати наступний сніпет:

add_action ('admin_menu', 'my_theme_customizer');
function my_theme_customizer() {
	add_theme_page(
		__( 'Customize Theme Options', THEMENAME ),
		__( 'Customize Theme', THEMENAME ),
		'edit_theme_options',
		'customize.php'
	);
}

Додавши наведений вище код файлу functions.php, буде створено посилання на налаштувач у секції "Зовнішній вигляд" панелі керування сайтом. Для додавання опцій потрібно створити клас. Додаємо файл під назвою MyCustomizer.class.php у папку теми, в ньому розміщуємо наступний код:

<?php
class MyCustomizer {
	public static function register ( $wp_customize ) {

		/** Sections **/
		$wp_customize->add_section( 'twitter_api' , array(
			'title'    => __( 'Twitter API Details', 'mytextdomain' ),
			'priority' => 10,
		));

		/** Settings **/
		$wp_customize->add_setting( 'twitter_consumer_key' );
		$wp_customize->add_setting( 'twitter_consumer_secret' );
		$wp_customize->add_setting( 'twitter_access_token' );
		$wp_customize->add_setting( 'twitter_access_token_secret' );

		/** Controls **/
		$wp_customize->add_control(
			'twitter_consumer_key',
			 array(
				'label' => __( 'Consumer Key', 'mytextdomain' ),
			 	'section' => 'twitter_api',
				'priority' => 10,
			 )
		);
		$wp_customize->add_control(
			'twitter_consumer_secret',
			 array(
				'label' => __( 'Consumer Secret', 'mytextdomain' ),
			 	'section' => 'twitter_api',
				'priority' => 20,
			 )
		);
		$wp_customize->add_control(
			'twitter_access_token',
			 array(
				'label' => __( 'Access Token', 'mytextdomain' ),
			 	'section' => 'twitter_api',
				'priority' => 30,
			 )
		);
		$wp_customize->add_control(
			'twitter_access_token_secret',
			 array(
				'label' => __( 'Access Token Secret', 'mytextdomain' ),
			 	'section' => 'twitter_api',
				'priority' => 40,
			 )
		);
   }
}
add_action( 'customize_register' , array( 'MyCustomizer' , 'register' ) );
?>

Пару зауважень щодо наведеного вище коду. Всі ці дані потрібні для налаштування класу. Клас реєструється фрагментом коду у нижній частині блоку.

Ось три важливі дії, які треба виконати:

1. Створюємо нову секцію, щоб усі опції поєднати в одну логічну групу. Для цього використовуємо функцію add_section(), щоб додати заголовок.
2. Потрібно передати в WordPress дані про конкретні налаштування. Для цього використовується функція add_setting, яку також можна вказати як параметр за промовчанням.
3. І щоб зв'язати налаштування з керуванням з боку користувачів, потрібно застосувати низку параметрів. Тут створимо блок та на основі функції add_control() вкажемо ті налаштування, які потрібно змінити.

Зверніть увагу на пріоритет налаштування деяких елементів. Саме тому важливим є порядок, в якому вони відображаються. Якщо вам не потрібні всі ці параметри, то і прописувати їх немає необхідності.

Не забудьте включити цей клас до складу коду functions.php.

include( 'MyCustomizer.class.php' );

Закінчивши з класом, можна отримати доступ до значень функції get_theme_mod('option_name').

Крок 3. Інтегруємо API

Тепер треба підключити API. Для роботи в цьому пості я використав Codebird, PHP-клас для взаємодії з Twitter API

Завантажуємо файл codebird.php з Codebird, помістимо у вашу основну папку теми та налаштуємо його наступним чином:

add_action( 'init', 'my_twitter_api' );
function my_twitter_api() {
	global $cb;
	$consumer_key = get_theme_mod( 'consumer_key' );
	$consumer_secret = get_theme_mod( 'consumer_secret' );
	$access_token = get_theme_mod( 'access_token' );
	$access_secret = get_theme_mod( 'access_secret' );

	include( 'codebird.php' )
	Codebird::setConsumerKey( $consumer_key, $consumer_secret );
	$cb = Codebird::getInstance();
	$cb->setToken( $access_token, $access_secret );
}

Тепер можна користуватися Codebird, але ми повернемося пізніше.

Крок 4. Створюємо віджет

Віджети найкраще помістити в окремі файли. Створимо папку для віджетів та помістимо туди файл MyTwitterWidget.class.php. Включимо цей файл до functions.php:

include( 'widgets/MyTwitterWidget.class.php' );

Додаємо наступний PHP-код, щоб віджети заробили:

<?php
class MyTwitterWidget extends WP_Widget {
	/** Widget setup **/
	function MyTwitterWidget() {
		parent::WP_Widget(
			false, __( 'My Twitter Widget', 'mytextdomain' ),
			array('description' => __( 'Displays a list of tweets from a specified user name', 'mytextdomain' )),
			array('width' => '400px')
		);
	}
	/** The back-end form **/
	function form( $instance ) {

	}
	/** Saving form data **/
	function update( $new_instance, $old_instance ) {

	}
	/** The front-end display **/
	function widget( $args, $instance ) {

	}
}
register_widget('MyTwitterWidget');
?>

Тут є 4 функції, кожна з яких відіграє свою роль у роботі віджету:

• Перша для конструктора, де вказують опис і заголовок віджету.
• Функція форму відповідає за форму для збирання даних.
• Функція оновлення дає вам можливість додавати будь-який спеціальний код.
• Функція віджет відповідає за роботу віджету у фронт-енді.

У міру створення віджету нам знадобляться всі ці функції одна за одною.

Форма в бек-енд

У нашому майбутньому віджеті можна буде змінювати назву та ряд параметрів, зокрема ім'я користувача Twitter. Основний шаблон використання та налаштування цих параметрів виглядають так:

<p>
	<label for='<?php echo $this->get_field_id( 'option_name' ); ?>'>
		<?php _e( 'Title:', 'mytextdomain' ); ?>
		<input class='widefat' id='<?php echo $this->get_field_id( 'option_name' ); ?>' name='<?php echo $this->get_field_name( 'option_name' ); ?>' type='text' value='<?php echo $values['option_name']; ?>' />
	</label>
</p>

масив $values — це список усіх опцій для віджету, які вказані у різних місцях. Усі опції оформляються та заповнюються за шаблоном. Ось як виглядають ці функції і що треба в них знайти:

• get_field_id() - виводить ID для поля кожної з налаштувань.
• get_field_name() - Виводить ім'я поля для вибраної опції.

Використання всіх цих функцій є критично важливим, щоб не внести плутанину у застосування великої кількості різних віджетів.

Повний код для форми виглядає так:

<?php
	$defaults = array(
		'title'    => '',
		'limit'    => 5,
		'username' => 'bonsaished'
	);
	$values = wp_parse_args( $instance, $defaults );
?>
<p>
	<label for='<?php echo $this->get_field_id( 'title' ); ?>'>
		<?php _e( 'Title:', 'mytextdomain' ); ?>
		<input class='widefat' id='<?php echo $this->get_field_id( 'title' ); ?>' name='<?php echo $this->get_field_name( 'title' ); ?>' type='text' value='<?php echo $values['title']; ?>' />
	</label>
</p>

<p>
	<label for='<?php echo $this->get_field_id( 'limit' ); ?>'>
		<?php _e( 'Tweets to show:', 'mytextdomain' ); ?>
		<input class='widefat' id='<?php echo $this->get_field_id( 'limit' ); ?>' name='<?php echo $this->get_field_name( 'limit' ); ?>' type='text' value='<?php echo $values['limit']; ?>' />
	</label>
</p>

<p>
	<label for='<?php echo $this->get_field_id( 'username' ); ?>'>
		<?php _e( 'Twitter user name:', 'mytextdomain' ); ?>
		<input class='widefat' id='<?php echo $this->get_field_id( 'username' ); ?>' name='<?php echo $this->get_field_name( 'username' ); ?>' type='text' value='<?php echo $values['username']; ?>' />
	</label>
</p>

Функція використовує значення параметрів $instance и за замовчуванням.

Крок 5. Зберігаємо дані форми

Ось простий рядок коду для функції update ():

return $new_instance;

Параметр $new_instance містить у собі нові дані. Ціль функції — дозволити нам деякі зміни і при цьому перевіряти дані.

Крок 6. Включаємо відображення твітів

Перейдемо тепер до складного. Нам потрібно кешувати результати та записи з Twitter, щоб скоротити кількість повторних запитів до основного сайту, не допустити зависань і не потрапити під фільтри та блокування. Вирішити ці проблеми можна шляхом створення функцій для фронт-енду та подальшого їх налаштування.

Для початку подивимося на загальне відображення віджетів у шаблоні:

echo $args['before_widget'];
echo $args['before_title'] . $instance['title'] .  $args['after_title'];
echo $args['after_widget'];

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

Тепер виведемо наші твіти:

$tweets = $this->get_tweets( $args['widget_id'], $instance );
if( !empty( $tweets['tweets'] ) AND empty( $tweets['tweets']->errors ) ) {

	echo $args['before_widget'];
	echo $args['before_title'] . $instance['title'] .  $args['after_title'];

	$user = current( $tweets['tweets'] );
	$user = $user->user;

	echo '
		<div class="twitter-profile">
		<img src="' . $user->profile_image_url . '">
		<h1><a class="heading-text-color" href="http://twitter.com/' . $user->screen_name . '">' . $user->screen_name . '</a></h1>
		<div class="description content">' . $user->description . '</div>
		</div>	';

	echo '<ul>';
	foreach( $tweets['tweets'] as $tweet ) {
		if( is_object( $tweet ) ) {
			$tweet_text = htmlentities($tweet->text, ENT_QUOTES);
			$tweet_text = preg_replace( '/http://([a-z0-9_.-+&!#~/,]+)/i', 'http://$1', $tweet_text );

			echo '
				<li>
					<span class="content">' . $tweet_text . '</span>
					<div class="date">' . human_time_diff( strtotime( $tweet->created_at ) ) . ' ago </div>
				</li>';
		}
	}
	echo '</ul>';
	echo $args['after_widget'];
}

Давайте трохи розберемо цей код за рядками:

• рядок 1: У нас є функція get_tweets()яка повертає нам список твітів. Її важливо включити до коду загальної функції.
• рядок 2: Якщо список твітів не містить помилок і не порожній, можна відобразити віджет.
• рядки 7-8: Всі твіти у нас — від одного користувача, і кожен твіт містить дані користувача. У 7-му рядку ми просто відбираємо перший твіт, а у 8-му рядку витягуємо дані користувача у змінному $ користувачеві.
• рядки 10-16: Використовуємо дані з $ користувачеві, щоб увімкнути відображення короткого опису, аватарки та імені користувача з облікового запису на Twitter.
• рядки 18-29: використовуючи дані змінної $tweets['tweets']створюємо список твітів. Параметр preg_replace () тут потрібно конвертувати посилання з простого тексту в клікабельні елементи.

Тепер розберемося, як працює функція get_tweets(). Ми вже знаємо, що функція не може отримувати безпосередньо твіти з Twitter, так що треба буде трохи почаклувати.

Для цього треба зробити з функцією get_tweets() наступне:

1. Отримати список твітів з нашої бази даних.
2. Якщо там немає списку або він старіший за 5 хвилин, то треба отримати такий список від Twitter.
3. Отримавши результати від Twitter, треба їх зберегти в нашу БД і додати мітку часу, щоб переконатися, що ми отримуємо найсвіжіші результати, а не ті, що були 5 хвилин тому.

Щоб розділити всі ці операції, створимо три окремі функції:

• get_tweets() - Витягує список твітів з нашої БД.
• retrieve_tweets() - Витягує список твітів з Twitter.
• save_tweets() - Зберігає список твітів з Twitter в нашу БД.

Вибираємо твіти з мікроблогу

У класі MyTwitterWidget створимо функцію та дозволимо їй вибирати твіти:

function retrieve_tweets( $widget_id, $instance ) {
	global $cb;
 	$timeline = $cb->statuses_userTimeline( 'screen_name=' . $instance['username']. '&count=' . $instance['limit'] . '&exclude_replies=true' );
 	return $timeline;
}

Як бачите, це досить просто, якщо скористатися класом Codebird. Ми просто беремо одну з функцій класу для отримання списку: statuses_userTimeline(). Наші власні функції отримують значення ідентифікатора віджету та дані з екземплярМи використовуємо для того, щоб "повідомити" Codebird, твіти якого користувача нам потрібні, і скільки всього повідомлень вибрати.

Зберігаємо твіти до бази даних

Щоб зберегти твіти у БД, нам треба використовувати ідентифікатор віджету та додати актуальні твіти, і нам треба ще зберегти мітку про той час, коли ми востаннє оновлювали вибірку твітів:

function save_tweets( $widget_id, $instance ) {
	$timeline = $this->retrieve_tweets( $widget_id, $instance );
	$tweets = array( 'tweets' => $timeline, 'update_time' => time() + ( 60 * 5 ) );
	update_option( 'my_tweets_' . $widget_id, $tweets );
	return $tweets;
}

Віджет також набуває значення ID та дані з екземпляр. Ця інформація потрібна для отримання твітів за допомогою створеної вище функції retrieve_tweets(). Все це ми додамо до масиву $tweets, в якому міститься інформація з Twitter та час оновлення.

Час оновлення зараз складає 5 хвилин. Коли ми відображаємо наші твіти, будемо використовувати це значення для того, щоб визначити, чи показувати твіти з нашої БД або підтягувати нові з Twitter (щоб переконатися, що наші користувачі сайту постійно бачать свіжі пости з мікроблогу).

Список зберігаємо у БД на основі ID віджета, із застосуванням таблиці налаштувань WordPress. Так ми будемо впевнені, що можемо зберегти всі подробиці про кожен твіт для нашого віджету.

Отримуємо твіти з БД

І ось настав час зайнятися функцією get_tweets(). Давайте подивимося, як тут все влаштовано:

function get_tweets( $widget_id, $instance ) {
	$tweets = get_option( 'my_tweets_' . $widget_id );
	if( empty( $tweets ) OR time() > $tweets['update_time'] ) {
		$tweets = $this->save_tweets( $widget_id, $instance );
	}
	return $tweets;
}

Спочатку ми отримуємо твіти із БД, використовуючи таблицю налаштувань. Якщо таблиця параметрів порожня або останнє оновлення було надто давно, потрібно використовувати функцію save_tweet. З її допомогою ми отримаємо наші твіти у вигляді списку та внесемо їх до БД для подальшого застосування.

Висновок

Метод, який наведений у цьому пості, має свої недоліки, зате він досить зрозумілий і логічний, включаючи додавання віджету та його кастомізацію для вашої теми оформлення на сайті WordPress. Якщо основи додавання та налаштування віджети ви освоїте, можна сміливо додавати і налаштовувати власні віджети такого типу на різних сайтах на свій розсуд.

Джерело:wp.smashingmagazine.com

Олексій Шевченко

редактор wpcafe

Вивчає сайтобудування з 2008 року. Практикуючий вебмайстер, що спеціалізується на створенні сайтів WordPress. Задати питання Олексію можна на https://profiles.wordpress.org/wpthemeus/