Costruzione di un Front-End alimentato da WordPress: una direttiva personalizzata per l'elenco di Post

Italian (Italiano) translation by Piergiorgio Sansone (you can also view the original English article)

Nella parte precedente della serie, abbiamo avviato la nostra applicazione AngularJS, configurato i percorsi per diverse viste e costruito i servizi sui percorsi di tutti i Posts, gli utenti e le categorie. Utilizzando questi servizi, ora siamo finalmente in grado di recuperare i dati dal server per alimentare il front-end.

In questa parte della serie, lavoreremo ala costruzione di una direttrice AngularJS personalizzata per la funzionalità elenco dei Post. Nella parte corrente della serie, ci impegniamo a:

presentarci alle direttrici AngularJS e perché dovremmo crearne una
pianificare la direttrice per la funzionalità elenco di post e gli argomenti che servono.
creare una direttrice AngularJS personalizzata per l'elenco dei post, insieme al relativo modello.

Quindi iniziamo a presentarci alle direttrici AngularJS e perché abbiamo bisogno di loro.

L'introduzione alle Direttrici AngularJS

Le Direttive AngularJS sono un modo per modificare il comportamento di elementi HTML e di riutilizzare un blocco ripetibile di codice. Sono utilizzabili per modificare la struttura di un elemento HTML e i relativi figli, e così sono un modo perfetto per introdurre il widget dell'interfaccia utente personalizzati.

Mentre analizzavamo i wireframes nella prima parte della serie, abbiamo notato che la funzionalità elenco post viene utilizzata in tre viste, vale a dire:

Elenco Post
Profilo Autore
Categoria elenco posts

Così invece di scrivere la funzionalità elenco posts distintamente su tutte queste tre pagine, possiamo creare una direttiva AngularJS personalizzata che contiene la logica di business per recuperare i messaggi utilizzando i servizi che abbiamo creato nella prima parte di questa serie. Oltre alla logica di business, questa direttiva conterrà anche la logica di rendering per elenco post su determinate viste. È anche in questa direttiva che verrà definita la funzionalità per l'impaginazione del post e il recupero dei post in base a determinati criteri.

Quindi, creare una direttiva AngularJS personalizzata per la funzionalità elenco post ci permette di definire la funzionalità in un solo posto, e questo renderà più facile estendere o modificare in futuro questa funzionalità senza dover modificare il codice in tutte le tre istanze dove viene utilizzato.

Detto questo, cominciamo la codifica della nostra direttiva personalizzata per la funzionalità di elenco post.

Pianificazione della direttiva AngularJS personalizzata per l' elenco di Post

Prima di cominciare scrivere qualsiasi codice per la costruzione della direttiva per la funzionalità di elenco post, vediamo di analizzare la funzionalità che serve nella direttiva.

A livello molto base, abbiamo bisogno di una direttiva che possiamo usare nelle nostre viste per l'elenco post, profilo dell'autore e la pagina della categoria. Ciò significa che ci sarà la creazione di un widget di interfaccia utente personalizzato (o un indicatore di DOM) che mettiamo nel nostro HTML, e AngularJS si prenderà cura del resto dipendendo quali opzioni forniamo per quella particolare istanza della direttiva.

Quindi, ci sarà la creazione di un widget di interfaccia utente personalizzato identificato dai seguenti tag :

<post-listing></post-listing>

Ma abbiamo anche bisogno di questa direttiva sia flessibile, cioè di prendere gli argomenti come input e agire di conseguenza. Considerate la pagina del profilo utente dove vogliamo si vedano solo post appartenenti a quell'utente specifico o la pagina di categoria dove verranno elencati tutti i messaggi appartenenti a tale categoria. Questi argomenti possono essere forniti nei seguenti due modi:

Nell'URL come parametri
Direttamente alla direttiva come valore di un attributo

Fornire argomenti nell'URL sembra nativo all'API in quanto abbiamo già familiarità nel farlo. Un utente è quindi in grado di recuperare una serie di posts appartenenti a un utente specifico nel modo seguente:

https://127.0.0.1:8080/#/posts?author=1

La funzionalità di cui sopra può essere realizzata utilizzando il servizio di $routeParams fornito da AngularJS. Questo è dove abbiamo potuto accedere ai parametri forniti dall'utente nell'URL. Ci abbiamo già guardato durante la registrazione dei percorsi nella parte precedente della serie.

Per quanto riguarda fornire argomenti direttamente alla direttiva come valore di attributo, potremmo usare qualcosa di simile al seguente:

<post-listing post-args="{author=1}"></post-listing>

L'attributo post-args nel frammento precedente, accetta argomenti per il recupero di un insieme specifico di post, e attualmente sta prendendo l'ID autore. Questo attributo può intraprendere qualsiasi numero di argomenti per il recupero post come supportato dal percorso /wp/v2/posts. Così se dovessimo recuperare un insieme di post scritti da un utente con ID 1 e appartenenti a una categoria di ID 10, potevamo fare qualcosa di simile alla seguente:

<post-listing post-args="{author=1, filter[cat]=10}"></post-listing>

Il parametro di filter[cat] nel codice precedente viene utilizzato per recuperare un insieme di post appartenenti a una determinata categoria.

Anche l'impaginazione è una caratteristica essenziale quando si lavora con pagine di post. La direttiva consente di gestire l'impaginazione del post, e questa caratteristica sarà guidata dai valori delle intestazioni di X-WP-totale e X-WP-TotalPages come restituito dal server insieme con il corpo della risposta. Quindi, l'utente sarà in grado di spostarsi avanti e indietro tra il precedente e successivo set di post.

Dopo aver deciso la quintaessenza della direttiva personalizzata per l'elenco di post, ora abbiamo delle solide basi per iniziare a scrivere il codice.

Costruzione di una direttiva personalizzata per l'elenco di Post

La costruzione di una direttiva per la funzionalità elenco post include due passaggi:

Creare la logica di business per il recupero post e gestire altre cose.
Creare una vista di rendering per la presentazione di questi post nella pagina.

La logica di business per la nostra direttiva personalizzata sarà trattata nella direttiva dichiarazione. E per i dati di rendering sul DOM, creeremo un modello personalizzato per l'elenco dei post. Cominciamo con la dichiarazione di direttiva.

Dichiarazione di direttiva

Le Direttive in AngularJS possono essere dichiarate per un modulo con la seguente sintassi:

/**
 * Creating a custom directive for posts listing
 */
quiescentApp.directive( 'postListing', [function() {
    return {

    };
}] );

Qui stiamo dichiarando una direttiva sul nostro modulo utilizzando il metodo .directive() che è disponibile nel modulo. Il metodo prende il nome della direttiva come primo argomento, e questo nome è strettamente legato con il nome del tag dell'elemento. Poiché vogliamo che il nostro elemento HTML sia <post-listing> </post-listing>, forniamo una rappresentazione maiuscole-minuscole del nome del tag. Può imparare di più su questo processo di normalizzazione eseguito da AngularJS per abbinare i nomi delle direttive nella documentazione ufficiale.

La notazione che stiamo usando nel suddetto codice per dichiarare la nostra direttiva viene chiamata safe-stile di inserimento delle dipendenze. E in questa notazione, forniamo come secondo argomento una matrice delle dipendenze che saranno necessarie alla direttiva. Attualmente, non abbiamo definito tutte le dipendenze per nostra direttiva personalizzata. Ma dal momento che, abbiamo bisogno del servizio di post per il recupero post (che abbiamo creato nella parte precedente della serie) e dei servizi nativi AngularJS di $routeParams e $location per l'accesso ai parametri URL e il percorso corrente, li definiamo come segue:

/**
 * Creating a custom directive for posts listing
 */
quiescentApp.directive( 'postListing', ['$routeParams', '$location', 'Posts', function( $routeParams, $location, Posts ) {
    return {
        restrict: 'E',
        scope: {
            postArgs: '='
        },
        link: function( $scope, $elem, $attr ) {
        
        }
    };
}] );

Queste dipendenze sono quindi rese disponibili per la funzione che è definita come l'ultimo elemento della matrice. Questa funzione restituisce un oggetto contenente la definizione della direttiva. Attualmente, abbiamo due proprietà nell'oggetto definizione della direttiva, cioè restrict e il link.

L'opzione restrict definisce il modo in che cui usiamo la direttiva nel nostro codice, e ci possono essere quattro valori possibili per questa opzione:

A: per l'utilizzo della direttiva come attributo di un elemento HTML esistente.
E: per l'utilizzo della direttiva come un nome di elemento.
C: per l'utilizzo della direttiva come un nome di classe.
M: per l'utilizzo della direttiva come un commento HTML.

L'opzione restrict può anche accettare qualsiasi combinazione dei suddetti quattro valori.

