WordPress.org

Make WordPress Core

Opened 6 years ago

Closed 6 years ago

Last modified 6 years ago

#8799 closed enhancement (wontfix)

get_search_form() is inadequately documented

Reported by: sampablokuper Owned by:
Milestone: Priority: normal
Severity: normal Version: 2.7
Component: WordPress.org site Keywords: search theme documentation codex
Focuses: Cc:

Description

According to the Codex page, "Migrating Plugins and Themes to 2.7", the new template tag get_search_form() is designed to be used in place of the old searchform.php system. That Codex page mentions that this tag can be filtered to allow "plugin authors or theme designers to alter the structure of the search form entirely", yet the Codex does not state how this filtering can be done.

This is obviously puzzing users who, like me, want to alter the structure of the search form.http://wordpress.org/support/topic/225241 1http://wordpress.org/support/topic/227030 2http://wordpress.org/support/topic/225114 3

The get_search_form() template tag clearly needs to be documented better.

Change History (13)

comment:1 @jacobsantos6 years ago

  • Resolution set to worksforme
  • Status changed from new to closed

From inline documentation of get_search_form():

"Will first attempt to locate the searchform.php file in either the child or the parent, then load it. If it doesn't exist, then the default search form will be displayed."

comment:2 @jacobsantos6 years ago

  • Milestone 2.7.1 deleted

comment:3 @sampablokuper6 years ago

  • Milestone set to 2.7.1
  • Resolution worksforme deleted
  • Status changed from closed to reopened

jacobsantos wrote:

From inline documentation of get_search_form():

"Will first attempt to locate the searchform.php file in either the child or the parent, then load it. If it doesn't exist, then the default search form will be displayed."

Yes, I read that part before I opened this ticket. It's the "default search form" that I want to modify (and which other users also clearly want to be able to modify. None of the Codex documentation explains how to do that. All it says (beyond what you've quoted above) is:

"The tag can also be filtered with the get_search_form filter, allowing plugin authors or theme designers to alter the structure of the search form entirely."

Telling users/developers that something can be done without telling them how to do it is not very helpful. The docs need to be improved to explain how to do it.

Also, presumably get_search_form ought to be documented at http://codex.wordpress.org/Plugin_API/Filter_Reference.

comment:4 @technosailor6 years ago

As a developer, you should be able to look at source code. As a WordPress developer, you should understand the principles behind filters and actions. So use the get_search_form filter and replace the form.

comment:5 @sampablokuper6 years ago

technosailor wrote:

As a developer, you should be able to look at source code. As a WordPress developer, you should understand the principles behind filters and actions.

Perhaps, but as a new Wordpress developer, I rely on the Codex to get me up to speed. Furthermore, I'm clearly not the only person who's had trouble understanding how to use get_search_form() to create a custom form. See the references I provided when I opened this ticket.

So use the get_search_form filter and replace the form.

I still feel this filter ought to at least be documented in http://codex.wordpress.org/Plugin_API/Filter_Reference, which describes itself as, "a (hopefully complete) list of the filter hooks available for use in plugin development in Version 2.1 and above of WordPress."

