1: <?php
2: /**
3: * Copyright 2007 Maintainable Software, LLC
4: * Copyright 2006-2012 Horde LLC (http://www.horde.org/)
5: *
6: * @author Mike Naberezny <mike@maintainable.com>
7: * @author Derek DeVries <derek@maintainable.com>
8: * @author Chuck Hagenbuch <chuck@horde.org>
9: * @license http://www.horde.org/licenses/bsd
10: * @category Horde
11: * @package View
12: * @subpackage Helper
13: */
14:
15: /**
16: * View helpers for URLs
17: *
18: * @author Mike Naberezny <mike@maintainable.com>
19: * @author Derek DeVries <derek@maintainable.com>
20: * @author Chuck Hagenbuch <chuck@horde.org>
21: * @license http://www.horde.org/licenses/bsd
22: * @category Horde
23: * @package View
24: * @subpackage Helper
25: */
26: class Horde_View_Helper_Url extends Horde_View_Helper_Base
27: {
28: /**
29: * Returns the URL for the set of +options+ provided. This takes the
30: * same options as url_for in ActionController (see the
31: * documentation for ActionController::Base#url_for). Note that by default
32: * <tt>:only_path</tt> is <tt>true</tt> so you'll get the relative /controller/action
33: * instead of the fully qualified URL like http://example.com/controller/action.
34: *
35: * When called from a view, url_for returns an HTML escaped url. If you
36: * need an unescaped url, pass :escape => false in the +options+.
37: *
38: * ==== Options
39: * * <tt>:anchor</tt> -- specifies the anchor name to be appended to the path.
40: * * <tt>:only_path</tt> -- if true, returns the relative URL (omitting the protocol, host name, and port) (<tt>true</tt> by default unless <tt>:host</tt> is specified)
41: * * <tt>:trailing_slash</tt> -- if true, adds a trailing slash, as in "/archive/2005/". Note that this
42: * is currently not recommended since it breaks caching.
43: * * <tt>:host</tt> -- overrides the default (current) host if provided
44: * * <tt>:protocol</tt> -- overrides the default (current) protocol if provided
45: * * <tt>:user</tt> -- Inline HTTP authentication (only plucked out if :password is also present)
46: * * <tt>:password</tt> -- Inline HTTP authentication (only plucked out if :user is also present)
47: * * <tt>:escape</tt> -- Determines whether the returned URL will be HTML escaped or not (<tt>true</tt> by default)
48: *
49: * ==== Relying on named routes
50: *
51: * If you instead of a hash pass a record (like an Active Record or Active Resource) as the options parameter,
52: * you'll trigger the named route for that record. The lookup will happen on the name of the class. So passing
53: * a Workshop object will attempt to use the workshop_path route. If you have a nested route, such as
54: * admin_workshop_path you'll have to call that explicitly (it's impossible for url_for to guess that route).
55: *
56: * ==== Examples
57: * <%= url_for(:action => 'index') %>
58: * # => /blog/
59: *
60: * <%= url_for(:action => 'find', :controller => 'books') %>
61: * # => /books/find
62: *
63: * <%= url_for(:action => 'login', :controller => 'members', :only_path => false, :protocol => 'https') %>
64: * # => https://www.railsapplication.com/members/login/
65: *
66: * <%= url_for(:action => 'play', :anchor => 'player') %>
67: * # => /messages/play/#player
68: *
69: * <%= url_for(:action => 'checkout', :anchor => 'tax&ship') %>
70: * # => /testing/jump/#tax&ship
71: *
72: * <%= url_for(:action => 'checkout', :anchor => 'tax&ship', :escape => false) %>
73: * # => /testing/jump/#tax&ship
74: *
75: * <%= url_for(Workshop.new) %>
76: * # relies on Workshop answering a new_record? call (and in this case returning true)
77: * # => /workshops
78: *
79: * <%= url_for(@workshop) %>
80: * # calls @workshop.to_s
81: * # => /workshops/5
82: *
83: * @return string
84: */
85: public function urlFor($first = array(), $second = array())
86: {
87: return is_string($first) ? $first : $this->controller->getUrlWriter()->urlFor($first, $second);
88: }
89:
90: /**
91: * Creates a link tag of the given +name+ using a URL created by the set of
92: * +options+. See the valid options in the documentation for url_for. It's
93: * also possible to pass a string instead of an options hash to get a link
94: * tag that uses the value of the string as the href for the link, or use
95: * +:back+ to link to the referrer - a JavaScript back link will be used in
96: * place of a referrer if none exists. If nil is passed as a name, the link
97: * itself will become the name.
98: *
99: * ==== Options
100: * * <tt>:confirm => 'question?'</tt> -- This will add a JavaScript confirm
101: * prompt with the question specified. If the user accepts, the link is
102: * processed normally, otherwise no action is taken.
103: * * <tt>:popup => true || array of window options</tt> -- This will force the
104: * link to open in a popup window. By passing true, a default browser window
105: * will be opened with the URL. You can also specify an array of options
106: * that are passed-thru to JavaScripts window.open method.
107: * * <tt>:method => symbol of HTTP verb</tt> -- This modifier will dynamically
108: * create an HTML form and immediately submit the form for processing using
109: * the HTTP verb specified. Useful for having links perform a POST operation
110: * in dangerous actions like deleting a record (which search bots can follow
111: * while spidering your site). Supported verbs are :post, :delete and :put.
112: * Note that if the user has JavaScript disabled, the request will fall back
113: * to using GET. If you are relying on the POST behavior, you should check
114: * for it in your controller's action by using the request object's methods
115: * for post?, delete? or put?.
116: * * The +html_options+ will accept a hash of html attributes for the link tag.
117: *
118: * Note that if the user has JavaScript disabled, the request will fall back
119: * to using GET. If :href=>'#' is used and the user has JavaScript disabled
120: * clicking the link will have no effect. If you are relying on the POST
121: * behavior, your should check for it in your controller's action by using
122: * the request object's methods for post?, delete? or put?.
123: *
124: * You can mix and match the +html_options+ with the exception of :popup and
125: * :method which will raise an ActionView::ActionViewError exception.
126: *
127: * ==== Examples
128: * link_to "Visit Other Site", "http://www.rubyonrails.org/", :confirm => "Are you sure?"
129: * # => <a href="http://www.rubyonrails.org/" onclick="return confirm('Are you sure?');">Visit Other Site</a>
130: *
131: * link_to "Help", { :action => "help" }, :popup => true
132: * # => <a href="/testing/help/" onclick="window.open(this.href);return false;">Help</a>
133: *
134: * link_to "View Image", { :action => "view" }, :popup => ['new_window_name', 'height=300,width=600']
135: * # => <a href="/testing/view/" onclick="window.open(this.href,'new_window_name','height=300,width=600');return false;">View Image</a>
136: *
137: * link_to "Delete Image", { :action => "delete", :id => @image.id }, :confirm => "Are you sure?", :method => :delete
138: * # => <a href="/testing/delete/9/" onclick="if (confirm('Are you sure?')) { var f = document.createElement('form');
139: * f.style.display = 'none'; this.parentNode.appendChild(f); f.method = 'POST'; f.action = this.href;
140: * var m = document.createElement('input'); m.setAttribute('type', 'hidden'); m.setAttribute('name', '_method');
141: * m.setAttribute('value', 'delete'); f.appendChild(m);f.submit(); };return false;">Delete Image</a>
142: */
143: public function linkTo($name, $options = array(), $htmlOptions = array())
144: {
145: $url = $this->urlFor($options);
146:
147: if ($htmlOptions) {
148: $href = isset($htmlOptions['href']) ? $htmlOptions['href'] : null;
149: // @todo convert_options_to_javascript!(html_options, url)
150: $tagOptions = $this->tagOptions($htmlOptions);
151: } else {
152: $tagOptions = null;
153: }
154:
155: $hrefAttr = isset($href) ? null : 'href="' . $url . '"';
156: $nameOrUrl = isset($name) ? $name : $url;
157: return '<a ' . $hrefAttr . $tagOptions . '>' . $nameOrUrl . '</a>';
158: }
159:
160: /**
161: * Creates a link tag of the given +name+ using a URL created by the set of
162: * +options+ unless the current request URI is the same as the links, in
163: * which case only the name is returned (or the given block is yielded, if
164: * one exists). You can give link_to_unless_current a block which will
165: * specialize the default behavior (e.g., show a "Start Here" link rather
166: * than the link's text).
167: *
168: * ==== Examples
169: * Let's say you have a navigation menu...
170: *
171: * <ul id="navbar">
172: * <li><%= link_to_unless_current("Home", { :action => "index" }) %></li>
173: * <li><%= link_to_unless_current("About Us", { :action => "about" }) %></li>
174: * </ul>
175: *
176: * If in the "about" action, it will render...
177: *
178: * <ul id="navbar">
179: * <li><a href="/controller/index">Home</a></li>
180: * <li>About Us</li>
181: * </ul>
182: *
183: * ...but if in the "home" action, it will render:
184: *
185: * <ul id="navbar">
186: * <li><a href="/controller/index">Home</a></li>
187: * <li><a href="/controller/about">About Us</a></li>
188: * </ul>
189: *
190: * The implicit block given to link_to_unless_current is evaluated if the current
191: * action is the action given. So, if we had a comments page and wanted to render a
192: * "Go Back" link instead of a link to the comments page, we could do something like this...
193: *
194: * <%=
195: * link_to_unless_current("Comment", { :controller => 'comments', :action => 'new}) do
196: * link_to("Go back", { :controller => 'posts', :action => 'index' })
197: * end
198: * %>
199: */
200: public function linkToUnlessCurrent($name, $url, $htmlOptions = array())
201: {
202: return $this->linkToUnless($this->isCurrentPage($url),
203: $name, $url, $htmlOptions);
204: }
205:
206: /**
207: * Creates a link tag of the given +name+ using a URL created by the set of
208: * +options+ unless +condition+ is true, in which case only the name is
209: * returned. To specialize the default behavior (i.e., show a login link
210: * rather than just the plaintext link text), you can pass a block that
211: * accepts the name or the full argument list for link_to_unless.
212: *
213: * ==== Examples
214: * <%= link_to_unless(@current_user.nil?, "Reply", { :action => "reply" }) %>
215: * # If the user is logged in...
216: * # => <a href="/controller/reply/">Reply</a>
217: *
218: * <%=
219: * link_to_unless(@current_user.nil?, "Reply", { :action => "reply" }) do |name|
220: * link_to(name, { :controller => "accounts", :action => "signup" })
221: * end
222: * %>
223: * # If the user is logged in...
224: * # => <a href="/controller/reply/">Reply</a>
225: * # If not...
226: * # => <a href="/accounts/signup">Reply</a>
227: */
228: public function linkToUnless($condition, $name, $url, $htmlOptions = array())
229: {
230: return $condition ? $name : $this->linkTo($name, $url, $htmlOptions);
231: }
232:
233: /**
234: * Creates a link tag of the given +name+ using a URL created by the set of
235: * +options+ if +condition+ is true, in which case only the name is
236: * returned. To specialize the default behavior, you can pass a block that
237: * accepts the name or the full argument list for link_to_unless (see the examples
238: * in link_to_unless).
239: *
240: * ==== Examples
241: * <%= link_to_if(@current_user.nil?, "Login", { :controller => "sessions", :action => "new" }) %>
242: * # If the user isn't logged in...
243: * # => <a href="/sessions/new/">Login</a>
244: *
245: * <%=
246: * link_to_if(@current_user.nil?, "Login", { :controller => "sessions", :action => "new" }) do
247: * link_to(@current_user.login, { :controller => "accounts", :action => "show", :id => @current_user })
248: * end
249: * %>
250: * # If the user isn't logged in...
251: * # => <a href="/sessions/new/">Login</a>
252: * # If they are logged in...
253: * # => <a href="/accounts/show/3">my_username</a>
254: */
255: public function linkToIf($condition, $name, $url, $htmlOptions = array())
256: {
257: return $this->linkToUnless(!$condition, $name, $url, $htmlOptions);
258: }
259:
260: /**
261: * Creates a mailto link tag to the specified +email_address+, which is
262: * also used as the name of the link unless +name+ is specified. Additional
263: * HTML attributes for the link can be passed in +html_options+.
264: *
265: * mail_to has several methods for hindering email harvestors and customizing
266: * the email itself by passing special keys to +html_options+.
267: *
268: * ==== Options
269: * * <tt>encode</tt> - This key will accept the strings "javascript" or "hex".
270: * Passing "javascript" will dynamically create and encode the mailto: link then
271: * eval it into the DOM of the page. This method will not show the link on
272: * the page if the user has JavaScript disabled. Passing "hex" will hex
273: * encode the +email_address+ before outputting the mailto: link.
274: * * <tt>replace_at</tt> - When the link +name+ isn't provided, the
275: * +email_address+ is used for the link label. You can use this option to
276: * obfuscate the +email_address+ by substituting the @ sign with the string
277: * given as the value.
278: * * <tt>replace_dot</tt> - When the link +name+ isn't provided, the
279: * +email_address+ is used for the link label. You can use this option to
280: * obfuscate the +email_address+ by substituting the . in the email with the
281: * string given as the value.
282: * * <tt>subject</tt> - Preset the subject line of the email.
283: * * <tt>body</tt> - Preset the body of the email.
284: * * <tt>cc</tt> - Carbon Copy addition recipients on the email.
285: * * <tt>bcc</tt> - Blind Carbon Copy additional recipients on the email.
286: *
287: * ==== Examples
288: * mailTo("me@domain.com")
289: * # => <a href="mailto:me@domain.com">me@domain.com</a>
290: *
291: * mailTo("me@domain.com", "My email", array('encode' => "javascript"))
292: * # => <script type="text/javascript">eval(unescape('%64%6f%63...%6d%65%6e'))</script>
293: *
294: * mailTo("me@domain.com", "My email", array('encode' => "hex"))
295: * # => <a href="mailto:%6d%65@%64%6f%6d%61%69%6e.%63%6f%6d">My email</a>
296: *
297: * mailTo("me@domain.com", null, array('replaceAt' => "_at_", 'replaceDot' => "_dot_", 'class' => "email"))
298: * # => <a href="mailto:me@domain.com" class="email">me_at_domain_dot_com</a>
299: *
300: * mailTo("me@domain.com", "My email", array('cc' => "ccaddress@domain.com",
301: * 'subject' => "This is an example email"))
302: * # => <a href="mailto:me@domain.com?cc=ccaddress@domain.com&subject=This%20is%20an%20example%20email">My email</a>
303: */
304: public function mailTo($emailAddress, $name = null, $htmlOptions = array())
305: {
306: // extra options "cc", "bcc", "subject", "body"
307: $extras = '';
308: $extraParts = array('cc', 'bcc', 'body', 'subject');
309: foreach ($extraParts as $partName) {
310: if (isset($htmlOptions[$partName])) {
311: $partValue = str_replace('+', '%20', urlencode($htmlOptions[$partName]));
312: $extras .= "{$partName}={$partValue}&";
313: }
314: unset($htmlOptions[$partName]);
315: }
316: if (! empty($extras)) {
317: $extras = '?' . rtrim($extras, '&');
318: }
319:
320: // obfuscation options "replaceAt" and "replaceDot"
321: $emailAddressObfuscated = $emailAddress;
322: foreach (array('replaceAt' => '@', 'replaceDot' => '.') as $option => $find) {
323: if (isset($htmlOptions[$option])) {
324: $emailAddressObfuscated = str_replace($find,
325: $htmlOptions[$option],
326: $emailAddressObfuscated);
327: }
328: unset($htmlOptions[$option]);
329: }
330:
331: $string = '';
332:
333: $encode = isset($htmlOptions['encode']) ? $htmlOptions['encode'] : null;
334: unset($htmlOptions['encode']);
335:
336: if ($encode == 'javascript') {
337: $name = isset($name) ? $name : $emailAddress;
338: $htmlOptions = array_merge($htmlOptions,
339: array('href' => "mailto:{$emailAddress}{$extras}"));
340: $tag = $this->contentTag('a', $name, $htmlOptions);
341:
342: foreach (str_split("document.write('$tag');") as $c) {
343: $string .= sprintf("%%%x", ord($c));
344: }
345:
346: return "<script type=\"text/javascript\">eval(unescape('$string'))</script>";
347: } elseif ($encode == 'hex') {
348: $emailAddressEncoded = '';
349: foreach (str_split($emailAddressObfuscated) as $c) {
350: $emailAddressEncoded .= sprintf("&#%d;", ord($c));
351: }
352:
353: foreach (str_split('mailto:') as $c) {
354: $string .= sprintf("&#%d;", ord($c));
355: }
356:
357: foreach (str_split($emailAddress) as $c) {
358: if (preg_match('/\w/', $c)) {
359: $string .= sprintf("%%%x", ord($c));
360: } else {
361: $string .= $c;
362: }
363: }
364: $name = isset($name) ? $name : $emailAddressEncoded;
365: $htmlOptions = array_merge($htmlOptions,
366: array('href' => $string . $extras));
367: return $this->contentTag('a', $name, $htmlOptions);
368:
369: } else {
370: $name = isset($name) ? $name : $emailAddressObfuscated;
371: $htmlOptions = array_merge($htmlOptions,
372: array('href' => "mailto:{$emailAddress}{$extras}"));
373: return $this->contentTag('a', $name, $htmlOptions);
374: }
375: }
376:
377: /**
378: * True if the current request URI was generated by the given +options+.
379: *
380: * ==== Examples
381: * Let's say we're in the <tt>/shop/checkout</tt> action.
382: *
383: * current_page?(:action => 'process')
384: * # => false
385: *
386: * current_page?(:controller => 'shop', :action => 'checkout')
387: * # => true
388: *
389: * current_page?(:action => 'checkout')
390: * # => true
391: *
392: * current_page?(:controller => 'library', :action => 'checkout')
393: * # => false
394: *
395: * @todo finish implementation
396: */
397: public function isCurrentPage($options)
398: {
399: $urlString = htmlentities($this->urlFor($options));
400: if (preg_match('/^\w+:\/\//', $urlString)) {
401: // @todo implement
402: // url_string == "#{request.protocol}#{request.host_with_port}#{request.request_uri}"
403: throw new Horde_View_Exception('not implemented');
404: } else {
405: if ($this->controller) {
406: // @todo prepending "/" is a hack, need to fix request object
407: $request = $this->controller->getRequest();
408: $requestUri = '/' . ltrim($request->getPath(), '/');
409: } else {
410: // @todo accessing $_REQUEST directly is a hack
411: $requestUri = $_SERVER['REQUEST_URI'];
412: }
413:
414: return rtrim($urlString, '/') == rtrim($requestUri, '/');
415: }
416: }
417:
418: }
419: