फ़ंक्शन की परीक्षा: wp_nav

Hindi (हिंदी) translation by Ashish Rampal (you can also view the original English article)

जब WordPress 3 हमे नयी मेनू कार्यक्षमता (functionality) के साथ हमे प्रस्तुत किया गया, तो इसने हमारे मेनू को देखने के नजरिये को हमेशा के लिए बदल दिया। अब हम सामान्य पेज लिस्टिंग फ़ंक्शंस का उपयोग करने या हमारे स्वयं के कस्टम मेनू फ़ंक्शंस का निर्माण करने के लिए केटेगरी और पेज मेनू को इंटेग्रटे (integrate) करने के साथ-साथ nav मेनू के भीतर बाहरी या हार्ड लिंक किए गए आइटम के लिए बाध्य नहीं थे। लेकिन इस नई फंक्शनलिटी के साथ हम कैसे कस्टम कर सकते हैं? इस ट्यूटोरियल में, हम उन सभी चीजों में गहराई से चलेंगे जो कि wp_nav_menu फंक्शन करता है, Walker Class का उपयोग एक sub डिस्क्रिप्शन जोड़ने के लिए करें, और इसके कुछ संबंधित कार्यों पर स्पर्श करें.

The Parameters

फ़ंक्शन के साथ काम करने के लिए कई पैरामीटर्स हैं। यह कुछ डिफॉल्ट्स है जो की WordPress.org Codex में सूचीबद्ध है:

<?php $defaults = array(
  'theme_location'  => ,
	'menu'            => ,
	'container'       => 'div',
	'container_class' => 'menu-{menu slug}-container',
	'container_id'    => ,
	'menu_class'      => 'menu',
	'menu_id'         => ,
	'echo'            => true,
	'fallback_cb'     => 'wp_page_menu',
	'before'          => ,
	'after'           => ,
	'link_before'     => ,
	'link_after'      => ,
	'items_wrap'      => '<ul id=\"%1$s\" class=\"%2$s\">%3$s</ul>',
	'depth'           => 0,
	'walker'          =>
);
?>

<?php wp_nav_menu( $defaults ); ?>

Theme की Location

इस पैरामीटर का उपयोग करके, हम एक थीम (theme) स्थान सेट कर सकते हैं जो मेनू के पेज पर उपयोग किया जाता है ताकि मैन्युअल (manual) रूप से निर्धारित किया जा सके कि कौन से मेनू वहां दिखाई देने चाहिए। यह थीम वितरकों (distributors) के लिए बहुत उपयोगी है क्योंकि आप केवल एक मेनू प्रदर्शित करने के लिए कंडीशंस का उपयोग कर सकते हैं, यदि यूज़र्स ने उस स्थान के लिए एक मेनू परिभाषित (define) किया है। एकमात्र अन्य आवश्यकता यह है कि आप उन स्थानों को पंजीकृत (register) करने के लिए फ़ंक्शन register_nav_menu() का उपयोग करें। यह आमतौर पर आपकी फ़ंक्शन फ़ाइलों से किया जाता है जब आप मेनू के लिए सपोर्ट सेट करते हैं

मान लीजिए कि हमने "primary" नामक एक थीम स्थान (location) को पंजीकृत (register) किया है, यह मानते हुए हमारे कस्टम मेनू फ़ंक्शन पैरामीटर का निर्माण शुरू करें।

$params = array(
	'theme_location' => 'primary'
);

मेन्यू (Menu)

यह पैरामीटर मैन्युअल रूप से परिभाषित करता है कि कौन से मेनू का उपयोग किया जाना चाहिए। हमारे उदाहरण में, हम केवल एक सामान्य (generic) मेनू स्थान (location) सेट कर रहे हैं और उपयोग करने के लिए सटीक (exact) कोई भी परिभाषित नहीं कर रहे हैं, लेकिन अगर हम "Primary Navigation" नामक एक मेनू का उपयोग करने के लिए फंक्शन को बताना चाहते हैं, तो हमारे पैरामीटर इस तरह दिखाई देंगे:

$params = array(
	'theme_location' => 'primary',
	'menu' => 'Primary Navigation'
);

कंटेनर (Container)

