Omskrivnings API Grunderna

Det här är en del av en tvådelarserie som tittar på WordPress 'Rewrite API. I denna handledning tittar vi på hur omskrivningar fungerar och de grundläggande metoderna som finns tillgängliga för att skapa anpassade omskrivningsregler.

Vad är omskrivning?

WordPress, som alla innehållshanteringssystem, bestämmer vilket innehåll som ska visas baserat på variablerna (vanligtvis kallade sökvariabler) som skickas till den. Till exempel: http://example.com/index.php?category=3 berättar WordPress vi är efter inlägg i en kategori med ett ID på 3 och http://example.com/index.php?feed=rss berättar WordPress vi vill ha webbplatsens flöde i RSS-format.

Tyvärr kan detta leda oss till ganska fula webbadresser:

http://example.com/index.php?post_type=portfolio&taxonomy=wordpress&portfolio=my-fancy-plugin

Det är här WordPress skriver om steg. Det låter oss ersätta ovanstående med:

http://example.com/portoflio/wordpress/my-fancy-plugin

Vilken är nu inte bara mycket mer läsbar (och minnesvärd) men också mer SEO-vänlig. Detta är i en nötskal, vilka omskrivningar gör.

Hur fungerar det?

Nu http://example.com/portoflio/wordpress/my-fancy-plugin existerar inte som en katalog eller en fil. Så hur tjänar WordPress upp rätt innehåll? När WordPress får en "ganska permalink" som ovan måste den konvertera den till något som den förstår, nämligen a frågeobjekt. Mer enkelt måste det ta den fina webbadressen och kartlägga lämpliga delar till den korrekta sökvariabeln. Så för vårt exempel:

http://example.com/portoflio/wordpress/my-fancy-plugin

post_type är inställd på "portfölj"
portfölj-taxonomi är inställd på "wordpress"
portfölj är inställd på "my-fancy-plugin" (postnamnet)

Då vet WordPress att vi är efter inlägg av typen 'portfölj"i"wordpress"portfölj-taxonomi"taxonomy term med namn"my-fancy-plugin'. (Som du kanske har gissat är de två första faktiskt överflödiga). WordPress utför sedan den frågan, väljer den lämpliga mallen för att visa resultaten och tjänar så till tittaren. Men tydligt WordPress inte bara gissa hur man tolkar webbadresserna, det måste höra ...

Det börjar med .htaccess

Förutsatt att du kan och har aktiverat ganska permalink på din Inställningar -> Permalinks-sida (se Codex för minimikrav - för WordPress på Nginx-servrar finns det här plug-in) - då börjar saker med .htaccess fil. Det spelar en enkel och ändå viktig roll. WordPress innehåller något som liknar följande i den här filen:

 # BEGIN WordPress  RewriteEngine On RewriteBase / RewriteRule ^ index \ .php $ - [L] RewriteCond% REQUEST_FILENAME! -F RewriteCond% REQUEST_FILENAME! -D RewriteRule. /index.php [L]  # END WordPress

Detta kontrollerar helt enkelt om filen eller katalogen faktiskt existerar - och om det gör det, är du helt enkelt där. Till exempel:

http://example.com/blog/wp-content/uploads/2012/04/my-picture.png

Skulle helt enkelt ta dig PNG-bilagan "my-picture.png'. Men som i fallet med:

http://example.com/blog/portoflio/wordpress/my-fancy-plugin

Där katalogen inte existerar - du tas till din WordPress " index.php fil. Det är den här filen som stöter WordPress.

Tolka webbadressen

Vid den här tiden vet WordPress inte ännu vad du är ute efter. Efter några initiala laddningar av WordPress och dess inställningar, avfyras den parse_request metod för WP klass (ligger i klass-wp.php fil). Det är den här metoden som tar / Portoflio / wordpress / my-fancy-plugin och omvandlar den till ett WordPress-förståeligt förfråganobjekt (nästan, det sätter faktiskt query_vars array och efteråt $ WP> query_posts gör det till en fråga).

