wp_list_bookmarks( string|array $args = '' ): void|string

Description

Parameters

$argsstring|arrayoptional

String or array of arguments to list bookmarks.Default: ''

• $orderbystringdefault: 'name'

  How to order the links by. Accepts post fields.

• $orderstringdefault: 'ASC'

  Whether to order bookmarks in ascending or descending order. Accepts 'ASC' (ascending) or 'DESC' (descending).

• $limitintdefault: -1

  Amount of bookmarks to display. Accepts 1+ or -1 for all.

• $categorystringdefault: empty

  Comma-separated list of category IDs to include links from.

• $category_namestringdefault: empty

  Category to retrieve links for by name.

• $hide_invisibleint|booldefault: 1|true

  Whether to show or hide links marked as 'invisible'. Accepts 1|true or 0|false.

• $show_updatedint|booldefault: 0|false

  Whether to display the time the bookmark was last updated. Accepts 1|true or 0|false.

• $echoint|booldefault: 1|true

  Whether to echo or return the formatted bookmarks. Accepts 1|true (echo) or 0|false (return).

• $categorizeint|booldefault: 1|true

  Whether to show links listed by category or in a single column. Accepts 1|true (by category) or 0|false (one column).

• $show_descriptionint|booldefault: 0|false

  Whether to show the bookmark descriptions. Accepts 1|true or 0|false.

• $title_listringdefault: 'Bookmarks'

  What to show before the links appear.

• $title_beforestringdefault: ''

  The HTML or text to prepend to the $title_li string.

• $title_afterstringdefault: ''

  The HTML or text to append to the $title_li string.

• $classstring|arraydefault: 'linkcat'

  The CSS class or an array of classes to use for the $title_li.

• $category_beforestringdefault: ''

  The HTML or text to prepend to $title_before if $categorize is true. String must contain '%id' and '%class' to inherit the category ID and the $class argument used for formatting in themes.

• $category_afterstringdefault: ''

  The HTML or text to append to $title_after if $categorize is true.

• $category_orderbystringdefault: 'name'

  How to order the bookmark category based on term scheme if $categorize is true.

• $category_orderstringdefault: 'ASC'

  Whether to order categories in ascending or descending order if $categorize is true. Accepts 'ASC' (ascending) or 'DESC' (descending).

Return

void|string

Void if 'echo' argument is true, HTML list of bookmarks if 'echo' is false.

Hooks fired · 2

2 hooks fire while wp_list_bookmarks() runs, in this order:

1. 1
   apply_filters( link_category )filterline 280 (+69 into the body)

   Filters the category name.

2. 2
   apply_filters( wp_list_bookmarks )filterline 321 (+110 into the body)

   Filters the bookmarks list before it is echoed or returned.

Uses · 6

• __()Retrieves the translation of $text.
• wp_parse_args()Merges user defined arguments into defaults array.
• get_terms()Retrieves the terms in a given taxonomy or list of taxonomies.
• get_bookmarks()Retrieves the list of bookmarks.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• _walk_bookmarks()The formatted output of a list of bookmarks.

Used by · 3

• WP_Widget_Links::widget()Outputs the content for the current Links widget instance.
• wp_get_links()Gets the links associated with category.
• wp_get_linksbyname()Gets the links associated with the named category.

Source

View on Trac ↗View on GitHub ↗

211function wp_list_bookmarks( $args = '' ) {212	$defaults = array(213		'orderby'          => 'name',214		'order'            => 'ASC',215		'limit'            => -1,216		'category'         => '',217		'exclude_category' => '',218		'category_name'    => '',219		'hide_invisible'   => 1,220		'show_updated'     => 0,221		'echo'             => 1,222		'categorize'       => 1,223		'title_li'         => __( 'Bookmarks' ),224		'title_before'     => '<h2>',225		'title_after'      => '</h2>',226		'category_orderby' => 'name',227		'category_order'   => 'ASC',228		'class'            => 'linkcat',229		'category_before'  => '<li id="%id" class="%class">',230		'category_after'   => '</li>',231	);232 233	$parsed_args = wp_parse_args( $args, $defaults );234 235	$output = '';236 237	if ( ! is_array( $parsed_args['class'] ) ) {238		$parsed_args['class'] = explode( ' ', $parsed_args['class'] );239	}240	$parsed_args['class'] = array_map( 'sanitize_html_class', $parsed_args['class'] );241	$parsed_args['class'] = trim( implode( ' ', $parsed_args['class'] ) );242 243	if ( $parsed_args['categorize'] ) {244		$cats = get_terms(245			array(246				'taxonomy'     => 'link_category',247				'name__like'   => $parsed_args['category_name'],248				'include'      => $parsed_args['category'],249				'exclude'      => $parsed_args['exclude_category'],250				'orderby'      => $parsed_args['category_orderby'],251				'order'        => $parsed_args['category_order'],252				'hierarchical' => 0,253			)254		);255		if ( empty( $cats ) ) {256			$parsed_args['categorize'] = false;257		}258	}259 260	if ( $parsed_args['categorize'] ) {261		// Split the bookmarks into ul's for each category.262		foreach ( (array) $cats as $cat ) {263			$params    = array_merge( $parsed_args, array( 'category' => $cat->term_id ) );264			$bookmarks = get_bookmarks( $params );265			if ( empty( $bookmarks ) ) {266				continue;267			}268			$output .= str_replace(269				array( '%id', '%class' ),270				array( "linkcat-$cat->term_id", $parsed_args['class'] ),271				$parsed_args['category_before']272			);273			/**274			 * Filters the category name.275			 *276			 * @since 2.2.0277			 *278			 * @param string $cat_name The category name.279			 */280			$catname = apply_filters( 'link_category', $cat->name );281 282			$output .= $parsed_args['title_before'];283			$output .= $catname;284			$output .= $parsed_args['title_after'];285			$output .= "\n\t<ul class='xoxo blogroll'>\n";286			$output .= _walk_bookmarks( $bookmarks, $parsed_args );287			$output .= "\n\t</ul>\n";288			$output .= $parsed_args['category_after'] . "\n";289		}290	} else {

History

Introduced in 2.1.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.9.7 tag, from src/wp-includes/bookmark-template.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.