डिफ़ॉल्ट रूप से, हमारे मेनू को एक div में wrap कर दिया जाएगा, लेकिन यदि आप मेरी तरह हैं, तो आपको आमतौर पर इसकी ज़रूरत नहीं है और संभवत: divs की संख्या और अन्य टैग को अपने कोड को जितना व्यवस्थित हो सके उतना व्यवस्थित रखने के लिए इस्तेमाल किया जा रहा है। आप html5 के <section> या <nav> जैसे अलग अलग टैग को परिभाषित करने के लिए भी इस पैरामीटर का उपयोग कर सकते हैं. हमारे उदाहरण के लिए, हम नहीं चाहते कि कंटेनर को डिफॉल्ट कंटेनर की वैल्यूज को बदलना चाहिए क्योंकि Twenty Eleven थीम इन स्टाइल्स पर वहां निर्भर है।

कंटेनर क्लास और कंटेनर ID

जैसा कि आप काफी अनुमान लगा सकते हैं, ये पैरामीटर कंटेनर के लिए एक क्लास और ID सेट करने के लिए उपयोग किया जाता है। चूंकि हम इसे पूरी तरह से हटा रहे हैं, इसलिए हमें वैल्यूज को परिभाषित करने की कोई आवश्यकता नहीं है।

मेनू कक्षा और मेनू ID

यह कार्य पिछली पैरामीटर की तरह ही है, सिवाय इसके की इस बार हम निश्चित रूप से "nav" की एक ID सेट करना चाहते हैं क्योंकि यह ID है जिसे हम अपनी स्टाइलशीट में नेविगेशन बार को स्टाइल देने में इस्तेमाल करेंगे।

$params = array(
	'theme_location' => 'primary',
	'container' => false,
	'menu_id' => 'nav'
);

Echo

आप इस पैरामीटर का उपयोग यह बता सकते हैं कि क्या आप परिणाम (echo) प्रदर्शित करना चाहते हैं, या इसे PHP में उपयोग के लिए return करना चाहते हैं। यह आइटम बूलियन (boolean) है इसलिए इसे return करने के लिए बस इस पैरामीटर को 0 पर सेट करें।

Fallback CB

यह एक कॉलबैक फ़ंक्शन है, जिस पर कोई मेनू नहीं मिले, तो आप फॉलबैक कर सकते हैं। डिफ़ॉल्ट रूप से यह wp_page_menu() द्वारा पुराने स्टैंड का उपयोग करता है और इस फ़ंक्शन के सभी समान पैरामीटर्स को भी पास करता है।

Before and After

इन आइटम्स को यह बताने के लिए परिभाषित किया जाता है की एंकर टैग (<a></a>) के पहले और बाद में क्या रखा जा सकता हैं। आप इन्हें प्रत्येक आइटम को एक वर्टीकल बार (vertical bar) से पहले इस्तेमाल कर सकते हैं या span टैग में nav आइटम wrap कर सकते हैं।

Link Before and Link After

ये काम पिछले आइटम्स के समान है जिन्हें हम कवर किया, सिवाय इसके कि जो भी आप परिभाषित करते हैं वह एंकर टैग के अंदर होगा। हमारे उदाहरण की आवश्यकता नहीं है कि हम इन का उपयोग करें ताकि हम उन्हें अनदेखा कर सकें और डिफ़ॉल्ट खाली आइटम को दो

Items Wrap

डिफ़ॉल्ट रूप से, आइटम्स को एक unordered list में मेनू id और मेनू class के साथ wrap किया जाता है। यह पैरामीटर आपको यह बदलने की सुविधा देता है कि यदि आप चाहें तो

Depth

यह पैरामीटर वास्तव में अच्छा होता है जब आप दो बार एक ही मेनू का उपयोग करना चाहते हैं, लेकिन आप wp_nav_menu() फ़ंक्शन के साथ सेट अप की गई लोकेशन पर कोई भी आइटम नहीं दिखाना चाहते हैं। उदाहरण के लिए, यदि आप प्राथमिक नेविगेशन में दूसरे स्तर के ड्रॉपडाउन को शामिल करना चाहते हैं, तो आप इसे डिफ़ॉल्ट सेटिंग पर छोड़ सकते हैं। फिर यदि आप footer नेविगेशन में एक ही पैरेंट आइटम का उपयोग करना चाहते हैं और चाइल्ड आइटम छोड़ना चाहते हैं, तो आप इस पैरामीटर को 1 की डेप्थ (depth) में सेट कर सकते हैं। डिफ़ॉल्ट "0" का अर्थ है सभी स्तर आउटपुट होंगे। हमारा उदाहरण संक्षिप्त रखने के लिए, हम मानते हैं कि प्राथमिक नेविगेशन में कोई भी चाइल्ड आइटम शामिल नहीं है।

