Walker{}WP 2.1.0AllowDynamicProperties

Класс для отображения различных древовидных структур. Используется как основа для создания своего, дочернего класса.

Этот класс позволяет собрать (вывести в виде HTML) древовидную структуру данных.

В WordPress таким древовидными структурами являются: навигационное меню, список категорий или страниц, список комментариев - все они имеют одну общую характеристику: они являются визуальным представлением древовидных структур данных.

Другими словами между элементами данных существуют отношения высшего и низшего уровня родства. Есть элементы, которые являются родителями других элементов, и, наоборот, элементы, которые являются детьми. Так например ответ на комментарий должен находиться внутри родителя, точно так же, как элемент подменю должны находится под родительским элементом дерева (или поддерева).

В дочерних классах обычно нужно описать следующие методы:

На основе этого класса работают следующие классы:

В ядре WordPress
  • Walker_Nav_Menu() — Класс ядра WordPress, который генерирует HTML код списка элементов навигационного меню WordPress.
  • Walker_Category_Checklist() — Core walker class to output an unordered list of category checkbox input elements.
  • Walker_CategoryDropdown() — Core class used to create an HTML dropdown list of Categories.
  • Walker_Comment() — Core walker class used to create an HTML list of comments.
  • Walker_PageDropdown() — Core class used to create an HTML drop-down list of pages.
  • Walker_Category() — Core class used to create an HTML list of categories.
  • Walker_Page() — Core walker class used to create an HTML list of pages.
В WooCommerce
Основа для: Walker_Nav_Menu()

Хуков нет.

Возвращает

Ничего (null).

Использование

$Walker = new Walker();
// используйте методы класса

Свойства класса

$tree_type(строка) (public)
Что обрабатывает класс.
$db_fields(строка) (public)
Используемые поля БД.
$max_pages(число) (public)
Максимальное число элементов для обхода.
По умолчанию: 1
$has_children(логический) (public)
Имеет текущий элемент дочерние элементы (true) или нет (false). Используется в методе start_el().

Методы класса

  1. public display_element( $element, &$children_elements, $max_depth, $depth, $args, &$output )
  2. public end_el( &$output, $data_object, $depth = 0, $args = array() )
  3. public end_lvl( &$output, $depth = 0, $args = array() )
  4. public get_number_of_root_elements( $elements )
  5. public paged_walk( $elements, $max_depth, $page_num, $per_page, ...$args )
  6. public start_el( &$output, $data_object, $depth = 0, $args = array(), $current_object_id = 0 )
  7. public start_lvl( &$output, $depth = 0, $args = array() )
  8. public unset_children( $element, &$children_elements )
  9. public walk( $elements, $max_depth, ...$args )

Эти методы нужно переопределить в дочернем классе в зависимости от того что нужно:

start_lvl( &$output, $depth = 0, $args = array() ) (public)
Формирует, например, открывающий тег <ul> дочернего списка.
end_lvl( &$output, $depth = 0, $args = array() ) (public)
Формирует, например, закрывающий тег </ul> дочернего списка, который открывается с помощью метода start_lvl().
start_el( &$output, $object, $depth = 0, $args = array(), $current_object_id = 0 ) (public)
Формирует, например, открывающий тег <li> с внутренним содержимым.
end_el( &$output, $object, $depth = 0, $args = array() ) (public)
Формирует, например, закрывающий тег </li>.

Эти методы не обязательно описывать в дочернем классе:

walk( $elements, $max_depth ) (public)
Основной метод, который запускается первым. Возвращает сформированный html код на основе переданного массива объектов элементов, из которых надо построить список или другую структуру (плоскую или древовидную). Работает на основе метода display_element().
display_element( $element, &$children_elements, $max_depth, $depth, $args, &$output ) (public)
Отображает один элемент, если дочерних элементов нет, или более, если есть. Когда у элемента есть вложенность, то метод замыкается сам на себя, проходя все уровни вложенности вглубь. Максимальная вложенность определена аргументом $max_depth. Если $max_depth = 1, то будут обработаны только элементы первого уровня, а дочерние пропущены. Этот метод не следует вызывать напрямую, вместо этого используйте метод walk(). Для формирования элементов использует методы start_el() -> start_lvl() -> end_lvl() -> end_el().
paged_walk( $elements, $max_depth, $page_num, $per_page ) (public)
Создает страницу вложенных элементов. Учитывая массив иерархических элементов, максимальную глубину, конкретный номер страницы и количество элементов на странице, этот метод сначала определяет все корневые элементы верхнего уровня, принадлежащие этой странице, а затем перечисляет их и всех их детей в иерархическом порядке. Работает основе методов display_element() и unset_children. Наглядным примером является использование метода классом Walker_Comment, создавая список из комментариев, в том числе и дочерних.
get_number_of_root_elements( $elements ) (public)
Вычисляет общее количество корневых элементов.
unset_children( $e, &$children_elements ) (public)
Открепляет все дочерние элементы от заданного элемента верхнего уровня. Метод замыкается сам на себя в случае, если вложенность больше 1, чтобы обойти всю иерархию переданных элементов.