Poiché vogliamo che la nostra direttiva sia un nuovo elemento <post-listing></post-listing>, impostiamo l'opzione restrict su E. Se dovessimo definire la direttiva utilizzando gli attributi su un elemento HTML pre-esistente, dovremmo impostare l'opzione A. In tal caso, abbiamo potuto utilizzare <div post-listing></div> per definire la direttiva nel nostro codice HTML.

Il secondo scope viene utilizzata per modificare l'ambito di applicazione della direttiva. Per impostazione predefinita, il valore della proprietà scope è falso, che significa che il campo di applicazione della direttiva è lo stesso come suo padre. Quando si passa un oggetto, viene creato un ambito isolato per la direttiva e tutti i dati che devono essere passato alla direttiva dal relativo elemento padre vengono passati attraverso gli attributi HTML. Questo è ciò che stiamo facendo nel nostro codice, e l'attributo che stiamo usando è post-args, che ottiene normalizzati in postArgs.

La proprietà postArgs dell'oggetto scope può accettare uno qualsiasi dei tre valori seguenti:

=: Significa che il valore passato nell'attributo sarebbe considerato come un oggetto.
@: Significa che il valore passato nell'attributo sarebbe essere trattato come una stringa normale.
&: Significa che il valore passato nell'attributo sarebbe considerato come una funzione.

Dal momento che abbiamo scelto di utilizzare il valore =, qualsiasi valore che viene passato nell'attributo post-args sarebbe trattato come un oggetto JSON, e potremmo usare quell'oggetto come un argomento per il recupero post.

La terza proprietà, link, è definisce una funzione che viene utilizzata per modificare il DOM e definisce le API e funzioni che sono necessarie per la direttiva. Questa funzione si trova dove viene gestita tutta la logica della direttiva.

La funzione link accetta argomenti per l'oggetto ambito, l'elemento HTML della direttiva, e un oggetto per attributi definiti sull'elemento HTML della direttiva. Attualmente, stiamo passando due argomenti $scope e $elem per l'oggetto di ambito e l'elemento HTML rispettivamente.

Cerchiamo di definire alcune variabili sulla proprietà $scope che si utilizzerà per eseguire il rendering la funzionalità di profilo di post sul DOM.

/**
 * Creating a custom directive for posts listing
 */
quiescentApp.directive( 'postListing', ['$routeParams', '$location', 'Posts', function( $routeParams, $location, Posts ) {
    return {
        restrict: 'E',
        scope: {
            postArgs: '='
        },
        link: function( $scope, $elem, $attr ) {
            // defining variables on the $scope object
            $scope.posts = [];
            $scope.postHeaders = {};
            $scope.currentPage = $routeParams.page ? Math.abs( $routeParams.page ) : 1;
            $scope.nextPage = null;
            $scope.previousPage = null;
            $scope.routeContext = $location.path();
        }
    };
}] );

Da qui abbiamo definito sei proprietà sull'oggetto $scope che abbiamo potuto accedere nel DOM. Queste proprietà sono:

$posts: matrice per contenere oggetti di post che verranno restituiti dal server.
$postHeaders: un oggetto per contenere le intestazioni che potranno essere restituite dal server nonché il corpo della risposta. Useremo questi per la gestione della navigazione.
$currentPage: una variabile integer che tiene il numero di pagina corrente.
$previousPage: una variabile contenente il numero di pagina precedente.
$nextPage: una variabile contenente il numero della pagina successiva.
$routeContext: per l'accesso il percorso corrente utilizzando il servizio di $location.

La proprietà di postArgs che abbiamo definito in precedenza per gli attributi HTML sarà già disponibile sull'oggetto $scope all'interno della direttiva.

Ora siamo pronti per effettuare una richiesta al server utilizzando il servizio di messaggi per il recupero post. Ma prima di ciò, dobbiamo prendere in considerazione gli argomenti forniti dall'utente come parametri URL come pure i parametri specificati nell'attributo post-args. E a tale scopo, si creerà una funzione che utilizza il servizio di $routeParams per estrarre i parametri URL e unirle con gli argomenti forniti attraverso l'attributo post-args:

/**
 * Creating a custom directive for posts listing
 */
