Url

Extends Object. Urls give you much more powerful methods over Strings when dealing with URLs for pages or images.

Instantiation

You can create a Url object either of these methods.


<?ev
    // url class method
    var homepage = new Url('/'); 
    
    // or, url function method (lowercase)
    var homepage = url('/'); 
?>

Construct parameters
url

Type String

A String representing the URL. This may be any external or internal URL including Theme URLs file based paths e.g. ~/content etc.



Properties
absolute

Type String

The absolute URL. If you originally supplied a relative path to the URL object it will automatically detect your current protocol and output the correct HTTP or HTTPS protocol and associated domain. 

hash

Type String

The hash fragment at the end of the URL.

hostname

Type String

The hostname and domain of the URL. If you supplied a relative pathname when instantiating the URL the appropriate hostname for the current protocol will be returned.

isHttps

Type Boolean

True if the URL has an HTTPS protocol, else false.

pathname

Type String

Path relative to root that follows the domain of the URL.

port

Type Number

The port if set. It is very unusual to ever need to utilise ports in Evance themes - we've never needed it yet.

protocol

Type String

The current protocol for the URL (e.g. http or https)

relative

Type String

The the relative URL and the default representation of URLs. If you supplied a relative URL there's no change here unless you did some transformations. However if you supplied a Theme URL then you will notice that this value miraculously transforms to a proper relative URL.

search

Type String

The full query string of the URL.



Methods
param(String:key [, String:value])

Returns String | Url

Get or set a query string parameter.


<?ev
    var searchurl = url('/search');
    
    // add a search to the url
    searchurl.param('q', 'search for something'); 
    
    // searchurl is now /search?q=search+for+something
    print(searchurl);
?>
parameter(String:key [, String:value])

Alias of param

params([Object:params])

Returns Object | Url

Get or set all query parameters.


<?ev
    var searchurl = url('/search');
    
    // add a search to the url
    searchurl.parameters({
        key1: 'value 1',
        key2: 'value 2'
    }); 
    
    // searchurl is now /search?key1=value+1&key2=value+2
    print(searchurl);
?>
parameters([Object:params])

Alias of params

toCdn()

Returns Url

Convert a valid static file path based URL to an Evance CDN URL. CDN URLs do not have a protocol, which means they can be used either over HTTP or HTTPS protocols. It is worth noting that <ev:img>, <ev:css> and <ev:js>tags automatically convert relative paths and Theme URLs to CDN URLs for you and you do not need to convert them manually. You may need to use toCdn() only if you are using URLs outside of such tags.


<?ev
    // create a url to a logo in your theme
    var logo = url('/portal/web/gateway/theme/v1/images/logo.png');
    
    // you must use the absolute property to see the full URL
    
    print(logo.absolute); 
    // http://www.mydomain.com/portal/public/1/theme/mytheme/images/logo.png
    
    logo.toCdn();
    
    print(logo.absolute); 
    //cdn.evance.it/portal/public/1/theme/mytheme/images/logo.png
?>

CDN URLs in your CSS
How do I use CDN URLs in my CSS stylesheets? You can use Theme URLs within your CSS stylesheets and Evance will convert these URLs for you automatically without you having to.

toGlobal()

Returns Url

Convert a localised URL with a locale prefix to a globalised version without the locale prefix. 


<!-- assuming we're on an alternative locale to your default -->
<a href="{{ page.url.toGlobal() }}">
    Visit the international version of this page
</a>
toHttp()

Returns Url

Converting toHttp() will convert a URL to the preferred domain for your account that's relevant to the HTTP protocol.


<a href="{{ page.url.toHttp().absolute }}">
    Visit the HTTP version of this page
</a> 
toHttps()

Returns Url

Converting toHttps() will convert the URL to the correct domain for HTTPS connections on your account. If you do not have a premium SSL for your own domain the URL will be converted to your Evance account URL. 


<a href="{{ page.url.toHttps().absolute }}">
    Visit the HTTPS version of this page
</a>
toLocal([locale])

Returns Url

This is useful for multi-lingual or multi-national sites and prefixes the URL with the current locale identifier. You may also supply a locale as a Locale object or string identifier (e.g. en-us) to use as the locale rather than the current.


<?ev
    // Create a url for your default locale
    // this is considered a global URL
    var homepage = new Url('/');
    
    // convert this url to the current locale
    // let's assume we're currently on the English version of your site for the US
    homepage.toLocal();
    
    print(homepage); // the url is now /en-us
?>
toRedirectString()

Returns String

Converts the relative URL to a redirect compatible String. Evance does not permit external redirects. A good example of usage is with Account Login. Let's say you have a product page and wish trade customers to login to see prices:


<a href="/auth/login?direct={{ product.url.toRedirectString() }}">
    Login to see trade prices
</a>