Примеры

0

#1 Пример создания и использования класса

Создадим свой обработчик чтобы вывести чекбоксы для категорий (в древовидном виде).

class Walker_My_Checklist extends Walker {

	public $tree_type = 'term';

	public $db_fields = array(
		'parent' => 'parent',
		'id'     => 'term_id',
	);

	public function start_lvl( &$output, $depth = 0, $args = array() ) {
		$indent  = str_repeat( "\t", $depth );
		$output .= "$indent<ul class='children'>\n";
	}

	public function end_lvl( &$output, $depth = 0, $args = array() ) {
		$indent  = str_repeat( "\t", $depth );
		$output .= "$indent</ul>\n";
	}

	public function start_el( &$output, $term, $depth = 0, $args = array(), $current_object_id = 0 ) {

		$taxonomy = $args['taxonomy'];
		$name = "tax_input[$taxonomy]";
		$class = 'class="category-li"';

		$args['selected_cats'] = array_map( 'intval', $args['selected_cats'] ?? [] );

		$is_selected = in_array( $term->term_id, $args['selected_cats'], true );
		$is_disabled = ! empty( $args['disabled'] );

		$str = '
		<li id="{id}" {class}>
			<label class="selectit">
				<input value="{term_id}" type="checkbox" name="{input_name}" id="{input_id}"{checked}{disabled} />
				{name}
			</label>';

		$output .= strtr( $str, [
			'{id}'         => "{$taxonomy}-{$term->term_id}",
			'{class}'      => $class,
			'{term_id}'    => $term->term_id,
			'{input_name}' => "{$name}[]",
			'{input_id}'   => "in-$taxonomy-$term->term_id",
			'{checked}'    => checked( $is_selected, true, false ),
			'{disabled}'   => disabled( $is_disabled, true, false ),
			'{name}'       => esc_html( $term->name ),
		] );

	}

	public function end_el( &$output, $data_object, $depth = 0, $args = array() ) {
		$output .= "</li>\n";
	}

}

Теперь используем этот класс так:

$taxonomy = 'category';

$terms = get_terms([ 'taxonomy' => $taxonomy ]);

$walker = new Walker_My_Checklist;

$output = $walker->walk( $terms, 0, [ 'taxonomy' => $taxonomy ] );

echo htmlspecialchars( $output );

Получим:

<li id="category-3" class="category-li">
	<label class="selectit">
		<input value="3" type="checkbox" name="tax_input[category][]" id="in-category-3"/>
		Wordpress
	</label>
	<ul class='children'>

		<li id="category-5" class="category-li">
			<label class="selectit">
				<input value="5" type="checkbox" name="tax_input[category][]" id="in-category-5"/>
				Авторские Функции
			</label></li>

		<li id="category-9" class="category-li">
			<label class="selectit">
				<input value="9" type="checkbox" name="tax_input[category][]" id="in-category-9"/>
				Админка
			</label></li>

	</ul>
</li>

<li id="category-1" class="category-li">
	<label class="selectit">
		<input value="1" type="checkbox" name="tax_input[category][]" id="in-category-1"/>
		Не WordPress
	</label>
	<ul class='children'>

		<li id="category-33" class="category-li">
			<label class="selectit">
				<input value="33" type="checkbox" name="tax_input[category][]" id="in-category-33"/>
				Полезные мелочи
			</label></li>

		<li id="category-1374" class="category-li">
			<label class="selectit">
				<input value="1374" type="checkbox" name="tax_input[category][]" id="in-category-1374"/>
				Сервисы и хостинги
			</label></li>
	</ul>
</li>

Заметки

  • Пакет: WordPress

Список изменений

С версии 2.1.0 Введена.

Код Walker{} WP 6.4.3