quiescentApp.directive( 'postListing', ['$routeParams', '$location', 'Posts', function( $routeParams, $location, Posts ) {
    return {
        restrict: 'E',
        scope: {
            postArgs: '='
        },
        link: function( $scope, $elem, $attr ) {
            // defining variables on the $scope object
            $scope.posts = [];
            $scope.postHeaders = {};
            $scope.currentPage = $routeParams.page ? Math.abs( $routeParams.page ) : 1;
            $scope.nextPage = null;
            $scope.previousPage = null;
            $scope.routeContext = $location.path();
            
            // preparing query arguments
            var prepareQueryArgs = function() {
                var tempParams = $routeParams;
                delete tempParams.id;
                return angular.merge( {}, $scope.postArgs, tempParams );
            };
        }
    };
}] );

Il metodo prepareQueryArgs() nel codice precedente utilizza il metodo angular.merge(), che estende l'oggetto $scope.postArgs con l'oggetto $routeParams. Ma prima di unire questi due oggetti, elimina prima la proprietà id dall'oggetto $routeParams utilizzando l'operatore delete. Ciò è necessario poiché useremo questa direttiva sulla categoria e utente viste, e non vogliamo che gli ID di categoria e utente per avere erroneamente interpretato come l'ID del post.

Dopo aver preparato gli argomenti delle query, siamo finalmente pronti ad effettuare una chiamata al server e recuperare tutti i messaggi, e lo facciamo con il metodo Posts.query(), che accetta due argomenti:

Un oggetto che contiene gli argomenti per rendere la query.
Una funzione di callback che viene eseguita dopo che la query è stata completata.

Quindi useremo la funzione prepareQueryArgs() per la preparazione di un oggetto per argomenti della query e nella funzione di callback, imposteremo i valori di determinate variabili sulla proprietà $scope:

// make the request and query posts
Posts.query( prepareQueryArgs(), function( data, headers ) {
    $scope.posts = data;
    $scope.postHeaders = headers();
    $scope.previousPage = ( ( $scope.currentPage + 1 ) > $scope.postHeaders['x-wp-totalpages'] ) ? null : ( $scope.currentPage + 1 );
    $scope.nextPage = ( ( $scope.currentPage - 1 ) > 0 ) ? ( $scope.currentPage - 1 ) : null;
});

La funzione di callback passa due argomenti per il corpo della risposta e le intestazioni di risposta. Questi sono rappresentati rispettivamente dagli argomenti dati e intestazioni.

L'argomento della intestazione è una funzione che restituisce un oggetto contenente le intestazioni di risposta dal server.

Il resto del codice è abbastanza auto-esplicativo, come ci stiamo impostando il valore della matrice $scope.posts. Per impostare i valori delle variabili $scope.previousPage e $scope.nextPage, stiamo utilizzando la proprietà x-wp-totalpages nell'oggetto postHeaders.

E ora siamo pronti per il rendering di tali dati sul front-end utilizzando un modello personalizzato per la nostra direttiva.

Creazione di un modello personalizzato per la direttiva

L'ultima cosa che dobbiamo fare per completare il nostro lavoro sulla direttiva è quello di creare un modello separato per elenco post e collegarlo alla direttiva. A tale scopo, abbiamo bisogno di modificare la dichiarazione di direttiva e includere una proprietà templateUrl simile alla seguente:

/**
 * Creating a custom directive for posts listing
 */
quiescentApp.directive( 'postListing', ['$routeParams', '$location', 'Posts', function( $routeParams, $location, Posts ) {
    return {
        restrict: 'E',
        scope: {
            postArgs: '='
        },
        templateUrl: 'views/directive-post-listing.html',
        link: function( $scope, $elem, $attr ) {
        
        }
    };
}] );

Questa proprietà templateUrl nel codice precedente fa riferimento in un file denominato direttiva-post-listing.html nella directory viste. Quindi creare questo file nella cartella viste e incollare il seguente codice HTML:

<!-- post listing starts -->
<article class="post-entry">
    <h2 class="post-title"><a href="post-single.html">Good design is a lot like clear thinking made visual.</a></h2>
    <figure class="post-thumbnail">
        <img src="img/img-712-348.jpg" alt="Featured Image">
    </figure>
    <p class="post-meta">
        By <a href="author.html">Bilal Shahid</a> in <a href="category.html">Quotes</a>
    </p>
    <div class="post-content">
        <p>Created days forth. Dominion. Subdue very hath spirit us sixth fish creepeth also. First meat one forth above. You'll Fill for. Can't evening one lights won't. Great of make firmament image. Life his beginning blessed lesser meat spirit blessed seas created green great beginning can't doesn't void moving. Subdue evening make spirit lesser greater all living green firmament winged saw tree one divide wherein divided shall dry very lesser saw, earth the. Light their the.</p>
    </div>
