Development

/branches/1.1/lib/helper/AssetHelper.php

You must first sign up to be able to contribute.

root/branches/1.1/lib/helper/AssetHelper.php

Revision 17078, 16.9 kB (checked in by FabianLange, 6 years ago)

[doc] fixed api description of include_http_metas()

  • Property svn:mime-type set to text/x-php
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Rev Date
Line 
1 <?php
2
3 /*
4  * This file is part of the symfony package.
5  * (c) 2004-2006 Fabien Potencier <fabien.potencier@symfony-project.com>
6  * (c) 2004 David Heinemeier Hansson
7  *
8  * For the full copyright and license information, please view the LICENSE
9  * file that was distributed with this source code.
10  */
11
12 /**
13  * AssetHelper.
14  *
15  * @package    symfony
16  * @subpackage helper
17  * @author     Fabien Potencier <fabien.potencier@symfony-project.com>
18  * @author     David Heinemeier Hansson
19  * @version    SVN: $Id$
20  */
21
22 /**
23  * Returns a <link> tag that browsers and news readers
24  * can use to auto-detect a RSS or ATOM feed for the current page,
25  * to be included in the <head> section of a HTML document.
26  *
27  * <b>Options:</b>
28  * - rel - defaults to 'alternate'
29  * - type - defaults to 'application/rss+xml'
30  * - title - defaults to the feed type in upper case
31  *
32  * <b>Examples:</b>
33  * <code>
34  *  echo auto_discovery_link_tag('rss', 'module/feed');
35  *    => <link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.curenthost.com/module/feed" />
36  *  echo auto_discovery_link_tag('rss', 'module/feed', array('title' => 'My RSS'));
37  *    => <link rel="alternate" type="application/rss+xml" title="My RSS" href="http://www.curenthost.com/module/feed" />
38  * </code>
39  *
40  * @param  string $type         feed type ('rss', 'atom')
41  * @param  string $url          'module/action' or '@rule' of the feed
42  * @param  array  $tag_options  additional HTML compliant <link> tag parameters
43  *
44  * @return string XHTML compliant <link> tag
45  */
46 function auto_discovery_link_tag($type = 'rss', $url = '', $tag_options = array())
47 {
48   return tag('link', array(
49     'rel'   => isset($tag_options['rel']) ? $tag_options['rel'] : 'alternate',
50     'type'  => isset($tag_options['type']) ? $tag_options['type'] : 'application/'.$type.'+xml',
51     'title' => isset($tag_options['title']) ? $tag_options['title'] : ucfirst($type),
52     'href'  => url_for($url, true)
53   ));
54 }
55
56 /**
57  * Returns the path to a JavaScript asset.
58  *
59  * <b>Example:</b>
60  * <code>
61  *  echo javascript_path('myscript');
62  *    => /js/myscript.js
63  * </code>
64  *
65  * <b>Note:</b> The asset name can be supplied as a...
66  * - full path, like "/my_js/myscript.css"
67  * - file name, like "myscript.js", that gets expanded to "/js/myscript.js"
68  * - file name without extension, like "myscript", that gets expanded to "/js/myscript.js"
69  *
70  * @param  string $source    asset name
71  * @param  bool   $absolute  return absolute path ?
72  *
73  * @return string file path to the JavaScript file
74  * @see    javascript_include_tag
75  */
76 function javascript_path($source, $absolute = false)
77 {
78   return _compute_public_path($source, 'js', 'js', $absolute);
79 }
80
81 /**
82  * Returns a <script> include tag per source given as argument.
83  *
84  * <b>Examples:</b>
85  * <code>
86  *  echo javascript_include_tag('xmlhr');
87  *    => <script language="JavaScript" type="text/javascript" src="/js/xmlhr.js"></script>
88  *  echo javascript_include_tag('common.javascript', '/elsewhere/cools');
89  *    => <script language="JavaScript" type="text/javascript" src="/js/common.javascript"></script>
90  *       <script language="JavaScript" type="text/javascript" src="/elsewhere/cools.js"></script>
91  * </code>
92  *
93  * @param  string asset names
94  * @param  array additional HTML compliant <link> tag parameters
95  *
96  * @return string XHTML compliant <script> tag(s)
97  * @see    javascript_path
98  */
99 function javascript_include_tag()
100 {
101   $sources = func_get_args();
102   $sourceOptions = (func_num_args() > 1 && is_array($sources[func_num_args() - 1])) ? array_pop($sources) : array();
103
104   $html = '';
105   foreach ($sources as $source)
106   {
107     
108     $absolute = false;
109     if (isset($sourceOptions['absolute']))
110     {
111       unset($sourceOptions['absolute']);
112       $absolute = true;
113     }
114  
115     if(!isset($sourceOptions['raw_name']))
116     {
117       $source = javascript_path($source, $absolute);
118     }
119     else
120     {
121       unset($sourceOptions['raw_name']);
122     }
123     $options = array_merge(array('type' => 'text/javascript', 'src' => $source), $sourceOptions);
124     $html   .= content_tag('script', '', $options)."\n";
125   }
126
127   return $html
128 }
129
130 /**
131  * Returns the path to a stylesheet asset.
132  *
133  * <b>Example:</b>
134  * <code>
135  *  echo stylesheet_path('style');
136  *    => /css/style.css
137  * </code>
138  *
139  * <b>Note:</b> The asset name can be supplied as a...
140  * - full path, like "/my_css/style.css"
141  * - file name, like "style.css", that gets expanded to "/css/style.css"
142  * - file name without extension, like "style", that gets expanded to "/css/style.css"
143  *
144  * @param  string $source    asset name
145  * @param  bool   $absolute  return absolute path ?
146  *
147  * @return string file path to the stylesheet file
148  * @see    stylesheet_tag 
149  */
150 function stylesheet_path($source, $absolute = false)
151 {
152   return _compute_public_path($source, 'css', 'css', $absolute);
153 }
154
155 /**
156  * Returns a css <link> tag per source given as argument,
157  * to be included in the <head> section of a HTML document.
158  *
159  * <b>Options:</b>
160  * - rel - defaults to 'stylesheet'
161  * - type - defaults to 'text/css'
162  * - media - defaults to 'screen'
163  *
164  * <b>Examples:</b>
165  * <code>
166  *  echo stylesheet_tag('style');
167  *    => <link href="/stylesheets/style.css" media="screen" rel="stylesheet" type="text/css" />
168  *  echo stylesheet_tag('style', array('media' => 'all'));
169  *    => <link href="/stylesheets/style.css" media="all" rel="stylesheet" type="text/css" />
170  *  echo stylesheet_tag('style', array('raw_name' => true));
171  *    => <link href="style" media="all" rel="stylesheet" type="text/css" />
172  *  echo stylesheet_tag('random.styles', '/css/stylish');
173  *    => <link href="/stylesheets/random.styles" media="screen" rel="stylesheet" type="text/css" />
174  *       <link href="/css/stylish.css" media="screen" rel="stylesheet" type="text/css" />
175  * </code>
176  *
177  * @param  string asset names
178  * @param  array additional HTML compliant <link> tag parameters
179  *
180  * @return string XHTML compliant <link> tag(s)
181  * @see    stylesheet_path
182  */
183 function stylesheet_tag()
184 {
185   $sources = func_get_args();
186   $sourceOptions = (func_num_args() > 1 && is_array($sources[func_num_args() - 1])) ? array_pop($sources) : array();
187
188   $html = '';
189   foreach ($sources as $source)
190   {
191     $absolute = false;
192     if (isset($sourceOptions['absolute']))
193     {
194       unset($sourceOptions['absolute']);
195       $absolute = true;
196     }
197         
198     if(!isset($sourceOptions['raw_name']))
199     {
200       $source = stylesheet_path($source, $absolute);
201     }
202     else
203     {
204       unset($sourceOptions['raw_name']);
205     }
206     $options = array_merge(array('rel' => 'stylesheet', 'type' => 'text/css', 'media' => 'screen', 'href' => $source), $sourceOptions);
207     $html   .= tag('link', $options)."\n";
208   }
209
210   return $html;
211 }
212
213 /**
214  * Adds a stylesheet to the response object.
215  *
216  * @see sfResponse->addStylesheet()
217  */
218 function use_stylesheet($css, $position = '', $options = array())
219 {
220   sfContext::getInstance()->getResponse()->addStylesheet($css, $position, $options);
221 }
222
223 /**
224  * Adds a javascript to the response object.
225  *
226  * @see sfResponse->addJavascript()
227  */
228 function use_javascript($js, $position = '', $options = array())
229 {
230   sfContext::getInstance()->getResponse()->addJavascript($js, $position, $options);
231 }
232
233 /**
234  * Decorates the current template with a given layout.
235  *
236  * @param mixed $layout  The layout name or path or false to disable the layout
237  */
238 function decorate_with($layout)
239 {
240   if (false === $layout)
241   {
242     sfContext::getInstance()->get('view_instance')->setDecorator(false);
243   }
244   else
245   {
246     sfContext::getInstance()->get('view_instance')->setDecoratorTemplate($layout);
247   }
248 }
249
250 /**
251  * Returns the path to an image asset.
252  *
253  * <b>Example:</b>
254  * <code>
255  *  echo image_path('foobar');
256  *    => /images/foobar.png
257  * </code>
258  *
259  * <b>Note:</b> The asset name can be supplied as a...
260  * - full path, like "/my_images/image.gif"
261  * - file name, like "rss.gif", that gets expanded to "/images/rss.gif"
262  * - file name without extension, like "logo", that gets expanded to "/images/logo.png"
263  *
264  * @param  string $source    asset name
265  * @param  bool   $absolute  return absolute path ?
266  *
267  * @return string file path to the image file
268  * @see    image_tag 
269  */
270 function image_path($source, $absolute = false)
271 {
272   return _compute_public_path($source, 'images', 'png', $absolute);
273 }
274
275 /**
276  * Returns an <img> image tag for the asset given as argument.
277  *
278  * <b>Options:</b>
279  * - 'absolute' - to output absolute file paths, useful for embedded images in emails
280  * - 'alt'  - defaults to the file name part of the asset (capitalized and without the extension)
281  * - 'size' - Supplied as "XxY", so "30x45" becomes width="30" and height="45"
282  *
283  * <b>Examples:</b>
284  * <code>
285  *  echo image_tag('foobar');
286  *    => <img src="images/foobar.png" alt="Foobar" />
287  *  echo image_tag('/my_images/image.gif', array('alt' => 'Alternative text', 'size' => '100x200'));
288  *    => <img src="/my_images/image.gif" alt="Alternative text" width="100" height="200" />
289  * </code>
290  *
291  * @param  string $source   image asset name
292  * @param  array  $options  additional HTML compliant <img> tag parameters
293  *
294  * @return string XHTML compliant <img> tag
295  * @see    image_path
296  */
297 function image_tag($source, $options = array())
298 {
299   if (!$source)
300   {
301     return '';
302   }
303
304   $options = _parse_attributes($options);
305
306   $absolute = false;
307   if (isset($options['absolute']))
308   {
309     unset($options['absolute']);
310     $absolute = true;
311   }
312
313   if(!isset($options['raw_name']))
314   {
315     $options['src'] = image_path($source, $absolute);
316   }
317   else
318   {
319     $options['src'] = $source;
320     unset($options['raw_name']);
321   }
322
323   if (!isset($options['alt']))
324   {
325     $path_pos = strrpos($source, '/');
326     $dot_pos = strrpos($source, '.');
327     $begin = $path_pos ? $path_pos + 1 : 0;
328     $nb_str = ($dot_pos ? $dot_pos : strlen($source)) - $begin;
329     $options['alt'] = ucfirst(substr($source, $begin, $nb_str));
330   }
331
332   if (isset($options['size']))
333   {
334     list($options['width'], $options['height']) = split('x', $options['size'], 2);
335     unset($options['size']);
336   }
337
338   return tag('img', $options);
339 }
340
341 function _compute_public_path($source, $dir, $ext, $absolute = false)
342 {
343   if (strpos($source, '://'))
344   {
345     return $source;
346   }
347
348   $request = sfContext::getInstance()->getRequest();
349   $sf_relative_url_root = $request->getRelativeUrlRoot();
350   if (0 !== strpos($source, '/'))
351   {
352     $source = $sf_relative_url_root.'/'.$dir.'/'.$source;
353   }
354
355   $query_string = '';
356   if (false !== $pos = strpos($source, '?'))
357   {
358     $query_string = substr($source, $pos);
359     $source = substr($source, 0, $pos);
360   }
361
362   if (false === strpos(basename($source), '.'))
363   {
364     $source .= '.'.$ext;
365   }
366
367   if ($sf_relative_url_root && 0 !== strpos($source, $sf_relative_url_root))
368   {
369     $source = $sf_relative_url_root.$source;
370   }
371
372   if ($absolute)
373   {
374     $source = 'http'.($request->isSecure() ? 's' : '').'://'.$request->getHost().$source;
375   }
376
377   return $source.$query_string;
378 }
379
380 /**
381  * Prints a set of <meta> tags according to the response attributes,
382  * to be included in the <head> section of a HTML document.
383  *
384  * <b>Examples:</b>
385  * <code>
386  *  include_metas();
387  *    => <meta name="title" content="symfony - open-source PHP5 web framework" />
388  *       <meta name="robots" content="index, follow" />
389  *       <meta name="description" content="symfony - open-source PHP5 web framework" />
390  *       <meta name="keywords" content="symfony, project, framework, php, php5, open-source, mit, symphony" />
391  *       <meta name="language" content="en" /><link href="/stylesheets/style.css" media="screen" rel="stylesheet" type="text/css" />
392  * </code>
393  *
394  * <b>Note:</b> Modify the view.yml or use sfWebResponse::addMeta() to change, add or remove metas.
395  *
396  * @return string XHTML compliant <meta> tag(s)
397  * @see    include_http_metas
398  * @see    sfWebResponse::addMeta()
399  */
400 function include_metas()
401 {
402   $context = sfContext::getInstance();
403   $i18n = sfConfig::get('sf_i18n') ? $context->getI18N() : null;
404   foreach ($context->getResponse()->getMetas() as $name => $content)
405   {
406     echo tag('meta', array('name' => $name, 'content' => is_null($i18n) ? $content : $i18n->__($content)))."\n";
407   }
408 }
409
410 /**
411  * Returns a set of <meta http-equiv> tags according to the response attributes,
412  * to be included in the <head> section of a HTML document.
413  *
414  * <b>Examples:</b>
415  * <code>
416  *  include_http_metas();
417  *    => <meta http-equiv="content-type" content="text/html; charset=utf-8" />
418  * </code>
419  *
420  * <b>Note:</b> Modify the view.yml or use sfWebResponse::addHttpMeta() to change, add or remove HTTP metas.
421  *
422  * @return string XHTML compliant <meta> tag(s)
423  * @see    include_metas
424  * @see    sfWebResponse::addHttpMeta()
425  */
426 function include_http_metas()
427 {
428   foreach (sfContext::getInstance()->getResponse()->getHttpMetas() as $httpequiv => $value)
429   {
430     echo tag('meta', array('http-equiv' => $httpequiv, 'content' => $value))."\n";
431   }
432 }
433
434 /**
435  * Returns the title of the current page according to the response attributes,
436  * to be included in the <title> section of a HTML document.
437  *
438  * <b>Note:</b> Modify the sfResponse object or the view.yml to modify the title of a page.
439  *
440  * @return string page title
441  */
442 function include_title()
443 {
444   $title = sfContext::getInstance()->getResponse()->getTitle();
445
446   echo content_tag('title', $title)."\n";
447 }
448
449 /**
450  * Returns <script> tags for all javascripts configured in view.yml or added to the response object.
451  *
452  * You can use this helper to decide the location of javascripts in pages.
453  * By default, if you don't call this helper, symfony will automatically include javascripts before </head>.
454  * Calling this helper disables this behavior.
455  *
456  * @return string <script> tags
457  */
458 function get_javascripts()
459 {
460   $response = sfContext::getInstance()->getResponse();
461   sfConfig::set('symfony.asset.javascripts_included', true);
462
463   $already_seen = array();
464   $html = '';
465
466   foreach ($response->getPositions() as $position)
467   {
468     foreach ($response->getJavascripts($position) as $files => $options)
469     {
470       if (!is_array($files))
471       {
472         $files = array($files);
473       }
474
475       foreach ($files as $file)
476       {
477         if (isset($already_seen[$file])) continue;
478
479         $already_seen[$file] = 1;
480         $html .= javascript_include_tag($file, $options);
481       }
482     }
483   }
484
485   return $html;
486 }
487
488 /**
489  * Prints <script> tags for all javascripts configured in view.yml or added to the response object.
490  *
491  * @see get_javascripts()
492  */
493 function include_javascripts()
494 {
495   echo get_javascripts();
496 }
497
498 /**
499  * Returns <link> tags for all stylesheets configured in view.yml or added to the response object.
500  *
501  * You can use this helper to decide the location of stylesheets in pages.
502  * By default, if you don't call this helper, symfony will automatically include stylesheets before </head>.
503  * Calling this helper disables this behavior.
504  *
505  * @return string <link> tags
506  */
507 function get_stylesheets()
508 {
509   $response = sfContext::getInstance()->getResponse();
510   sfConfig::set('symfony.asset.stylesheets_included', true);
511
512   $already_seen = array();
513   $html = '';
514
515   foreach ($response->getPositions() as $position)
516   {
517     foreach ($response->getStylesheets($position) as $files => $options)
518     {
519       if (!is_array($files))
520       {
521         $files = array($files);
522       }
523
524       foreach ($files as $file)
525       {
526         if (isset($already_seen[$file])) continue;
527
528         $already_seen[$file] = 1;
529         $html .= stylesheet_tag($file, $options);
530       }
531     }
532   }
533
534   return $html;
535 }
536
537 /**
538  * Prints <link> tags for all stylesheets configured in view.yml or added to the response object.
539  *
540  * @see get_stylesheets()
541  */
542 function include_stylesheets()
543 {
544   echo get_stylesheets();
545 }
546
547 /**
548  * Returns a <script> include tag for the given internal URI.
549  *
550  * The helper automatically adds the sf_format to the internal URI, so you don't have to.
551  *
552  * @param  string $uri       The internal URI for the dynamic javascript
553  * @param  bool   $absolute  Whether to generate an absolute URL
554  * @param  array  $options   An array of options
555  *
556  * @return string  XHTML compliant <script> tag(s)
557  * @see    javascript_include_tag
558  */
559 function dynamic_javascript_include_tag($uri, $absolute = false, $options = array())
560 {
561   $options['raw_name'] = true;
562
563   return javascript_include_tag(_dynamic_path($uri, 'js', $absolute), $options);
564 }
565
566 /**
567  * Adds a dynamic javascript to the response object.
568  *
569  * The first argument is an internal URI.
570  * The helper automatically adds the sf_format to the internal URI, so you don't have to.
571  *
572  * @see sfResponse->addJavascript()
573  */
574 function use_dynamic_javascript($js, $position = '', $options = array())
575 {
576   $options['raw_name'] = true;
577
578   return use_javascript(_dynamic_path($js, 'js'), $position, $options);
579 }
580
581 /**
582  * Adds a dynamic stylesheet to the response object.
583  *
584  * The first argument is an internal URI.
585  * The helper automatically adds the sf_format to the internal URI, so you don't have to.
586  *
587  * @see sfResponse->addStylesheet()
588  */
589 function use_dynamic_stylesheet($css, $position = '', $options = array())
590 {
591   $options['raw_name'] = true;
592
593   return use_stylesheet(_dynamic_path($css, 'css'), $position, $options);
594 }
595
596 function _dynamic_path($uri, $format, $absolute = false)
597 {
598   return url_for($uri.(false === strpos($uri, '?') ? '?' : '&').'sf_format='.$format, $absolute);
599 }
600
Note: See TracBrowser for help on using the browser.