[theme-reviewers] New Tags in 3.0: home_url(), site_url(), admin_url()

[Andrew Nacin]

On Fri, Aug 27, 2010 at 2:45 PM, Chip Bennett <chip at chipbennett.net> wrote:

> On Fri, Aug 27, 2010 at 1:41 PM, Edward Caissie <edward.caissie at gmail.com>wrote:
>
>> I'm not seeing a great deal of difference in their functionality from the
>> codex pages.
>>
>> The major differences I am seeing in core are:
>>
>>    - site_url() returns get_option ( 'siteurl' ) vs. home_url returns
>>    get_option( 'home' )
>>    - site_url() does additonal $scheme checks
>>
>> Allow me to summarize everything, as well as what was added in 3.0.

In a nutshell, home_url() is to get_bloginfo('url') or get_option('home'),
as site_url() is to get_option('site_url') or get_bloginfo('wpurl');

The difference between the _url() functions and get_option/get_bloginfo is
that the _url() functions handle schemes, specifically, HTTPS versus HTTP.
Thus these are extremely important for sites that want to force SSL on the
frontend, admin, or login.

The difference between site and home is the following. Otto is correct that
they have to do with the two address fields on the General Settings page.
Specifically, SITE is always where the WP files are actually located, and
HOME *may* be /blog. In 99% of cases, a theme will want to use home_url().

home_url() is new in 3.0, but site_url(), admin_url(), content_url(),
plugins_url(), and includes_url() were all added in 2.6. [1]

Additionally, we added 6 others that are for multisite installations. Three
are network_admin_url(), _site_, and _home_... These are for the root site's
admin, site, and home, respectively. And then get_admin_url(), _site_, and
_home_, which are designed to be able to fetch the admin, site, and home of
any site (it takes a blog_id parameter).

Thus it is important to know that get_site_url() and site_url() are *not*
complimentary the way most get_ and non-get_ functions are (return versus
echo).

[1] http://codex.wordpress.org/Determining_Plugin_and_Content_Directories

I would prefer to go with "Theme authors may also use home_url()" ... at
> least until we are given a clear direction from WPORG.


Suggested direction: I would use "recommended," primarily because they are
easier to use. Instead of doing `get_bloginfo() . '/blah/'`, you can do
home_url('/blah'). That said, there is *zero* functional difference between
the url and wpurl arguments for get_bloginfo() with their _url()
counterparts (home and site, respectively), as bloginfo() simply calls
home_url() or site_url(). Thus, the HTTPS scheme is covered.

However, get_option('home') or get_option('url') in a theme should throw a
flag. Likewise, chances are in a theme, site_url() should actually be
home_url() in most cases.

Questions welcome.

Nacin
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.wordpress.org/pipermail/theme-reviewers/attachments/20100828/74c3f7f1/attachment.htm>