But I've read the Codex page on filtering, and the email you sent me (for which, thank you), which says much the same thing as that Codex page, and it's still not clear to me how to modify the search form without either using a searchform.php (which, as far as I can tell is deprecated, since it's described as being an option only "in order to preserve compatibility with older themes") or creating a plugin.

I don't want to have to create a plugin to modify the search form, because I want to customise the search form with a theme. But I don't want to use a searchform.php file either, because (IIUC, see above) this is deprecated.

Is there no other way to achieve a custom search form using get_search_form()?

  • If there is, then it should be documented.
  • If not, then the docs should make clear whether or not developers should feel free to use searchform.php files in WP 2.7 templates, because:
    • if they are not free to do so (i.e. if this really is deprecated practice), then if they want a custom search form, they must either avoid get_search_form() or else write a plugin.
    • if they are free to do so, what's the point of get_search_form()? Is its sole raison d'etre to create a hook? If so, please say so explicitly (in the Codex), because it's unclear to me.

Many thanks,

Sam

comment:6 follow-up: @jacobsantos6 years ago

  • Milestone 2.7.1 deleted
  • Owner changed from matt to jacobsantos
  • Status changed from reopened to new

Whoever said searchform.php was deprecated was wrong. It is not deprecated in 2.7. There was some complaint about deprecating searchform.php, so even if the word on the street was that it was being deprecated, it ended up not being deprecated. The Trac people and the Codex people do not often talk to each other.

Also, if you are using the search widget, then it will use the searchform.php template file as well, so to say that something that is used in both places is deprecated, well that is either misinformation or wrong information.

As for examples, I would have to give an sarcastic reply, "Do you want us to wipe your ass as well?" Yes, examples would be an nice addition. Luckily, there is a group of people that might make your wishes come true on the Codex.

As well, the hook will only be used if and only if the searchform.php file is not found. Therefore, if you rely on the hook, then you'll be SOL when the theme includes the searchform.php file.

The whole issue is that, there are two ways for a theme to change the search form on the widget and if the user hard codes it. You don't need to create a plugin and in this case, it is better if you don't.

I think the wording is arbitrarily, in that it doesn't mean the searchform.php is deprecated, it is just clarifying why there are two ways to skin the cat (so to speak, although I have no idea why you would skin a cat).

So in summary:

Examples: In progress, look for it in about one to three months at the least.
Wording: A little vague, but the summary works. The Inline documentation can also be updated to clarify the situation.

comment:7 @jacobsantos6 years ago

  • Owner jacobsantos deleted

comment:8 @jacobsantos6 years ago

  • Resolution set to wontfix
  • Status changed from new to closed

comment:9 in reply to: ↑ 6 @sampablokuper6 years ago

  • Milestone set to 2.8
  • Resolution wontfix deleted
  • Status changed from closed to reopened

Replying to jacobsantos:

Whoever said searchform.php was deprecated was wrong. It is not deprecated in 2.7. There was some complaint about deprecating searchform.php, so even if the word on the street was that it was being deprecated, it ended up not being deprecated.

I guessed as much in the end, but it's good to have it clarified by someone who knows the background. This removes the uncertainty that inevitably surrounds a guess.

The Trac people and the Codex people do not often talk to each other.

Now THAT is an A1 bug!

As for examples, I would have to give an sarcastic reply, "Do you want us to wipe your ass as well?" Yes, examples would be an nice addition.

No need to be so rude, especially as I didn't ask for examples.

The whole issue is that, there are two ways for a theme to change the search form on the widget

Those two ways being:

  1. Create a searchform.php file if one doesn't already exist.
  2. Use a filter in functions.php.

OK, I get the drill now.

This stuff needs to be made clearer in the Codex. The assertion I made in the title of this ticket remains true.

and if the user hard codes it. You don't need to create a plugin and in this case, it is better if you don't.

Agreed.

I think the wording is arbitrarily,

If you mean "ambiguous", I agree with you. It is ambiguous.

I don't think ambiguous documentation is a good thing, and I think most users and developers would agree with me.

Wording: A little vague, but the summary works.

If it worked reliably, I wouldn't have had to open this ticket.

I get the impression that what you've said about Trac people and Codex people not talking to each other (I'd put characterise it as, "not getting involved in each others' work") is holding true in this case. Yet at least since "Zen and the art of motorcycle maintenance" was published (1974), it's been clear that developers and documentors need to work closely in order to be effective together. It's also clear that they are rarely terribly effective separately.

Anyway, even though the thread above should provide sufficient help for someone searching on this problem to be able to solve it, Trac isn't the first place they should be finding this help: the Codex is. So until all the knowledge that's been laid out in the posts above makes it into the Codex, surely this ticket should stay open. I'm not being ornery. If I find time, I'll update the relevant parts of the Codex myself. But until it has been updated, I believe this is a valid ticket.

comment:10 @technosailor6 years ago

  • Resolution set to wontfix
  • Status changed from reopened to closed

