WordPress.org

Make WordPress Core

Opened 9 years ago

Closed 9 years ago

Last modified 3 years ago

#14034 closed defect (bug) (fixed)

is_single() or its documentation needs update

Reported by: sirzooro Owned by: scribu
Milestone: 3.1 Priority: normal
Severity: normal Version: 3.0
Component: Inline Docs Keywords: needs-patch
Focuses: Cc:
PR Number:

Description

I have compared how is_single() works with its documentation, and I am a bit confused:

  • implementation: is_single() returns true for Posts, Attachments and Custom Post Types; for Pages it returns false;
  • documentation on codex: "When any single Post page is being displayed." (my understanding: it should return true for Posts only);
  • inline documentation in code: "Whether the current page query is single page. [...] This applies to other post types, attachments, pages, posts. Just means that the current query has only a single object.".

Need to determine how this function should really works, and update it, its inline doc and/or codex accordingly.

Change History (10)

#1 @nacin
9 years ago

The inline docs are wrong. is_single is not true for pages.

is_singular is true for posts, pages, custom post types, attachments.

#2 @mrmist
9 years ago

I've updated the referenced Codex doc to reflect that is_single returns true for attachement and custom types, but not for Pages.

#3 @sirzooro
9 years ago

  • Keywords dev-feedback 2nd-opinion added

OK, but current function behavior is correct or not? Codex doc for this function is in "A Single Post Page" section, so I would expect that this function should be used to detect if we are on Post page or not. I have searched Internet for it, and found that others write something similar about it.

What's more, in WP2.9 and earlier we need to use more complex condition to detect if current page is Post or not - something like this:
if ( is_single() && !is_attachment() )
In 3.0 we can use is_singular( 'page' ) to do this, but this is not backward-compatible.

Therefore I am not sure if this is correct. I would like to get extra feedback from other people about this.

#4 @nacin
9 years ago

  • Component changed from General to Inline Docs
  • Milestone changed from Awaiting Review to 3.1

IIRC: is_single() should return true for posts only. is_singular() returns true for pages, posts, and attachments.

Let's fix the docs.

#5 @PeteMall
9 years ago

is_single() currently returns true for custom post types which is a bug.

#6 @nacin
9 years ago

We might need to accept that as new functionality.

#7 @nacin
9 years ago

  • Keywords dev-feedback 2nd-opinion removed

Technically, is_singular = is_single || is_page || is_attachment, but when is_attachment is true, is_single xor is_page is also true.

is_single() cannot be counted on for attachments due to a specific case where is_attachment = is_page = true, but for the most part, is_single() checks any post type other than pages.

Let's have the docs reflect this. is_singular() checks any post type. is_page() checks pages. is_attachment() checks attachments. is_single() checks posts, any other post type, and usually returns true for attachments.

#8 @scribu
9 years ago

  • Owner set to scribu
  • Status changed from new to accepted

#9 @scribu
9 years ago

  • Resolution set to fixed
  • Status changed from accepted to closed

(In [16830]) Clarify is_single() inline doc. Fixes #14034

This ticket was mentioned in Slack in #docs by johnbillion. View the logs.


3 years ago

Note: See TracTickets for help on using tickets.