class Walker {
	/**
	 * What the class handles.
	 *
	 * @since 2.1.0
	 * @var string
	 */
	public $tree_type;

	/**
	 * DB fields to use.
	 *
	 * @since 2.1.0
	 * @var string[]
	 */
	public $db_fields;

	/**
	 * Max number of pages walked by the paged walker.
	 *
	 * @since 2.7.0
	 * @var int
	 */
	public $max_pages = 1;

	/**
	 * Whether the current element has children or not.
	 *
	 * To be used in start_el().
	 *
	 * @since 4.0.0
	 * @var bool
	 */
	public $has_children;

	/**
	 * Starts the list before the elements are added.
	 *
	 * The $args parameter holds additional values that may be used with the child
	 * class methods. This method is called at the start of the output list.
	 *
	 * @since 2.1.0
	 * @abstract
	 *
	 * @param string $output Used to append additional content (passed by reference).
	 * @param int    $depth  Depth of the item.
	 * @param array  $args   An array of additional arguments.
	 */
	public function start_lvl( &$output, $depth = 0, $args = array() ) {}

	/**
	 * Ends the list of after the elements are added.
	 *
	 * The $args parameter holds additional values that may be used with the child
	 * class methods. This method finishes the list at the end of output of the elements.
	 *
	 * @since 2.1.0
	 * @abstract
	 *
	 * @param string $output Used to append additional content (passed by reference).
	 * @param int    $depth  Depth of the item.
	 * @param array  $args   An array of additional arguments.
	 */
	public function end_lvl( &$output, $depth = 0, $args = array() ) {}

	/**
	 * Starts the element output.
	 *
	 * The $args parameter holds additional values that may be used with the child
	 * class methods. Also includes the element output.
	 *
	 * @since 2.1.0
	 * @since 5.9.0 Renamed `$object` (a PHP reserved keyword) to `$data_object` for PHP 8 named parameter support.
	 * @abstract
	 *
	 * @param string $output            Used to append additional content (passed by reference).
	 * @param object $data_object       The data object.
	 * @param int    $depth             Depth of the item.
	 * @param array  $args              An array of additional arguments.
	 * @param int    $current_object_id Optional. ID of the current item. Default 0.
	 */
	public function start_el( &$output, $data_object, $depth = 0, $args = array(), $current_object_id = 0 ) {}

	/**
	 * Ends the element output, if needed.
	 *
	 * The $args parameter holds additional values that may be used with the child class methods.
	 *
	 * @since 2.1.0
	 * @since 5.9.0 Renamed `$object` (a PHP reserved keyword) to `$data_object` for PHP 8 named parameter support.
	 * @abstract
	 *
	 * @param string $output      Used to append additional content (passed by reference).
	 * @param object $data_object The data object.
	 * @param int    $depth       Depth of the item.
	 * @param array  $args        An array of additional arguments.
	 */
	public function end_el( &$output, $data_object, $depth = 0, $args = array() ) {}

	/**
	 * Traverses elements to create list from elements.
	 *
	 * Display one element if the element doesn't have any children otherwise,
	 * display the element and its children. Will only traverse up to the max
	 * depth and no ignore elements under that depth. It is possible to set the
	 * max depth to include all depths, see walk() method.
	 *
	 * This method should not be called directly, use the walk() method instead.
	 *
	 * @since 2.5.0
	 *
	 * @param object $element           Data object.
	 * @param array  $children_elements List of elements to continue traversing (passed by reference).
	 * @param int    $max_depth         Max depth to traverse.
	 * @param int    $depth             Depth of current element.
	 * @param array  $args              An array of arguments.
	 * @param string $output            Used to append additional content (passed by reference).
	 */
	public function display_element( $element, &$children_elements, $max_depth, $depth, $args, &$output ) {
		if ( ! $element ) {
			return;
		}

		$id_field = $this->db_fields['id'];
		$id       = $element->$id_field;

		// Display this element.
		$this->has_children = ! empty( $children_elements[ $id ] );
		if ( isset( $args[0] ) && is_array( $args[0] ) ) {
			$args[0]['has_children'] = $this->has_children; // Back-compat.
		}

		$this->start_el( $output, $element, $depth, ...array_values( $args ) );

		// Descend only when the depth is right and there are children for this element.
		if ( ( 0 == $max_depth || $max_depth > $depth + 1 ) && isset( $children_elements[ $id ] ) ) {

			foreach ( $children_elements[ $id ] as $child ) {

				if ( ! isset( $newlevel ) ) {
					$newlevel = true;
					// Start the child delimiter.
					$this->start_lvl( $output, $depth, ...array_values( $args ) );
				}
				$this->display_element( $child, $children_elements, $max_depth, $depth + 1, $args, $output );
			}
			unset( $children_elements[ $id ] );
		}

		if ( isset( $newlevel ) && $newlevel ) {
			// End the child delimiter.
			$this->end_lvl( $output, $depth, ...array_values( $args ) );
		}

		// End this element.
		$this->end_el( $output, $element, $depth, ...array_values( $args ) );
	}

