Make wp_list_* functions all behave similarly...

[pishmishy]

The sidebar template typically uses lists of lists to prettily display lists of pages, categories and bookmarks. Lists of pages, categories and bookmarks are forced to be items of lists themselves as the functions wp_list_pages(),wp_list_categories() and wp_list_bookmarks() wrap the output of functions in <li>..</li> tags by default.

Lists are intended to indicate something about the structure of the document where as these forced <li> tags appear to be intended to provide pretty indentation. Nested-lists can also provide confusion for non-visual readers.

wp_list_bookmarks() provides the ability to override this with category_before and category_after options. wp_list_pages() and wp_list_categories() should offer similar options. Ideally the accessible approach would be the default for these options but I don't believe this is possible without breaking existing themes.

Added patch. I'm not sure why the options are called category_before, category_after. I suspect they need to be changed to something more descriptive but I've continued the pattern for now.

Replying to pishmishy:

The sidebar template typically uses lists of lists to prettily display lists of pages, categories and bookmarks. Lists of pages, categories and bookmarks are forced to be items of lists themselves as the functions wp_list_pages(),wp_list_categories() and wp_list_bookmarks() wrap the output of functions in <li>..</li> tags by default.

Lists are intended to indicate something about the structure of the document where as these forced <li> tags appear to be intended to provide pretty indentation. Nested-lists can also provide confusion for non-visual readers.

The purpose of these lists is not for indentation, it's for document structure.

Generally speaking, the entire sidebar can be considered one big list of items. Each "item" is a whole sidebar entry. This is a perfectly acceptable structure, you have a big list of entries. The fact that each entry is large vertically does not make the unordered list structure incorrect. And indentation is not a factor here either, generally speaking, as the entire sidebar is styled to a specific position.

Now, the individual elements of that sidebar might contain list information themselves, such as a list of pages or list of bookmarks or what have you. But the content of that sidebar list item is irrelevant, it can be anything desired.

wp_list_bookmarks() provides the ability to override this with category_before and category_after options.

wp_list_bookmarks is a special case, as it generates *multiple* list items intended for inclusion into a sidebar. By default, each category becomes a separate sidebar entry, instead of the entire unit being one sidebar entry with multiple subentries.

Because of this multiple nature, it needs these extra before and after options because not all themes use lists for the entire sidebar. I've seen sidebars that use nested divs, for example. These themes would have a div around each sidebar section, and so the wp_list_bookmarks would need to know those div elements in order to wrap each one in a div instead of a list.

wp_list_pages() and wp_list_categories() should offer similar options.

wp_list_pages and wp_list_categories do not actually generate multiple sidebar, and so they do not need these similar options.

Recommend closing this as wontfix.

Replying to pishmishy:

Added patch. I'm not sure why the options are called category_before, category_after. I suspect they need to be changed to something more descriptive but I've continued the pattern for now.

wp_list_bookmarks() uses category before and after because it's wrapping each category in a separate sidebar entry. Use of this pattern in these other functions is incorrect, even if it was necessary.

On the other hand, looking closer, I do see your point to some degree. As far as consistency goes, it would make a lot more sense if the pages and categories functions had title_before and after as well as a normal before and after wrapping the whole thing. The style == 'list' is being misused in the categories, for example.

Here's a patch for wp_list_categories that I think is more consistent overall.

Patch for wp_list_categories

Patch for wp_list_pages

wp_list_pages is trickier, it doesn't make much sense to not have it in an unordered list internal to the sidebar item, since it's hierarchical in nature. So it was strangely overriding the existence of a title_li to make it not display the UL even though it had no way to not display the LIs around each entry.

Patch attached to make it more consistent with the others.

Replying to Otto42:

The purpose of these lists is not for indentation, it's for document structure.

Generally speaking, the entire sidebar can be considered one big list of items.

That's fine if it's what you're after (and I admit for most people it is), but it'd be nice if a theme author could have option of not using a list of lists if they so desire. Allow consistant unwrapping of the <li> tags if desired doesn't come at any cost.

Many thanks for your work on further patches for this ticket.

Replying to pishmishy:

That's fine if it's what you're after (and I admit for most people it is), but it'd be nice if a theme author could have option of not using a list of lists if they so desire.

I don't understand your objection, theme authors do have that option. Many themes use divs instead, for example. All the bits in there where it generates lists for sidebar items can be overriden with arguments.

I haven't looked at this ticket in a while. I'm still convinced that we should be able to use _before and _after arguments with this function.

Bumping milestone for feature freeze.

Replying to Otto42:

Replying to pishmishy:

That's fine if it's what you're after (and I admit for most people it is), but it'd be nice if a theme author could have option of not using a list of lists if they so desire.

I don't understand your objection, theme authors do have that option. Many themes use divs instead, for example. All the bits in there where it generates lists for sidebar items can be overriden with arguments.

I believe the objection presented there is allowing theme authors to be able to retain categorization while broken out of list mode. While currently it's possible to replace the tags for list items, the unordered list element is still present when categorization is enabled. Meaning if you want to keep categories but drop lists, in it's current form it's a bit inflexible to do so.

A bug also worth mentioning, is while attempting to pass double quotes as part of your string in either the before or after portions for tags that write lists. Like wp_list_bookmarks and possibly other tags, the output is passed but the quotes become escaped instead of switched or stripped completely. I understand why this happens, I'm just not sure whether or not double quotes should actually be passed if user wishes to pass a class variable for their custom before or after arguments.

I've also noticed that wp_list_pages(),wp_list_bookmarks(), wp_list_categories() have a title_li argument, but wp_get_archives needs to be wrapped as:

<li><h2>Archives</h2>
    <ul>
        <?php wp_get_archives('type=monthly'); ?>
    </ul>
</li>

Can I also make an argument for the functions to be consistent in this fashion?

Revised patch

Fresh patch, fixing the issues mentioned above, with no impact forseen on existing themes. Allows before/after on wp_list_pages() and wp_list_categories().

there are several dups of this one

Apart from the after/before discussion, the archive title thing can be fixed.