Walker

पैरामीटर का इस्तेमाल walker ऑब्जेक्ट को परिभाषित करने के लिए किया जाता है, जिसका इस्तेमाल पूरे फ़ंक्शन द्वारा काम करने के तरीके को मैनिपुलेट (manipulate) करने के लिए किया जा सकता है और उसकी जानकारी को आउटपुट करने के लिए भी। हम अगले भाग में एक अच्छे उदाहरण के लिए जाएंगे.

Nav Menu Items में एक विवरण (Description) जोड़ना

हमारे उदाहरण के लिए, हम प्रत्येक मुख्य मेनू आइटम के लिए एक उप विवरण (sub description) जोड़ना चाहते हैं। वर्डप्रेस मेनू सिस्टम में खुद से विवरण (description) जोड़ने की कार्यक्षमता (functionality) पहले ही मौजूद है इसे चालू करने के लिए, मेनू पर जाएं और फिर टॉप दाएं कोने (top right corner) में स्क्रीन ऑप्शंस का टैब दबाएं। "Description" ऑप्शन पर क्लिक करना आपको सुनिश्चित करना होगा। इसको चेक करने के बाद, मेनू आइटम अब इस तरह दिखना चाहिए:

एक बार हमारे विवरणों (descriptions) को भरने के बाद, हमें walker क्लास बनानी और उसे wp_nav_menu() मापदंडों (parameters) में जोड़ना होगा। हम क्लास को description_navigation कॉल करेंगे इस तरह हमारे पूरे पैरामीटर कोड इस तरह दिखेंगे:

$params = array(
	'theme_location' => 'primary',
	'menu_id' => 'nav',
	'walker' => new description_walker()
);
wp_nav_menu($params);

The Walker Class

अब हम अपने Walker क्लास के उपयोग में उन विवरणों (description) को जोड़ने के लिए तैयार हैं:

class description_walker extends Walker_Nav_Menu {
	function start_el(&$output, $item, $depth, $args) {
		global $wp_query;
		$indent = ( $depth ) ? str_repeat( "\t", $depth ) : '';

		$class_names = $value = '';

		$classes = empty( $item->classes ) ? array() : (array) $item->classes;

		$class_names = join( ' ', apply_filters( 'nav_menu_css_class', array_filter( $classes ), $item ) );
		$class_names = ' class="'. esc_attr( $class_names ) . '"';

		$output .= $indent . '<li id="menu-item-'. $item->ID . '"' . $value . $class_names .'>';

		$attributes  = ! empty( $item->attr_title ) ? ' title="'  . esc_attr( $item->attr_title ) .'"' : '';
		$attributes .= ! empty( $item->target )     ? ' target="' . esc_attr( $item->target     ) .'"' : '';
		$attributes .= ! empty( $item->xfn )        ? ' rel="'    . esc_attr( $item->xfn        ) .'"' : '';
		$attributes .= ! empty( $item->url )        ? ' href="'   . esc_attr( $item->url        ) .'"' : '';
		$description  = ! empty( $item->description ) ? '<span>'.esc_attr( $item->description ).'</span>' : '';

		if($depth != 0) {
			$description = $append = $prepend = "";
		}

		$item_output = $args->before;
		$item_output .= '<a'. $attributes .'>';
		$item_output .= $args->link_before .apply_filters( 'the_title', $item->title, $item->ID );
		$item_output .= $description.$args->link_after;
		$item_output .= '</a>';
		$item_output .= $args->after;

		$output .= apply_filters( 'walker_nav_menu_start_el', $item_output, $item, $depth, $args );
	}
}

यहां बहुत कुछ चल रहा है आम तौर पर Walker क्लासेज के बारे में अधिक जानकारी के लिए, मुझे आपको एक और ट्यूटोरियल पर भेजना चाहिए: Walker क्लास को समझना आपको यहां समझने वाला सबसे महत्वपूर्ण हिस्सा यह है कि हम प्रत्येक लिंक आइटम के आउटपुट का पुनर्निर्माण (rebuild) कर रहे हैं और इसे डिस्क्रिप्शन में जोड़ रहे हैं। ऊपर दिए गए स्निपेट (snippet) की लाइन 19 पर आप यह देख सकते हैं कि हम कहां आइटम का विवरण (description) प्राप्त करते हैं और यह स्पैन टैग में लिपटे $description की वैल्यू बनाते हैं, ताकि हम विवरण (description) को अलग-अलग रूप से स्टाइल कर सकें। फिर 24-29 लाइनों में जहां हम एक साथ लिंक आइटम को वापस जोड़ते हैं, हम एंकर टैग के बंद होने से बिलकुल पहले वर्णन में जोड़ देते हैं ताकि यह लिंक का हिस्सा बन जाए।