I responded on Trac and wrote that part of the Codex docs. I also wrote the template tag. While there is sometimes disconnect, there is none now.

And the search widget uses get_search_form(), Jacob (just saying! You documented it inline! :))

Bottom line, if the Codex documentation is ambiguous, change it! It's a wiki! And now you know and understand how it works so go fix problems I created! :)

And why did we reopen this ticket? Trac is not a support system, it's a bug reporting tool. And since there isn't a bug here, the ticket does need to be closed. Go forth and fix docs!

comment:11 follow-up: @DD326 years ago

sampablokuper: Is it a Documentation error on the Codex, Or a bug within the Core WordPress Code?

Bugs in the core code belong on Trac (Or Documentation errors in the actual Inline documentation in the PHP), Codex documentation issues do not, Change it yourself, Go to the support forums or post on the documentation mailing list

If you do not understand the API, Post in the support forums and ask for help, Do not assume just because the codex doesnt say it, that its a bug, You not understanding how the API works is not a bug, It simply means you need to learn a bit more, You cannot expect every page to spell it out in baby steps, Theres a higher-level overview of actions and filters, Anyone who has some PHP knowledge *should* be able to pick it up by following the examples. There is no reason why the codex should hold peoples hands through -every- little detail

The groups of people who work on the Code, and those who work on the Codex are 2 completely separate groups of people, Very few of either are payed to do that, and as such, Most people will not communicate between each other, Those doing Documentation work follow the WordPress development, and update the codex if need be, If a Developer comes across a Codex page thats severely out of date, they may fix it themselves, or post a message to someone else on the before mentioned locations to get it fixed up.
(This is not to say that there are not developers who do both developing and documentation, Nor that there is -no- communication, I've had people who write documentation contact me numerous times asking for some info on a item so they could document it well on the codex)

Also, Please don't get into re-open wars, If its closed, Someone has closed it for a reason, Core developers follow the trac mailing list, If they see something thats been closed incorrectly, they will re-open and address the issue, As it is, this is NOT a Trac issue.

comment:12 in reply to: ↑ 11 ; follow-up: @sampablokuper6 years ago

Replying to DD32:

sampablokuper: Is it a Documentation error on the Codex, Or a bug within the Core WordPress Code?

The former.

Bugs in the core code belong on Trac (Or Documentation errors in the actual Inline documentation in the PHP), Codex documentation issues do not

That's a pretty unenlightened view, IMO. Ubuntu has shown that "bugs" aren't just about the code.

Furthermore, I reported this as an enhancement to wordpress.org (which contains the Codex in one of its subdomains), not as bug in the core code.

Change it yourself

If I can spare the time, I may yet do this. But without raising the issue with others, I wasn't able to find out what to change it to.

Go to the support forums or post on the documentation mailing list

I did go to the forums, as you will see if you follow the references in the ticket. It's true that I could have posted to the mailing list, and maybe that would have been the least controversial course of action, but I still don't think the ticket was wholly inappropriate, for the reasons I've given above.

Do not assume just because the codex doesnt say it, that its a bug,

I don't. But if the Codex should say something, and it doesn't, then that is a problem. That's what I reported.

You not understanding how the API works is not a bug,

I agree, but this wasn't just about my understanding of the API. It was about a new feature in 2.7 whose intended purpose was at least partly unclear, and which was documented in a manner that made the status of searchform.php (i.e. whether it was deprecated or not) confusing.

The groups of people who work on the Code, and those who work on the Codex are 2 completely separate groups of people,

That's a great pity. I'm genuinely very sorry to hear it.

Very few of either are payed to do that, and as such, Most people will not communicate between each other,

I don't understand this point at all. Surely a volunteer coder who learns to document her code in the Codex is a greater asset than one who doesn't learn to do this. So I don't see why volunteers who care about WP wouldn't want to learn to do this.

Those doing Documentation work follow the WordPress development, and update the codex if need be, If a Developer comes across a Codex page thats severely out of date, they may fix it themselves, or post a message to someone else on the before mentioned locations to get it fixed up.

That's better than nothing, but there's evidently still quite a lot that's out of date.

(This is not to say that there are not developers who do both developing and documentation, Nor that there is -no- communication, I've had people who write documentation contact me numerous times asking for some info on a item so they could document it well on the codex)

Good to hear!

Also, Please don't get into re-open wars, If its closed, Someone has closed it for a reason,

But not always a good reason...

Don't worry, I'm not trying to start a war here. I just don't think my ticket was inappropriate. Nor do I think the problem I reported has been fixed. Nor do I think the problem should be ignored.

But you've made it clear that, for the time being, the people who follow the Trac mailing list aren't interested in documentation problems. And while I think that's a missed opportunity for the wordpress.org community (cf. the Ubuntu example above), I'm not going to be able to change everyone's minds overnight.

comment:13 in reply to: ↑ 12 @jacobsantos6 years ago

  • Milestone 2.8 deleted

Replying to sampablokuper:

That's a pretty unenlightened view, IMO. Ubuntu has shown that "bugs" aren't just about the code.

Yes, if the inline documentation is incorrect, then it is a bug worth posting to Trac. Since the very nature of the Codex as a Wiki, which allows anyone to sign up and edit it. There is really no point to say, "Hey fix this," when the person saying that can fix it themselves.

Really, the only page that it should be corrected on is the function reference or template tag, depending on which it falls under. Summaries like the page you referenced, should not go into a lot of detail, so an example on that page would not be advisable.

I don't. But if the Codex should say something, and it doesn't, then that is a problem. That's what I reported.

The Codex doesn't say a lot of things that it should. It is like DD32 said, a completely volunteer effort, and it is a lot of effort. So basically, you have a group of awesome people working as hard as possible to document what they feel like.

So I mean, take you for example. You care about the get_search_form() function issue, so someone like you would create the template tag page, add the details, and then leave it as a stub for others to finish later. Or you could finish it.

Part of the reason for the inline documentation effort was that the Codex doesn't have everything and is often inaccurate about functions you are describing. Also, phpdoc.wordpress.org exists, and that is also a wordpress.org site, which has correct information. You can not however, easily edit it. Well, you can't edit it, unless you create a patch for the inline documentation in the source.

That does remind me to document the HTTP API. Just so boring, I'm sure people will figure it out, eventually. Maybe. Yeah, I should probably write it.

The groups of people who work on the Code, and those who work on the Codex are 2 completely separate groups of people,

That's a great pity. I'm genuinely very sorry to hear it.

Why? I can spend close to about 10 to 30 minutes creating patches for simple tickets and spend up to 3 hours on more difficult ones. What makes you think I have time to search the codex to fix the various locations or document what I've done? To me adding inline documentation is as far as I need to go.

Likewise, a Codex page can also take up to three hours, so it evens out. If I was being paid, then yeah, I would probably spend the time to document what I was doing.

I don't understand this point at all. Surely a volunteer coder who learns to document her code in the Codex is a greater asset than one who doesn't learn to do this. So I don't see why volunteers who care about WP wouldn't want to learn to do this.

It is also part of the reasons for adding inline documentation to the source code of WordPress. A novice may not understand the importance of documentation, until they see if first hand. DocBook and PHP.net style documentation like the Codex is somewhat out there until you reach a higher level. I will say that inline documentation is good enough in most cases.

That said, I do care about WordPress. I care about WordPress being stable and having the features I care about. I do also care about being able to build plugins and having documentation in place, which is why I started documenting more on the Codex. However, I find it difficult to justify spending an hour to 3 hours writing about something on the Codex.

But you've made it clear that, for the time being, the people who follow the Trac mailing list aren't interested in documentation problems. And while I think that's a missed opportunity for the wordpress.org community (cf. the Ubuntu example above), I'm not going to be able to change everyone's minds overnight.

You're not going to change anyone's mind. Go to wp-docs mailing list instead.

Note: See TracTickets for help on using tickets.