	/**
	 * Displays array of elements hierarchically.
	 *
	 * Does not assume any existing order of elements.
	 *
	 * $max_depth = -1 means flatly display every element.
	 * $max_depth = 0 means display all levels.
	 * $max_depth > 0 specifies the number of display levels.
	 *
	 * @since 2.1.0
	 * @since 5.3.0 Formalized the existing `...$args` parameter by adding it
	 *              to the function signature.
	 *
	 * @param array $elements  An array of elements.
	 * @param int   $max_depth The maximum hierarchical depth.
	 * @param mixed ...$args   Optional additional arguments.
	 * @return string The hierarchical item output.
	 */
	public function walk( $elements, $max_depth, ...$args ) {
		$output = '';

		// Invalid parameter or nothing to walk.
		if ( $max_depth < -1 || empty( $elements ) ) {
			return $output;
		}

		$parent_field = $this->db_fields['parent'];

		// Flat display.
		if ( -1 == $max_depth ) {
			$empty_array = array();
			foreach ( $elements as $e ) {
				$this->display_element( $e, $empty_array, 1, 0, $args, $output );
			}
			return $output;
		}

		/*
		 * Need to display in hierarchical order.
		 * Separate elements into two buckets: top level and children elements.
		 * Children_elements is two dimensional array. Example:
		 * Children_elements[10][] contains all sub-elements whose parent is 10.
		 */
		$top_level_elements = array();
		$children_elements  = array();
		foreach ( $elements as $e ) {
			if ( empty( $e->$parent_field ) ) {
				$top_level_elements[] = $e;
			} else {
				$children_elements[ $e->$parent_field ][] = $e;
			}
		}

		/*
		 * When none of the elements is top level.
		 * Assume the first one must be root of the sub elements.
		 */
		if ( empty( $top_level_elements ) ) {

			$first = array_slice( $elements, 0, 1 );
			$root  = $first[0];

			$top_level_elements = array();
			$children_elements  = array();
			foreach ( $elements as $e ) {
				if ( $root->$parent_field == $e->$parent_field ) {
					$top_level_elements[] = $e;
				} else {
					$children_elements[ $e->$parent_field ][] = $e;
				}
			}
		}

		foreach ( $top_level_elements as $e ) {
			$this->display_element( $e, $children_elements, $max_depth, 0, $args, $output );
		}

		/*
		 * If we are displaying all levels, and remaining children_elements is not empty,
		 * then we got orphans, which should be displayed regardless.
		 */
		if ( ( 0 == $max_depth ) && count( $children_elements ) > 0 ) {
			$empty_array = array();
			foreach ( $children_elements as $orphans ) {
				foreach ( $orphans as $op ) {
					$this->display_element( $op, $empty_array, 1, 0, $args, $output );
				}
			}
		}

		return $output;
	}

