Link Vault for ExpressionEngine - Template Tags

Mask links, track links, guard against hotlinking and leeching. Like Prego, it's in here.

The :download_link template tag generates a protected link to a file stored on the server or to a file stored on a remote server. When the link is clicked, a download record is generated and the file is downloaded.

Parameters

  • file_name : The file name (commonly used with the directory parameter.)
  • directory : Enter a directory path if the file is not in the default hidden folder. (commonly used with the file_name parameter.
  • file_path : If you don't specify a file_name and directory independently, use this parameter to specify the complete path or a URL that contains the true path to the file. Note: Do not use a URL for S3 links; only use folder path and file name.
  • download_as : To override the actual file name for the download, enter a valid file name in this parameter without the file extension. This parameter is only available when serving a file stored locally on the server.
  • entry_id : An entry ID may be specified for logging purposes if download files are associated with a channel.
  • url_only : If value is 'true', only the URL will be returned. (Default: false)
  • action_only : If value is 'true', the URL will exclude the site index from the beginning of the URL. Only the action number and the rest of the query string will be included in the returned URL. (Default: false)
  • class : The CSS class attribute to use for the anchor element.
  • text : The text that is displayed in the anchor element. (Default: Download)
  • remote : Set this to "true" if the file is hosted on a remote server. (Default: false)
  • cf: : 'cf:' is the prefix for any custom field created in the Link Vault control panel. (Examples: cf:user_agent, cf:download_page, cf:screen_name)
  • s3_bucket : If you'd like to fetch a file from your Amazon S3 account, specify the bucket here. To specify which file you'd like to fetch, use the 'file_path' parameter. Note: You may need to override the default S3 endpoint using the 'link_vault_aws_endpoint' config variable if your bucket exists outside the US Standard Region.
  • expires : Use this parameter to set an expiration date/time that the link will no longer show on the page upon page load. The date/time format must conform to one of the accepted PHP date/time formats.
  • expires_text : Use this parameter to specify some content that should be displayed if the link has expired.
  • show_file_name : Set this parameter to 'true' if you'd like the name of the file to appear in the generated URL. The query string parameter value created by this tag parameter is not used during processing.

Sample Code

{!-- Basic Examples --}
{exp:link_vault:download_link file_name='file.zip' entry_id='520' member_id='23'}
{exp:link_vault:download_link file_name='file.zip' url_only='true'}
{exp:link_vault:download_link file_name='file.zip' cf:category='catname'}
{exp:link_vault:download_link file_name='file.zip' url_only='true' cf:category='catname' }
{exp:link_vault:download_link file_path='http://othersite.com/somefile.zip' remote='true' }
{exp:link_vault:download_link file_name='file.zip' expires='2013-01-01' expires_text='Not available' }
{exp:link_vault:download_link file_name='fonts.zip' show_file_name='true' }
{exp:link_vault:download_link file_path='/the/full/system/path/to/file.zip' text='Download now' }
{exp:link_vault:download_link directory='/the/full/system/path/to/' file_name='file.zip' text='Click this' }
{exp:link_vault:download_link directory='relative/to/docroot/' file_name='yes.mp3' text='Download song' }
{exp:link_vault:download_link file_path='http://example.com/music/horsemask-sonata.mp3' text='Download my song' }
{exp:link_vault:download_link file_name='entire-directory-of-employees.csv' download_as='directory' }

{!-- Sample Output --}
<a href="http://site.com/?ACT=30&lv=eomDdQoswRC%2FqjxKLXR2Te0hebW7dtx%2B38g3i3hh2hs1fm">Download Now!</a>

{!-- Show the file name --}
{exp:link_vault:download_link directory='../downloads/' file_name='burrito-recipe.pdf' url_only='true' }

{!-- Sample Output --}
http://example.com/?file=burrito-recipe.pdf&ACT=30&lv=eomDdQoswRC%2FqjxKLXR2Te0hebW7dtx%2B38g3i3hh2hs1fm

{exp:link_vault:download_link file_name="file.zip" class="my-link-style"}
{exp:link_vault:download_link file_name="file.zip" url_only="true"}
Result:
http://site.com/?ACT=30&e=1928&file=eomDdQoswRC%2FqjxKLXR2Te0hebW7dtx%2B

{exp:link_vault:download_link file_name="file.zip" url_only="true" action_only="true"}
{exp:link_vault:download_link file_path="mega/uploads/file.zip" entry_id="1234"}

{!-- Remote File Examples --}
{exp:link_vault:download_link file_name="http://www.site.ly/a.txt" text="view file" remote="true"}
{exp:link_vault:download_link file_name="http://mysite.com/monkeys.zip" remote="true"}

{!-- Amazon S3 Examples --}
{exp:link_vault:download_link s3_bucket='images' file_path='animals/monkeys.png' text='Get Monkeys'}
{exp:link_vault:download_link s3_bucket='tutes' file_path='video.flv' cf:file_category='tutorial'}

:download_url

This template tag is a shortcut for the :download_link tag with the url_only parameter set to true.

Added v1.4.0

Sample Code

{exp:link_vault:download_url file_name="pdfcollection.zip" }

{!-- Result: --}
http://site.com/?ACT=24&lv=eo3B4C4tenTbQlehAAksaEH1nmb7...

:download_action

This template tag is a shortcut for the :download_link tag with the url_only and action_onlyparameters set to true. It outputs the Link Vault query string starting with the ACT parameter.

Added v1.4.0

Sample Code

{exp:link_vault:download_action file_name="pdfcollection.zip" }

{!-- Result: --}
?ACT=24&lv=eo3B4C4tenTbQlehAAksavtNNxd0EH1nmb7...

:download_button

The :download_button template tag generates a button contained within a mostly hidden form. When the button is clicked, a download record is generated and the file is downloaded.

Parameters

  • file_name : The file name (commonly used with the directory parameter.)
  • directory : Enter a directory path if the file is not in the default hidden folder. (commonly used with the file_name parameter.
  • file_path : If you don't specify a file_name and directory independently, use this parameter to specify the complete path or a URL that contains the true path to the file. Note: Do not use a URL for S3 links; only use folder path and file name.
  • download_as : To override the actual file name for the download, enter a valid file name in this parameter without the file extension. This parameter is only available when serving a file stored locally on the server.
  • entry_id : An entry ID may be specified for logging purposes if download files are associated with a channel.
  • action_only : If value is 'true', the URL will exclude the site index from the beginning of the URL. Only the action number and the rest of the query string will be included in the returned URL. (Default: false)
  • class : The CSS class attribute to use for the button element.
  • text : The text that is displayed on the button. (Default: Download)
  • remote : Set this to "true" if the file is hosted on a remote server. (Default: false)
  • cf: : 'cf:' is the prefix for any custom field created in the Link Vault control panel. (Examples: cf:user_agent, cf:download_page, cf:screen_name)
  • s3_bucket : If you'd like to fetch a file from your Amazon S3 account, specify the bucket here. To specify which file you'd like to fetch, use the 'file_path' parameter. Note: You may need to override the default S3 endpoint using the 'link_vault_aws_endpoint' config variable if your bucket exists outside the US Standard Region.
  • expires : Use this parameter to set an expiration date/time that the button will no longer show on the page upon page load. The date/time format must conform to one of the accepted PHP date/time formats.
  • expires_text : Use this parameter to specify some content that should be displayed if the button has expired.

Sample Code

{!-- Regular Examples --}
{exp:link_vault:download_button file_name='file.zip'}
{exp:link_vault:download_button file_name='file.zip' directory='misc-files/apps/' }
{exp:link_vault:download_button file_name='file.zip' class='greenbtn rounded' }
{exp:link_vault:download_button file_name='file.zip' text='Click to Download' }
{exp:link_vault:download_button file_path='http://www.site.com/file.zip' entry_id='1234' remote='true' }
{exp:link_vault:download_button file_path='http://www.site.com/file.zip' cf:user_agent='Chrome 11.0' }

{!-- This example will generate a link that downloads a zip file renamed as "terrible-music.zip" --}
{exp:link_vault:download_button file_name='justice-beaver-complete-discography.zip' download_as='terrible-music' }

{!-- Amazon S3 Examples --}
{exp:link_vault:download_button s3_bucket='stock-photos' file_path='call-center-lady.png'}
{exp:link_vault:download_button s3_bucket='horses' file_path='directory/names/horse.gif' }

:download_count

The :download_count template tag returns the total download count based on the provided parameters. It can also be used to return the number of leech attempts based on the parameters.

Parameters

  • file_name : The file name or URL.
  • entry_id : The channel entry ID for the file.
  • directory : Enter a directory path if the file is not in the default hidden folder.
  • file_path : If you don't specify a file_name and directory independently, use this parameter to specify the complete path.
  • table_name : The name of the table in which to count. Options: downloads, leeches. (Default: downloads)
  • member_id : Specify a member_id to return the number of times a particular member has downloaded a file.
  • start_date : The starting date in a range of dates. (format : Y-m-d)
  • end_date : The end date in a range of date. (format : Y-m-d)
  • cf: : 'cf:' is the prefix for any custom field created in the Link Vault control panel. (Examples: cf:user_agent, cf:download_page, cf:screen_name)

Sample Code

{exp:link_vault:download_count entry_id='1234' }
{exp:link_vault:download_count file_name='photos.zip' directory='alternative/directory/' }
{exp:link_vault:download_count file_name='photos.zip' member_id='312' }
{exp:link_vault:download_count file_name='photos.zip' table_name='leeches' }
{exp:link_vault:download_count entry_id='1234' start_date='2012-01-01' end_date='2012-02-14' }

:file_size

The :file_size template tag returns a file size for a specified file that is stored locally.

Parameters

  • file_name : The file name.
  • directory : Enter a directory path if the file is not in the default hidden folder.
  • file_path : If you don't specify a file_name and directory independently, use this parameter to specify the complete path.

Sample Code

{!-- Basic Usage --}
{exp:link_vault:file_size file_name='file.zip' directory='files/other-directory/' }
{exp:link_vault:file_size file_path='images/random/animals/reggy.jpg' }
{exp:link_vault:file_size file_path='http://example.com/url/to/file.tar.gz' }

{!-- Sample Output --}
3 GB
14 KB
20 MB

:url

The :url template tag generates a protected link by encrypting the true URL. It doesn't have to be associated with a download and it will not be logged in any way. It is simply a way to mask the destination of a link. As of Link Vault 1.1.0, the :url template tag supports Link Vault custom fields.

Parameters

  • url : The URL that is to be encrypted.
  • cf: : 'cf:' is the prefix for any custom field created in the Link Vault control panel. (Examples: cf:user_agent, cf:download_page, cf:screen_name)

Sample Code

{exp:link_vault:url url='http://example.com/link/i/want/to/track' }
{exp:link_vault:url url='http://example.com/remote/content/im/sharing' cf:page='{segment_1}/{segment_2}' }

:pretty_url

The :pretty_url template tag accepts a URL and description text. The description text is made into a URL friendly unique identifier that Link Vault uses to redirect the user to the specified URL. This template tag accepts custom field parameters and the encrypted data is attached to the URL.

Parameters

  • url : The URL that is to be obscured.
  • text : A description of the URL's destination.
  • cf: : 'cf:' is the prefix for any custom field created in the Link Vault control panel. (Examples: cf:user_agent, cf:current_uri, cf:screen_name)

Sample Code

{exp:link_vault:pretty_url url='http://site.com/long/url/or/blog/title' text='visit my blog'}
http://site.com?go=visit-my-blog&ACT=46

{exp:link_vault:pretty_url url='http://site.com/advertisement/link' text='visit our sponsor'}
http://site.com?go=visit-our-sponsor&ACT=46

:click_count

The :click_count template tag queries the number of clicks that particular URL has received. This tag only works if link click logging is enabled in the Link Vault module settings.

Parameters

  • url : The URL for which you'd like the count.
  • member_id : Specify a member ID if you'd like limit the count to the number of times a particular member clicked a link.
  • start_date : The starting date in a range of dates. (format : Y-m-d)
  • end_date : The end date in a range of dates. (format : Y-m-d)

Sample Code

{exp:link_vault:click_count url='http://example.com/tracked/site/link' }
{exp:link_vault:click_count url='http://twitter.com/devot_ee' start_date='2012-01-01' end_date='2012-12-31' }
{exp:link_vault:click_count url='http://ellislab.com' member_id='8170' }

:records

The template tag pair queries the link_vault_downloads for downloads or link clicks. It can also query the link_vault_leeches table for leech attempts.

Parameters

  • table : The data you'd like to query. Options: downloads, leeches, link_clicks. (Default: downloads)
  • directory : Return downloads where the file comes from a particular directory.
  • file_name : Return downloads for a particular file name.
  • url : Return link click statistics for a particular URL.
  • pretty_url_id : Return link click statistics for a particular pretty URL ID.
  • member_id : Specify a member ID if you'd like to list downloads for a particular member.
  • start_date : The starting date in a range of dates. (format : Y-m-d)
  • end_date : The end date in a range of dates. (format : Y-m-d)
  • group_by : Specify a link_vault_downloads column name to group the results. Using the group_by parameter creates the 'census' variable to store the count tally.
  • count_variable : If you'd like your 'census' variable to have a different name, specify the desired name in the count_variable parameter. (Default: census)
  • order_by : Order the results by a particular field. Any field in the link_vault_downloads table is valid. (Default: unix_time)
  • sort : Options: asc, desc. (Default: desc)
  • limit : Limit the number of results returned. (Default: 100)
  • cf: : You may search by custom fields with the 'cf:' prefix. (Examples: cf:user_agent, cf:download_page, cf:screen_name).
  • variable_prefix : If you are nesting the template tag inside another tag, you can use this parameter to add a prefix to the template variables in order to avoid conflicting with template variables from another tag.

Sample Code

{!--  Member ID 5's 10 most recent downloads of 'logos.zip'. --}
{exp:link_vault:records table='downloads' member_id='5' file_name='logos.zip' limit='10'}
    {count}
    {id}
    {site_id}
    {entry_id}
    {unix_time format='%m-%d-%Y %H:%i'}
    {member_id}
    {remote_ip}
    {directory}
    {file_name}
    {is_link_click}

    {!-- sample custom fields --}
    {cf_screen_name}
    {cf_download_page}
    {cf_user_agent}
{/exp:link_vault:records}

{!-- Top encrypted link clicks (non-downloads) --}
{exp:link_vault:records table='link_clicks' group_by='url' order_by='census' sort='desc' }
    <p>{count}. {url} : {census} clicks.</p>
{/exp:link_vault:records}

{!-- Top 10 downloaded files --}
{exp:link_vault:records table='downloads' group_by='file_name' order_by='census' sort='desc' limit='10'}
    <p>{count}. {file_name} was downloaded {census} times.</p>
{/exp:link_vault:records}

{!-- Top 5 users with the most downloads --}
{exp:link_vault:records table='downloads'
    group_by='member_id'
    count_variable='download_count'
    order_by='download_count'
    sort='desc'
    limit='5'}
    <p>{count}. Member {member_id} has downloaded {download_count} files.</p>
{/exp:link_vault:records}

{!-- All leech attempts by member with ID 300, most recent first --}
{exp:link_vault:records table='leeches' member_id='300' order_by='unix_time' sort='desc'}
    <p>Leech attempt for {file_name} file on {unix_time format='%m/%d/%Y'}</p>
{/exp:link_vault:records}

{!-- 15 most recent downloads with a variable prefix --}
{exp:link_vault:records table='downloads' order_by='date' sort='desc' limit='15' variable_prefix='md_' }
    {if md_no_results}<p>No downloads ever!</p>{/if}
    <p>Member {md_member_id} downloaded {md_file_name} at {md_unix_time format='%m-%d-%Y %H:%i'}</p>
{/exp:link_vault:records}