WordPress: aggiungere una sezione portfolio a TwentyFourteen

In questo articolo vedremo come estendere il tema TwentyFourteen di WordPress includendo una sezione portfolio che raccoglierà i nostri ultimi lavori. Per questo compito aggiungeremo due nuovi file template al tema e creeremo un plugin. Tutto il core del nostro codice sarà scritto con un approccio OOP.

Preparazione

Il nostro codice verrà strutturato in due componenti:

1. un plugin che gestirà i custom post type, le tassonomie, lo shortcode e l'inclusione dei file JavaScript e CSS;
2. due nuovi file template per il tema TwentyFourteen, ossia:
   1. single-portfolio.php per i singoli custom post type del portfolio;
   2. taxonomy-portfolio-category.php per le categorie dei nostri custom post type.

Il plugin

Il nostro plugin funziona grazie alla classe TFPortfolio che svolge tre compiti ben precisi:

1. registra il custom post type portfolio e le tassonomie del portfolio (portfolio-category) grazie al metodo TFPortfolio::createCustomPostType();
2. inserisce i file CSS e JavaScript grazie al metodo TFPortfolio::insertScripts(), che sono:
   1. il file CSS portfolio.css per il layout;
   2. il plugin jQuery Colorbox per gestire le lightbox delle immagini del portfolio;
   3. il file JavaScript portfolio.js che fa riferimento al plugin jQuery e lo utilizza;
3. crea lo shortcode [tf-portfolio] per visualizzare i nostri lavori in una pagina che andremo a creare (ad esempio sito.it/progetti) tramite il metodo TFPortfolio::portfolioShortcode().

Il metodo TFPortfolio::createCustomPostType()

Passiamo quindi al codice del metodo TFPortfolio::createCustomPostType() che, come anticipato, registra il custom post type portfolio e la tassonomie del portfolio.

public function createCustomPostType() {
  		$labels = array(
    		'name' => _x( 'Portfolio', 'post type general name' ),
    		'singular_name' => _x( 'Portfolio', 'post type singular name'),
    		'add_new' => _x( 'Add New', 'Portfolio' ),
    		'add_new_item' => __( 'Add New Portfolio' ),
    		'edit_item' => __( 'Edit Portfolio' ),
    		'new_item' => __( 'New Portfolio' ),
    		'all_items' => __( 'All Portfolio' ),
    		'view_item' => __( 'View Portfolio' ),
    		'search_items' => __( 'Search Portfolio' ),
    		'not_found' =>  __( 'No Portfolio found' ),
    		'not_found_in_trash' => __( 'No Portfolio found in Trash' ),
    		'parent_item_colon' => '',
    		'menu_name' => __( 'Portfolio' )
  		);
  		$args = array(
    		'labels' => $labels,
    		'public' => true,
    		'publicly_queryable' => true,
    		'show_ui' => true,
    		'show_in_menu' => true,
    		'query_var' => true,
    		'rewrite' => array( 'slug'=> 'portfolio' ),
    		'capability_type' => 'post',
    		'has_archive' => true,
    		'hierarchical' => false,
    		'menu_position' => 100,
    		'supports' => array( 'title', 'editor', 'author', 'thumbnail', 'excerpt' )
  		);
  		$catLabels = array(
			'name'              => _x( 'Portfolio Categories', 'taxonomy general name' ),
			'singular_name'     => _x( 'Portfolio Category', 'taxonomy singular name' ),
			'search_items'      => __( 'Search Portfolio Categories' ),
			'all_items'         => __( 'All Portfolio Categories' ),
			'parent_item'       => __( 'Parent Portfolio Category' ),
			'parent_item_colon' => __( 'Parent Portfolio Category:' ),
			'edit_item'         => __( 'Edit Portfolio Category' ),
			'update_item'       => __( 'Update Portfolio Category' ),
			'add_new_item'      => __( 'Add Portfolio Category' ),
			'new_item_name'     => __( 'New Portfolio Category' ),
			'menu_name'         => __( 'Portfolio Categories' ),
		);
		$catArgs = array(
			'hierarchical'      => true,
			'labels'            => $catLabels,
			'show_ui'           => true,
			'show_admin_column' => true,
			'query_var'         => true,
			'rewrite'           => array( 'slug' => 'portfolio-category' ),
		);
  		register_post_type( 'portfolio', $args );
  		register_taxonomy( 'portfolio-category', array( 'portfolio' ), $catArgs );
  		flush_rewrite_rules();
	}