Kortfattat jämför den här funktionen den mottagna URL-adressen (/ Portoflio / wordpress / my-fancy-plugin) med en rad "reguljära uttryck". Det här är omskrivnings array - och det kommer att se ut så här:

 kategori /(.+?)/sida/? ([0-9] 1,) /? $ => index.php? category_name = $ matchningar [1] & paged = $ matchningar [2] category /(.+ ?) /? $ => index.php? category_name = $ matchar [1] tag / ([^ /] +) / sida /? ([0-9] 1,) /? $ => index.php ? tag = $ matchningar [1] & paged = $ matchningar [2] tag / ([^ /] +) /? $ => index.php? tag = $ matchningar [1] ([0-9] 4) / ([0-9] 1,2) / ([0-9] 1,2) /? $ => Index.php? År = $ matchningar [1] & månad = $ matchningar [2] och dag = $ matchningar [3] (. +?) (/ [0-9] +)? /? $ => index.php? pagename = $ matchningar [1] & sida = $ matchningar [2]

Nycklarna för denna array är reguljära uttryck, och den mottagna URL-en jämförs mot varandra i sin tur tills det matchas mönstret för den mottagna URL-adressen. Motsvarande värde är hur webbadressen tolkas. De $ matcher array innehåller de fångade värdena (indexerade från 1) från matchningen.

Till exempel besöker www.example.com/blog/tag/my-tag, WordPress letar efter det första mönstret som matchar "tag / my-tagg'. Med ovanstående array matchar den det tredje mönstret: tag / ([^ /] +) /? $. Detta berättar att WordPress tolkar webbadressen som www.example.com/blog/index.php?tag=my-tag och motsvarande "my-taggarkiv serveras.

Naturligtvis tillåter WordPress dig att anpassa den här matrisen, och resten av denna handledning är dedikerad till att visa dig hur.

Anpassa omskrivningsreglerna

Inställningar -> Permalinks

Din första anlöpshamn ska vara inställningssidan "Permalink". På den här sidan kan du ändra reglerna för standard 'posta"posttyp och"kategori"och"taggartaxonomier. Alternativet "standard" har ganska permalinks inaktiverade, men du kan välja från en lista med förinställda strukturer eller skapa en anpassad struktur. Observera att anpassade strukturer inte får innehålla webbadressen till din webbplats. WordPress kan du ändra din permalinkstruktur genom att lägga till i angivna taggar som % Post% (postens namn), %år% (året posten publicerades) och %författare% (författaren till posten). En permalinkstruktur, såsom:

/% År% /% författare% /% post% /

Skulle skapa en postlänk som:

www.example.com/2012/stephen/my-post

Dokumentationen för dessa alternativ finns i WordPress Codex. (Senare visar jag dig hur man skapar egna anpassade taggar).

De angivna alternativen är dock ganska begränsade. I denna handledning ska jag fokusera på de funktioner som tillhandahålls av WordPress som erbjuder större kontroll över permalinkstrukturer och hur de tolkas. Jag kommer inte att täcka omskrivningsalternativen som är tillgängliga för anpassade posttyper eller taxonomier, eftersom det kommer att beskrivas i del 2.

Varför Spola omskrivningsreglerna?

Efter någon ändring av omskrivningsreglerna (till exempel genom att antingen använda någon av följande metoder eller registrera en anpassad posttyp eller taxonomi) kan du upptäcka att de nya reglerna inte träder i kraft. Detta beror på att du måste spola omskrivningsreglerna. Detta kan göras på ett av två sätt:

Besök bara Inställningar -> Permalink
Ring upp flush_rewrite_rules () (omfattas av del 2)

Vad gör det här? Minns att parse_request Metoden jämför förfrågan mot en omskrivnings array. Denna matris bor i databasen. Spolning av omskrivningsregler uppdaterar databasen för att spegla dina ändringar - och tills du gör det kommer de inte att bli igenkända. Men parse_request också skriver till .htaccess fil. Detta gör det till en dyr operation. Så, även om jag inte kommer att täcka användningen av flush_rewrite_rules () tills del 2 kommer jag att ge dig den här varningen: Ring inte flush_rewrite_rules på varje sidlast. Plug-ins bör bara ringa detta när plugin-modulen är aktiverad och inaktiverad.