</article>
<!-- post listing ends -->


<!-- pagination links start -->
<div class="post-pagination">
    <a href="#" class="button">Older Posts</a>
    <a href="#" class="button">Newer Posts</a>
</div>  	
<!-- pagination links end -->

Questo è un codice HTML molto semplice che rappresenta un singolo post d'ingresso e l' impaginazione post. L'ho copiato dal file views/listing.html. Useremo alcune direttive AngularJS, tra cui ng-repeat, ng-href, ng-src e ng-bind-html, per visualizzare i dati che attualmente risiede nella proprietà $scope della direttiva.

Modificare il codice HTML con il seguente:

<!-- post listing starts -->
<article class="post-entry" ng-repeat="post in posts">
    <h2 class="post-title"><a ng-href="#/posts/{{post.slug}}">{{post.title.rendered}}</a></h2>
    <figure class="post-thumbnail" ng-show="post.quiescent_featured_image">
        <img ng-src="{{post.quiescent_featured_image}}" alt="Featured Image">
    </figure>
    <p class="post-meta">
        By <a ng-href="#/users/{{post.author}}">{{post.quiescent_author_name}}</a> 
        in <a ng-href="#/categories/{{category.term_id}}" ng-repeat="category in post.quiescent_categories">{{category.name}}{{$last ? '' : ',&nbsp;'}}</a>
    </p>
    <div class="post-content" ng-bind-html="post.excerpt.rendered"></div>
    </article>
<!-- post listing ends -->

Il codice precedente utilizza la direttiva di ng-repeat per scorrere la matrice di $scope.posts. Qualsiasi proprietà che viene definita sull'oggetto $scope nella dichiarazione di direttiva è disponibile direttamente nel modello. Quindi, ci riferiamo alla matrice $scope.posts direttamente come post nel modello.

Utilizzando la direttiva di ng-ripetizione, ci assicuriamo che il contenitore article.post-entry verrà ripetuto per ogni post nella matrice post e ogni post è indicato come post nel ciclo interno. Questo oggetto post contiene dati in formato JSON restituiti dal server, che contiene le proprietà come il titolo del post, post ID, contenuto del post e il link di foto di presentazione, che è un campo aggiuntivo aggiunto dal compagno plugin.

Nel passaggio successivo, sostituiamo i valori come il titolo del post, il link del post e il link di foto di presentazione con le proprietà dell'oggetto post.

Per l'impaginazione, sostituire il codice precedente con il seguente:

<!-- pagination links start -->
<div class="post-pagination">
    <a ng-href="#{{routeContext}}?page={{nextPage}}" class="button" ng-class="{'disabled': !nextPage}">Newer Posts</a>
    <a ng-href="#{{routeContext}}?page={{previousPage}}" class="button" ng-class="{'disabled': !previousPage}">Older Posts</a>
</div>		
<!-- pagination links end -->

Per prima cosa accederemo alla proprietà routeContext, che abbiamo definito nella nostra dichiarazione di direttiva, con il suffisso ?page= parametro e utilizzaremo i valori delle variabili nextPage e previousPage per spostarsi avanti e indietro tra post. Controlleremo anche che la pagina successiva o il collegamento alla pagina precedente non sia null, altrimenti aggiungiamo una classe .disabled al pulsante che è fornito dalla Fondazione Zurb.

Ora che abbiamo finito la direttiva, è il momento di provarla. E lo facciamo mettendo un <post-listing> </post-listing> tag nel nostro HTML, idealmente proprio sopra il <footer></footer> tag. Facendo così, significa che un elenco di post apparirà sopra il piè di pagina. Non preoccuparti per la formattazione e gli stili come ci occuperemo di loro nella parte successiva della serie.

Così questo è praticamente tutto sulla creazione di una direttiva AngularJS personalizzata per la funzionalità di elenco di post.

Cosa ci aspetta dopo?

In questa parte della serie, dedicata creazione di un front-end con l'API REST di WP e AngularJS, abbiamo costruito una direttiva AngularJS personalizzata per la funzionalità di elenco di post. Questa direttiva utilizza il servizio di post che abbiamo creato nella prima parte della serie. La direttiva prende anche l'input dell'utente in forma di attributo HTML e attraverso i parametri URL.

Nella parte conclusiva della serie, si inizierà il lavoro sulla parte finale del nostro progetto, cioè controller per tutti i messaggi, gli utenti e le categorie e rispettivi modelli.