Skip to content
Browse files

Revamp Html helper API docs

  • Loading branch information...
1 parent d0a11cb commit 5f16dca96344f818021be33584ff132bba955f26 @mehlah mehlah committed with mehlah May 28, 2012
Showing with 45 additions and 17 deletions.
  1. +45 −17 template/helper/Html.php
View
62 template/helper/Html.php
@@ -117,19 +117,26 @@ public function charset($encoding = null) {
/**
* Creates an HTML link (`<a />`) or a document meta-link (`<link />`).
*
- * If `$url` starts with `"http://"` or `"https://"`, this is treated as an external link.
+ * If `$url` starts with `'http://'` or `'https://'`, this is treated as an external link.
* Otherwise, it is treated as a path to controller/action and parsed using
* the `Router::match()` method (where `Router` is the routing class dependency specified by
* the rendering context, i.e. `lithium\template\view\Renderer::$_classes`).
*
* If `$url` is empty, `$title` is used in its place.
*
- * @param string $title The content to be wrapped by an `<a />` tag.
+ * @param string $title The content to be wrapped by an `<a />` tag,
+ * or the `title` attribute of a meta-link `<link />`.
* @param mixed $url Can be a string representing a URL relative to the base of your Lithium
* application, an external URL (starts with `'http://'` or `'https://'`), an
* anchor name starting with `'#'` (i.e. `'#top'`), or an array defining a set
* of request parameters that should be matched against a route in `Router`.
- * @param array $options Array of HTML s and other options.
+ * @param array $options The available options are:
+ * - `'escape'` _boolean_: Whether or not the title content should be escaped or not. Defaults to true.
+ * - `'type'` _string_: The meta-link type, which is looked up in `Html::$_metaLinks`.
+ * By default it accepts `atom`, `rss` and `icon`.
+ * If a `type` is specified, this method will render a document meta-link (`<link />`),
+ * instead of an HTML link (`<a />`).
+ * - any other options specified are rendered as HTML attributes of the element.
* @return string Returns an `<a />` or `<link />` element.
*/
public function link($title, $url = null, array $options = array()) {
@@ -147,11 +154,18 @@ public function link($title, $url = null, array $options = array()) {
/**
* Returns a JavaScript include tag (`<script />` element). If the filename is prefixed with
- * `"/"`, the path will be relative to the base path of your application. Otherwise, the path
+ * `'/'`, the path will be relative to the base path of your application. Otherwise, the path
* will be relative to your JavaScript path, usually `webroot/js`.
*
- * @param mixed $path String path to JavaScript file, or an array of paths.
- * @param array $options
+ * @link http://lithify.me/docs/manual/handling-http-requests/views.wiki
+ * @param mixed $path String The name of a JavaScript file, or an array of names.
+ * @param array $options Available options are:
+ * - `'inline'` _boolean_: Whether or not the `<script />` element should be output inline.
+ * When set to false, the `scripts()` handler prints out the script, and other specified scripts
+ * to be included in the layout. Defaults to true.
+ * This is useful when page-specific scripts are created inline in the page,
+ * and you'd like to place them in the <head /> along with your other scripts.
+ * - any other options specified are rendered as HTML attributes of the element.
* @return string
* @filter This method can be filtered.
*/
@@ -180,11 +194,22 @@ public function script($path, array $options = array()) {
}
/**
- * Creates a link element for CSS stylesheets.
+ * Creates a `<link />` element for CSS stylesheets or a `<style />` tag. If the filename is prefixed with
+ * `'/'`, the path will be relative to the base path of your application. Otherwise, the path
+ * will be relative to your Stylesheets path, usually `webroot/css`.
*
- * @param mixed $path The name of a CSS style sheet in `/app/webroot/css`, or an array
+ * @param mixed $path The name of a CSS stylesheet in `/app/webroot/css`, or an array
* containing names of CSS stylesheets in that directory.
- * @param array $options Array of HTML attributes.
+ * @param array $options Available options are:
+ * - `'inline'` _boolean_: Whether or not the `<style />` element should be output inline.
+ * When set to false, the `styles()` handler prints out the styles, and other specified styles
+ * to be included in the layout. Defaults to true.
+ * This is useful when page-specific styles are created inline in the page,
+ * and you'd like to place them in the <head /> along with your other styles.
+ * - `'type'` _string_: By default, accepts `stylesheet` or `import`,
+ * which respectively correspond to `style-link` and `style-import` strings templates
+ * defined in `Html::$_strings`.
+ * - any other options specified are rendered as HTML attributes of the element.
* @return string CSS <link /> or <style /> tag, depending on the type of link.
* @filter This method can be filtered.
*/
@@ -216,16 +241,16 @@ public function style($path, array $options = array()) {
}
/**
- * Creates a tag for the ```<head>``` section of your document.
+ * Creates a tag for the `<head>` section of your document.
*
* If there is a rendering context, then it also pushes the resulting tag to it.
*
- * The ```$options``` must match the named parameters from ```$_strings``` for the
- * given ```$tag```.
+ * The `$options` must match the named parameters from `$_strings` for the
+ * given `$tag`.
*
- * @param string $tag the name of a key in ```$_strings```
- * @param array $options the options required by ```$_strings[$tag]```
- * @return mixed a string if successful, otherwise NULL
+ * @param string $tag the name of a key in `$_strings`
+ * @param array $options the options required by `$_strings[$tag]`
+ * @return mixed a string if successful, otherwise `null`
* @filter This method can be filtered.
*/
public function head($tag, array $options) {
@@ -244,9 +269,12 @@ public function head($tag, array $options) {
}
/**
- * Creates a formatted <img /> element.
+ * Creates a formatted `<img />` element.
*
- * @param string $path Path to the image file, relative to the app/webroot/img/ directory.
+ * @param string $path Path to the image file. If the filename is prefixed with
+ * `'/'`, the path will be relative to the base path of your application.
+ * Otherwise the path will be relative to the images directory, usually `app/webroot/img/`.
+ * If the name starts with `'http://'`, this is treated as an external url used as the `src` attribute.
* @param array $options Array of HTML attributes.
* @return string
* @filter This method can be filtered.

0 comments on commit 5f16dca

Please sign in to comment.
Something went wrong with that request. Please try again.