Lägg till omskrivningsregeln

De add_rewrite_rule kan du lägga till ytterligare regler till omskrivningsuppsättningen. Den här funktionen accepterar tre argument:

regel - ett regelbundet uttryck för att jämföra begäran URL mot
skriva om - frågesträngen som användes för att tolka regeln. De $ matcher array innehåller de fångade matchningarna och startar från indexet '1'.
placera - 'topp"eller"botten'. Var ska man placera regeln: högst upp på omskrivningsfältet eller botten. WordPress skannar från toppen av matrisen till botten och slutar så snart den hittar en matchning. För att dina regler ska ha företräde framför befintliga regler måste du ange detta till "topp'. Standard är "botten'.

Notera: om du använder add_rewrite_rule flera gånger, var och en med position "topp"- den först samtal har företräde framför efterföljande samtal.

Låt oss anta att våra inlägg har ett händelsedatum förknippat med dem och vi vill ha den här strukturen: www.example.com/blog/the-olympics-begin/2012-07-27 tolkas som www.example.com/blog/index.php?postname=the-olympics-begin&eventdate=2012-07-27 då kan vi lägga till denna regel enligt följande:

 funktionen wptuts_add_rewrite_rules () add_rewrite_rule ('^ ([^ /] *) / ([0-9] 4 - [0-9] 2 - [0-9] 2) /? $' / / String följt av ett snedstreck följt av ett datum i formuläret "2012-04-21" följt av ett annat slash "index.php? Pagename = $ matchningar [1] & eventdate = $ matchningar [2] ',' top ' );  add_action ('init', 'wptuts_add_rewrite_rules');

Följande skulle tolka www.example.com/olympics/2012/rowing som www.example.com/index.php?p=17&olymyear=2012&game=rowing

 add_rewrite_rule ('^ olympics / ([0-9] 4) / ([^ /] *)', 'index.php? p = 17 & olymyear = $ matchningar [1] & match = $ matchningar [2] topp' );

Om du är osäker på dina vanliga uttryck kan du hitta denna introduktion och det här verktyget är användbart.

Lägg till omskrivnings-tagg

Du kanske tror att värdet av DATE (2012-07-27 i ovanstående exempel), olymyear och spel kan vara tillgängligt från WordPress 'internals via get_query_var (på samma sätt som get_query_var ( 'paged') får sidnumret du är på). WordPress känner emellertid inte automatiskt igen variabeln DATE även om det tolkas som en GET-variabel. Det finns ett par sätt att få WordPress att identifiera anpassade variabler. En är att använda query_vars filtrera som visas i avsnittet "Lägg till anpassad slutpunkt" nedan. Alternativt kan vi gå ett steg längre och använda add_rewrite_tag att registrera en anpassad tagg som standard % Post% och %år%

Den här funktionen accepterar tre argument:

taggnamn - (med ledande och efterföljande%) t ex: % DATE%
regex - Regelbundet uttryck för att validera värdet, t.ex. '([0-9] 4 - [0-9] 2 - [0-9] 2)'
fråga - (valfritt) Hur taggen tolkas, t.ex. 'DATE ='. Om det anges måste det sluta med en '='.

 funktion wptuts_register_rewrite_tag () add_rewrite_tag ('% eventdate%', '([0-9] 4 - [0-9] 2 - [0-9] 2)');  add_action ('init', 'wptuts_register_rewrite_tag');

Inte bara kommer get_query_var ( 'DATE') returnera värdet av datumet i webbadressen, men du kan använda taggen % DATE% i inställningarna -> Permalink (tillsammans med standardvärdet %år%, % Post% etc.) och WordPress tolkar det korrekt. Tyvärr När man skapar ett inläggs permalink vet WordPress inte hur man ska ersätta % DATE% med lämpligt värde: så våra post permalinks hamnar som:

www.example.com/the-olympics-begin/%eventdate%

Vi behöver ersätta % DATE% med ett lämpligt värde, och vi kan göra det med att använda POST_LINK filtrera. (I det här exemplet kommer jag att anta att värdet är lagrat i ett anpassat fält "DATE').

 funktionen wp_tuts_filter_post_link ($ permalink, $ post) // Kontrollera om% eventdate% taggen finns i URL: om (false === strpos ($ permalink, '% eventdate%')) returnera $ permalink; // Hämta händelsedatumet lagrat i posten meta $ event_date = get_post_meta ($ post-> ID, 'eventdate', true); // Tyvärr, om inget datum hittas, måste vi ange ett "standardvärde". $ event_date = (! tomt ($ event_date)? $ event_date: '2012-01-01'); $ event_date = urlencode ($ event_date); // Byt ut '% eventdate%' $ permalink = str_replace ('% eventdate%', $ event_date, $ permalink); returnera $ permalink;  add_filter ('post_link', 'wp_tuts_filter_post_link', 10, 2);

I del 2 i denna serie kommer jag att täcka anpassade taggar för anpassade posttyper.

Lägg till anpassad slutpunkt

Slutpunkter är taggar som bifogas URL-adressen (/ Trackback / [värde] är den vanligaste). Den har flera andra möjliga användningsområden: visar olika mallar beroende på värdet, anpassade meddelanden och visning av inlägg i olika "format" (utskrivbar, XML, JSON etc).

Du kan skapa ändpunkter med add_rewrite_endpoint. Denna funktion accepterar två argument:

namn - Slutpunktens namn, t.ex. 'json','form', etc.
var - Slutpunktsmask som anger var slutpunkten ska läggas till. Detta bör vara en av EP_ * -konstanterna som anges nedan (eller en kombination med bitvis operatorer). När du registrerar egna posttyper kan du skapa en mask för den posttypen:

Standard slutpunktsmaskar är:

EP_PERMALINK - för post permalinks
EP_ATTACHMENT - för bilagor
EP_DATE - för datumarkiv
EP_YEAR - för årets arkiv
EP_MONTH - för månadsarkiv
EP_DAY - för "dag" arkiv
EP_ROOT - för roten till webbplatsen
EP_COMMENTS - för kommentarer
EP_SEARCH - för sökningar
EP_CATEGORIES - för kategorier
EP_TAGS - för taggar
EP_AUTHORS - för arkiv av författarens inlägg
EP_PAGES - för sidor
EP_ALL - för allt

Slutpunkter är extremt flexibla, du kan använda dem med bitvisa operatörer så att du till exempel kan lägga till en slutpunkt för att posta och sända permalink med EP_PERMALINK | EP_PAGES.

 funktion wptuts_add_endpoints () add_rewrite_endpoint ('myendpoint', EP_PERMALINK); // Lägger till ändpunkt till permalinks add_rewrite_endpoint ('anotherendpoint', EP_AUTHORS | EP_SEARCH); // lägger till slutpunkt för webbadresser för upphovsmän eller sökresultat add_action ('init', 'wptuts_add_endpoints');

Som ett kort exempel kan slutpunkter vara användbara för formulärinslag. Antag att vi har en kontaktformulärssida med namn Kontaktformulär och med permalink: www.example.com/contact och vill ha webbadresserna:

www.example.com/contact/submission/success - för att återspegla en framgångsrik formulärinsändning
www.example.com/contact/submission/error - att återspegla en misslyckad formulärinsändning

Detta kan göras med slutpunkter. Följande är ett mycket enkelt exempel på hur du använder slutpunkter, och så är formuläret oerhört grundläggande i sina kontroller (och gör faktiskt ingenting med data). Normalt skulle ett formulär som det här fungera bäst i ett plugin-program med hjälp av kortnummer - men i det här exemplet ska du skapa en sida med följande mall och resten av koden som du kan lägga in functions.php

  Mitt enkla kontaktformulär 
   ditt meddelande har skickats! 
   hoppsan! Det verkar ha varit ett fel ... 
     Ditt meddelande:        E-post bekräftelse:

(Om du undrar, hänvisar honungen till den här väldigt grundläggande metoden för att fånga skräppost som beskrivs här. Det är verkligen inte dumt bevis, men korrekt formbehandling och skräppostskydd är borta här). Nu skapar vi vår slutpunkt:

 funktion wptuts_add_endpoint () add_rewrite_endpoint ('form', EP_PAGES);  add_action ('init', 'wptuts_add_endpoint');

Nästa lägger vi till vår "form"variabel till arrayen av igenkända variabler:

 funktion wptuts_add_queryvars ($ query_vars) $ query_vars [] = 'form'; returnera $ query_varslar;  add_filter ('query_vars', 'wptuts_add_queryvars');

Slutligen tillhandahåller vi en formulärhanterare, som kommer att bearbeta data, skicka in formuläret och sedan omdirigera tillbaka till kontaktsidan med det relevanta slutpunktvärdet bifogade.

 funktion wptuts_form_handler () // Vill vi bearbeta formuläret om (! isset ($ _POST ['action']) || 'wptuts_send_message'! = $ _POST ['action']) returnerar; // ID på kontaktformulärssidan $ form_id = 2163; $ redirect = get_permalink ($ form_id); // Kontrollera nonces $ data = $ _POST ['wptuts_contact']; om ! isset ($ _ POST ['wptuts_contact_nonce']) ||! wp_verify_nonce ($ _ POST ['wptuts_contact_nonce'], 'wptuts_send_message')) // Misslyckades nonce check $ redirect. = 'form / error'; wp_redirect ($ omdirigering); utgång();  om (! tomt ($ data ['bekräftelse'])) // bin i honungen ... $ omdirigering. = 'form / error'; wp_redirect ($ omdirigering); utgång();  // Santize och validera data etc. // Gör så egentligen något med saniterade data // Framgångsrik! $ redirect. = 'form / success'; wp_redirect ($ omdirigering); utgång();  add_action ('init', 'wptuts_form_handler');

Självklart kan även detta exempel förbättras avsevärt genom att ge mer detaljerade felmeddelanden som förklarar orsaken till fel.

Lägger till en anpassad flöde

Med vackra permalinks aktiverade WordPress producerar automatiskt vackra webbadresser för din webbplatss flöde: www.example.com/feed/rss. De add_feed funktionen kan du skapa en anpassad matning, som om ganska permalink är aktiverade, kommer också att ha en "söt" URL. Denna funktion accepterar två argument:

matningsnamn - Namnet på flödet som det kommer att visas i foder / [feed-namn]
mata återuppringning - Funktionen som är ansvarig för att visa foderinnehållet.

Följande är avsedd som ett exempel på add_feed, och ger en mycket grundläggande anpassad matning.

 funktion wptuts_events_feed_callback () $ custom_feed = new WP_Query (array ('meta_key' => 'eventdate')); rubrik ('Content-Type:'. feed_content_type ('rss-http'). '; charset = ". get_option (" blog_charset "), sant); eko "'; ?>   Mitt anpassade flöde     have_posts ()):?> have_posts ()): $ custom_feed-> the_post (); ?>  <?php the_title_rss() ?>    ]]>       Efter spolning av permalinks kommer matningen att finnas tillgänglig på www.example.com/feed/events.
 
 Kontrollera omskrivningsreglerna
 När du har lagt till några av dina egna omskrivningsregler (och spolas dem), kommer du noga att kolla om de fungerar korrekt - och om de inte är det, ta reda på vad som går fel. För detta rekommenderade jag starkt Monkeyman Rewrite Analyzer plug-in, en gratis plug-in tillgänglig i WordPress-förvaret. När den här pluggen har aktiverats lägger du till en sida i avsnittet "Verktyg", som listar alla dina omskrivningsregler.
  Du kan också testa reglerna genom att ge den ett exempel på webbadressen, och plugin-modulen filtrerar reglerna för att visa bara matchande mönster och anger hur WordPress tolkar webbadressen.
  Ha det roligt och håll ett öga på del 2, kommer snart!
  Observera: Det finns för tillfället ett fel i vår syntaxlampa som visar "tömma()" som "emptyempty ()". Glöm inte att justera din kod i enlighet med detta.
 



		
			
	   
	




Koda