Request Generator Methods
From LifeType Wiki
Contents |
[edit] Introduction
$url object helps to generate a request url and send to user's browser. Use $url object to avoid hardcoded URL in templates.
These methods are exported to template. When you use them in template, don't forget to enclose them with { and }. The following is an example from 'grey' template:
<link rel="stylesheet" title="Default" href="{$url->getTemplateFile("grey.css")}" type="text/css" />
[edit] General methods to get entry link
These methods are implemented in class/net/baserequestgenerator.class.php. For those methods which have a boolean parameter ($useSubdomains), when set true, it returns URL in subdomain scheme.
$url->getBaseUrl( $useSubdomains = true )
- returns base url. Usually, it is starting point of a blog.
$url->getIndexUrl( $useSubdomains = true )
- returns index page url, i.e. url to index.php.
$url->getAdminUrl( $useSubdomains = true )
- returns admin page url, i.e. url to admin.php.
$url->getRssUrl( $useSubdomains = false )
- returns RSS url.
$url->getTrackbackUrl( $useSubdomains = false )
- returns TrackBack url.
$url->getResourceServerUrl( $useSubdomains = false )
- returns resource server url.
$url->getUrl( $res, $useSubdomains = false )
- converts a relative resource name to url.
$url->getTemplateFile( $file )
- Returns the url for a file inside current template directory. It is used to locate the CSS or image file that template uses. Template designers are encouraged to use this method to locate file.
$url->getTemplateLocaledFile( $file )
- Returns the url for a file inside current template directory, a localized one if available. For example, if your blog use "zh_CN" as locale, and you getTemplateLocaledFile("grey.css"), this method will test if "grey.zh_CN.css" is available inside current template directory, and use it if it exists, otherwise, it behaves like getTemplateFile().
- Developers of plog are generally against the idea of localizing file by naming. This makes things complex. In the case of script, the script itself should and can support localization. However, CSS files and image files can't do that. Eventually this method is provided to overcome the problem, and we wish that it can improve out-of-box user experiences.
- A possible usage of getTemplateLocaledFile() is to locate CSS file. For eastern languages such as Chinese, Japanese and Korean, the character glyph is more complex and generally needs more space when being displayed. The smallest font size for CJK is generally larger than western languages. But enlarge font size is bad option for western language. So if you want your template to be used by CJK people without modification, you can provide localized CSS file with larger font. Even if you don't know what font size is suitable, you can still use this method, because it enables coexistence of localized CSS file, and maybe someone else can help you localize CSS file.
- However, it is discouraged to use this method for image files. Image file is hard to localize and image localization is a bad idea at all.
[edit] Url-scheme specific methods
Plog supports some kinds of url-scheme: normal, search engine friendly, mod_rewrite and custom. They provide different URL for an arbitary web object (image, script, etc.).
The following methods are provided, so template can avoid handling different url-scheme itself.
[edit] Post (article) related methods
These methods need a $post object as parameter, and should be used in a context that a $post object is provided.
$url->postPermalink( $post )
- Returns the permalink for a post.
$url->postCommentLink( $post )
- Returns the comment link for a post.
$url->postLink( $post )
- Returns the link for a post. In most cases, it is the same as $url->postPermalink().
$url->postRssLink( $post )
- Returns the rss link for a post. Not surprising, usually, it is the same as $url->postPermalink().
$url->replyCommentLink( $post, $comment )
- Returns the link to reply to a given comment. It should be used in a context that $comment object can be available. See postandcomments.template of grey template for reference.
$url->postTrackbackStatsLink( $post )
- Returns the link to the page showing the trackback statistics for a given post.
$url->postTrackbackLink( $post )
- Returns html block which contains trackback information. It doesn't return a link however. This is example from grey template:
<!-- {$url->postTrackbackLink($post)} -->
[edit] Album related methods
These methods deal with albums. NOTE: album methods must be used in a blog context.
$url->albumLink( $album = null )
- Returns the link to an album. Default is to get root album link.
$url->parentAlbumLink( $album )
- Returns the link to an album's parent album.
[edit] Resource related methods
These methods deal with resource.
$url->resourceLink( $resource )
- Returns the link to a resource.
$url->resourcePreviewLink( $resource )
- Returns the link to a resource preview.
$url->resourceMediumSizePreviewLink( $resource )
- Returns the link to a resource preview.
$url->resourceDownloadLink( $resource )
- Returns the link to a resource.
[edit] Other methods
$url->blogLink( $blogInfo = null )
- Returns the link to a blog. For normal template design, never use parameter.
$url->getArchiveLink( $date )
- Returns the link to an archive of a given date. The date is used to calculate year and month. Normally, you have little chance to use this method.
$url->categoryLink( $category )
- Returns the link for a given category. The parameter is a category object.
$url->linkTrackerLink()
- Returns the url that shows the results of the link tracker.
$url->rssLink( $profile = "", $blogInfo = null )
- Returns the url for the rss feed. For normal template design, never use $blogInfo parameter.
- $profile is a string of rss type name, one of "rss090", "rss10", "rss20" and "atom".
$url->categoryRssLink( $category, $profile = "", $blogInfo = null )
- Returns the url for the rss feed of a category. It is does the same as rssLink() but for the given category this time.