	/**
	 * Produces a page of nested elements.
	 *
	 * Given an array of hierarchical elements, the maximum depth, a specific page number,
	 * and number of elements per page, this function first determines all top level root elements
	 * belonging to that page, then lists them and all of their children in hierarchical order.
	 *
	 * $max_depth = 0 means display all levels.
	 * $max_depth > 0 specifies the number of display levels.
	 *
	 * @since 2.7.0
	 * @since 5.3.0 Formalized the existing `...$args` parameter by adding it
	 *              to the function signature.
	 *
	 * @param array $elements  An array of elements.
	 * @param int   $max_depth The maximum hierarchical depth.
	 * @param int   $page_num  The specific page number, beginning with 1.
	 * @param int   $per_page  Number of elements per page.
	 * @param mixed ...$args   Optional additional arguments.
	 * @return string XHTML of the specified page of elements.
	 */
	public function paged_walk( $elements, $max_depth, $page_num, $per_page, ...$args ) {
		if ( empty( $elements ) || $max_depth < -1 ) {
			return '';
		}

		$output = '';

		$parent_field = $this->db_fields['parent'];

		$count = -1;
		if ( -1 == $max_depth ) {
			$total_top = count( $elements );
		}
		if ( $page_num < 1 || $per_page < 0 ) {
			// No paging.
			$paging = false;
			$start  = 0;
			if ( -1 == $max_depth ) {
				$end = $total_top;
			}
			$this->max_pages = 1;
		} else {
			$paging = true;
			$start  = ( (int) $page_num - 1 ) * (int) $per_page;
			$end    = $start + $per_page;
			if ( -1 == $max_depth ) {
				$this->max_pages = ceil( $total_top / $per_page );
			}
		}

		// Flat display.
		if ( -1 == $max_depth ) {
			if ( ! empty( $args[0]['reverse_top_level'] ) ) {
				$elements = array_reverse( $elements );
				$oldstart = $start;
				$start    = $total_top - $end;
				$end      = $total_top - $oldstart;
			}

			$empty_array = array();
			foreach ( $elements as $e ) {
				++$count;
				if ( $count < $start ) {
					continue;
				}
				if ( $count >= $end ) {
					break;
				}
				$this->display_element( $e, $empty_array, 1, 0, $args, $output );
			}
			return $output;
		}

		/*
		 * Separate elements into two buckets: top level and children elements.
		 * Children_elements is two dimensional array, e.g.
		 * $children_elements[10][] contains all sub-elements whose parent is 10.
		 */
		$top_level_elements = array();
		$children_elements  = array();
		foreach ( $elements as $e ) {
			if ( empty( $e->$parent_field ) ) {
				$top_level_elements[] = $e;
			} else {
				$children_elements[ $e->$parent_field ][] = $e;
			}
		}

		$total_top = count( $top_level_elements );
		if ( $paging ) {
			$this->max_pages = ceil( $total_top / $per_page );
		} else {
			$end = $total_top;
		}

		if ( ! empty( $args[0]['reverse_top_level'] ) ) {
			$top_level_elements = array_reverse( $top_level_elements );
			$oldstart           = $start;
			$start              = $total_top - $end;
			$end                = $total_top - $oldstart;
		}
		if ( ! empty( $args[0]['reverse_children'] ) ) {
			foreach ( $children_elements as $parent => $children ) {
				$children_elements[ $parent ] = array_reverse( $children );
			}
		}

		foreach ( $top_level_elements as $e ) {
			++$count;

			// For the last page, need to unset earlier children in order to keep track of orphans.
			if ( $end >= $total_top && $count < $start ) {
					$this->unset_children( $e, $children_elements );
			}

			if ( $count < $start ) {
				continue;
			}

			if ( $count >= $end ) {
				break;
			}

			$this->display_element( $e, $children_elements, $max_depth, 0, $args, $output );
		}

		if ( $end >= $total_top && count( $children_elements ) > 0 ) {
			$empty_array = array();
			foreach ( $children_elements as $orphans ) {
				foreach ( $orphans as $op ) {
					$this->display_element( $op, $empty_array, 1, 0, $args, $output );
				}
			}
		}

		return $output;
	}

	/**
	 * Calculates the total number of root elements.
	 *
	 * @since 2.7.0
	 *
	 * @param array $elements Elements to list.
	 * @return int Number of root elements.
	 */
	public function get_number_of_root_elements( $elements ) {
		$num          = 0;
		$parent_field = $this->db_fields['parent'];

		foreach ( $elements as $e ) {
			if ( empty( $e->$parent_field ) ) {
				++$num;
			}
		}
		return $num;
	}

	/**
	 * Unsets all the children for a given top level element.
	 *
	 * @since 2.7.0
	 *
	 * @param object $element           The top level element.
	 * @param array  $children_elements The children elements.
	 */
	public function unset_children( $element, &$children_elements ) {
		if ( ! $element || ! $children_elements ) {
			return;
		}

		$id_field = $this->db_fields['id'];
		$id       = $element->$id_field;

		if ( ! empty( $children_elements[ $id ] ) && is_array( $children_elements[ $id ] ) ) {
			foreach ( (array) $children_elements[ $id ] as $child ) {
				$this->unset_children( $child, $children_elements );
			}
		}

		unset( $children_elements[ $id ] );
	}
}