Da notare in questo metodo è l'uso finale della funzione flush_rewrite_rules(). La usiamo per essere sicuri che la riscrittura degli URL venga aggiornata con la nuova struttura creata dal nostro custom post type e dalla nostra tassonomia senza generare l'errore 404 ("Non Trovato").

Il metodo TFPortfolio::insertScripts()

TwentyFourteen utilizza già jQuery, quindi non è necessario includerla:

public function insertScripts() {
		$url = plugins_url();
		$assetsURL = $url . '/tf-portfolio/assets/';
		wp_enqueue_style( 'portfolio', $assetsURL . 'css/portfolio.css' );
		wp_enqueue_style( 'colorbox', $assetsURL . 'js/colorbox/colorbox.css' );
		wp_enqueue_script( 'colorbox', $assetsURL . 'js/colorbox/jquery.colorbox.min.js', array( 'jquery' ), '1.3.21', false );
		wp_enqueue_script( 'portfolio', $assetsURL . 'js/portfolio.js', array( 'jquery' ), '1.0', false );
}

Il codice del nostro file JavaScript fa a sua volta uso di un approccio OOP e associa una lightbox ai link principali degli elementi del portfolio:

(function( $ ) {
	$.TFPortfolio = function( element ) {
	  if( $( element ).length ) {
		this.$element = $( element );
		this.init();
	  }
	}
	$.TFPortfolio.prototype = {
		init: function() {
			this.$links = this.$element.find( ".portfolio-lightbox" );
			this.lightbox();	
		},
		lightbox: function() {
			this.$links.colorbox();
		}	
	};
	$(function() {
		var portfolio = new $.TFPortfolio( "#portfolio-items" );
	});
})( jQuery );

Il metodo TFPortfolio::portfolioShortcode()

Questo metodo restituisce una stringa HTML contenente tutti i nostri portfolio:

public function portfolioShortcode() {
		$html = '<div id="portfolio-items">' . "n";
		$loop = new WP_Query( array( 'post_type' => 'portfolio', 'posts_per_page' => -1 ) );
		while( $loop->have_posts() ) {
			$loop->the_post();
			$id = get_the_ID();
			$title = get_the_title();
			$excerpt = strip_tags( get_the_excerpt() );
			$thumb_id = get_post_thumbnail_id( $id );
			$image_full = wp_get_attachment_image_src( $thumb_id, 'full' );
			$image_thumb = wp_get_attachment_image_src( $thumb_id, 'large' );
			$permalink = get_permalink();
			$html .= '<div class="portfolio-item">' . "n";
			$html .= '<a href="' . $image_full[0] . '" class="portfolio-lightbox" title="' . $title . '">' . "n";
			$html .= '<img src="' . $image_thumb[0] . '" alt="" />' . "n";
			$html .= '</a>' . "n";
			$html .= '<h2 class="portfolio-title">' . $title . '</h2>' . "n";
			$html .= '<p class="portfolio-excerpt">' . $excerpt . '</p>' . "n";
			$html .= '<p class="portfolio-more"><a href="' . $permalink . '">' . __( 'Vedi progetto', 'tf-portfolio' ) . '</a></p>';
			$html .= '</div>';
		}
		$html .= '</div>';
		wp_reset_query();
		return $html;
	}

Una volta introdotti i metodi necessari potremo passare alla fase di inizializzazione della classe.

Inizializzazione della classe

Il passaggio riguardante l'inizializzazione della classe verrà completato introducendo i tre temi precedentemente esposti:

class TFPortfolio {
	public function __construct() {
		add_action( 'init', array( &$this, 'createCustomPostType' ) );
		add_action( 'wp_enqueue_scripts', array( &$this, 'insertScripts' ) );
		add_shortcode( 'tf-portfolio', array( &$this, 'portfolioShortcode' ) );
	}
	//...
}

Quindi nel file principale del nostro plugin avremo i dati seguenti:

<?php
/*
Plugin Name: Twenty Fourteen Portfolio
Version: 1.0
Description: Adds a portfolio to the Twenty Fourteen theme
Author: Gabriele Romanato
Author URI: http://gabrieleromanato.com
*/
$dir = plugin_dir_path(  __FILE__  );
require_once( $dir . 'framework/TFPortfolio.php' );
if( class_exists( 'TFPortfolio' ) ) {
	$tfPortfolio = new TFPortfolio();
}