Twenty Eleven थीम (theme) का उपयोग करते हुए, अब आपके पास ऐसा कुछ होना चाहिए जो ऐसा दिखता है:

Style It Up

चलो इसमें थोड़ा और स्टाइल जोड़ कर इसे पड़े जाने योग्य बनाते हैं:

#nav a {
	line-height: 20px;
	padding: 10px 15px;
}

#nav a span {
	display: block;
	font-size: 11px;
	color: #ccc;
}

#nav a:hover span {
	color: #999;
}

यह प्रत्येक लिंक की ऊँचाई और पैडिंग को बदल देगा, स्पैन टैग के भीतर विवरण को अपनी लाइन में छोड़ने के लिए, और अंतिम परिणाम के लिए फ़ॉन्ट आकार और रंग थोड़ा समायोजित (adjust) करेगा जिसका परिणाम इस तरह दिखेगा:

Relation Functions

न केवल आप सभी कस्टमइजशन (customizations) के साथ अपना मेनू आउटपुट करने के लिए wp_nav_menu() का उपयोग कर सकते हैं, आप इसके संबंधित कार्यों में थोड़ा आगे जा सकते हैं

`has_nav_menu()`

यह फ़ंक्शन केवल एक विशेष मेनू प्रदर्शित करने के लिए बहुत अच्छा है यदि उस मेनू को आपके थीम लोकेशन पर निर्दिष्ट (assigned) किया गया है। उदाहरण के लिए, आप कम नेविगेशन आइटम्स के लिए अपने विषय पर एक शीर्ष नेविगेशन बनाना चाह सकते हैं, जो यूज़र्स अपने मुख्य नेविगेशन में नहीं चाहते हैं। यह एक होम लिंक, "हमारे साथ विज्ञापन करें", या अन्य निचली कॉल की कार्रवाई की तरह हो सकता है लेकिन एक थीम वितरक (theme distributor) के रूप में, यदि आपको नहीं पता है कि यूज़र्स कुछ उपयोग करना चाहता है, तो ऐसी स्थिति का उपयोग करें:

if (has_nav_menu('top-menu')) {
	wp_nav_menu('theme_location='top-menu');
}

`wp_get_nav_menu_items()`

यह फ़ंक्शन किसी विशेष मेनू से आइटम का एक array return करेगा। यह विशेष रूप से उपयोगी हो सकता है यदि आप Walker क्लास का उपयोग किए बिना कस्टम मेनू लिस्ट बनाना चाहते हैं। आप मेन्यू की मौजूदा क्लास जैसी कई कार्यक्षमता (functionality) खो देते हैं, लेकिन यह आसान समाधान के लिए मेनू आइटम के एक array के माध्यम से लूप का एक शानदार तरीका है।

निष्कर्ष

आपके द्वारा नेविगेशन मेनू को अनुकूलित (customize) करने के लिए बहुत सी चीजें हैं, जब आपको लचीलेपन (flexibility) के बारे में अधिक जानकारी मिलती है जो पैरामीटर में निर्मित है और Walker क्लास के साथ अधिक नियंत्रण (control) रखने में सक्षम है। प्रत्येक आइटम में कस्टम आइकन (custom icons) के लिए "icon" की class के साथ एक और स्पैन टैग जोड़ने की आवश्यकता है? कोई बात नहीं।

प्लेसमेंट और मेन्यू के आउटपुट पर पूरा नियंत्रण रखने में सक्षम होने के नाते आपकी क्षमताओं (capabilities) को एक theme डेवलपर के रूप में विस्तारित (extend) किया जाता है जो संभावनाओं की एक न नापे जा सकने वाली वाली राशि (amount) है। क्या कुछ चीजें हैं जो आप वॉकर क्लास का उपयोग करके कर सकते हैं?

फ़ंक्शन की परीक्षा: wp_nav_menu