I nuovi file template per TwentyFourteen

Il nuovo file taxonomy-portfolio-category.php riprende la struttura del file originale di archivio del tema con alcune varianti:

<?php
get_header(); ?>
	<section id="primary" class="content-area">
		<div id="content" class="site-content" role="main">
			<?php if ( have_posts() ) { ?>
			<header class="archive-header">
				<h1 class="archive-title">
				    <!-- Visualizza il titolo della tassonomia -->
					<?php $term = get_term_by( 'slug', get_query_var( 'term' ), get_query_var( 'taxonomy' ) ); ?>
                    <?php echo $term->name; ?>
				</h1>
			</header><!-- .archive-header -->
			<!-- Portfolio -->
		  <div id="portfolio-items">
			<?php
			  while( have_posts() ) {
				  the_post();
				  $id = get_the_ID();
				  $title = get_the_title();
				  $excerpt = strip_tags( get_the_excerpt() );
				  $thumb_id = get_post_thumbnail_id( $id );
				  $image_full = wp_get_attachment_image_src( $thumb_id, 'full' );
				  $image_thumb = wp_get_attachment_image_src( $thumb_id, 'large' );
				  $permalink = get_permalink();
			?>
				<div class="portfolio-item">
					<a href="<?php echo $image_full[0];?>" class="portfolio-lightbox" title="<?php echo $title; ?>">
						<img src="<?php echo $image_thumb[0];?>" alt="" />
					</a>
					<h2 class="portfolio-title"><?php echo $title; ?></h2>
					<p class="portfolio-excerpt"><?php echo $excerpt; ?></p>
					<p class="portfolio-more"><a href="<?php echo $permalink; ?>"><?php _e( 'Vedi progetto', 'tf-portfolio' ); ?></a></p>
				</div>
			  <!-- /Portfolio -->
		  <?php
			  }   
			?>
		  </div>
			<?php } ?>
		</div><!-- #content -->
	</section><!-- #primary -->
<?php
get_sidebar( 'content' );
get_sidebar();
get_footer();

Quando si estende un tema con nuovi template non si deve mai cercare di stravolgere la struttura originaria del tema, al contrario si deve armonizzare la nuova struttura con quella preesistente cercando di eliminare ogni possibile conflitto.

Il tema TwentyFourteen è un tema a due colonne con un'ampia zona centrale per il contenuto; dobbiamo sfruttare quest'area per inserire il nostro portfolio. Questa filosofia
è evidente anche nel file single-portfolio.php che visualizza i portfolio singoli:

<?php
get_header(); ?>
	<div id="primary" class="content-area">
		<div id="content" class="site-content" role="main">
			<?php
				// Start the Loop.
				while ( have_posts() ) : the_post();
			?>
			  <!-- Portfolio -->
				<div id="portfolio-items">
					<div class="portfolio-item single">
						<?php
							$id = get_the_ID();
							$thumb_id = get_post_thumbnail_id( $id );
							$image_full = wp_get_attachment_image_src( $thumb_id, 'full' );
							$image_thumb = wp_get_attachment_image_src( $thumb_id, 'large' );
							$title = get_the_title();
							$excerpt = strip_tags( get_the_content() );
						?>
						<a href="<?php echo $image_full[0];?>" class="portfolio-lightbox" title="<?php echo $title; ?>">
							<img src="<?php echo $image_thumb[0];?>" alt="" />
						</a>
						<h2 class="portfolio-title"><?php echo $title; ?></h2>
						<div class="portfolio-excerpt"><?php echo $excerpt; ?></div>
					</div>
				</div>
			  <!-- /Portfolio -->
			<?php
				endwhile;
			?>
		</div><!-- #content -->
	</div><!-- #primary -->
<?php
get_sidebar( 'content' );
get_sidebar();
get_footer();

Conclusione

Abbiamo implementato una soluzione semplice ma efficace che evita di stravolgere il tema originale ma che al contempo ci consente di estenderlo aggiungendo le funzionalità richieste. Ancora una volta l'approccio OOP si rivela vincente sia per la gestione della struttura che per la sua presentazione ed il suo comportamento.

Demo

Potete osservare la nostra soluzione dal vivo nel seguente video: