Link Vault for Craft CMS - Template Variables

downloadURL

The download URL accepts two parameters:

Parameters

  • file (required) : This may either be an instance of an AssetFileModel or it may be a string path to a file on the server.
  • additional parameters : This is an array of custom fields or other variables to be saved to the download record.The downloadAs option changes the filename that will be used for the download.

Sample Code

{# Example 1: Passing an AssetFileModel instance. #}
{% for download in entry.downloadableAssets %}
    <a href="{{ craft.linkVault.downloadURL(download, {downloadAs: 'custom-filename.zip'}) }}" >Download This</a>
{% endfor %}

{# Example 2: Passing a system path. Note: Do not include the basePath 
if your Asset source settings already include the base path. This method 
does not work when the strings contain environment variables. #}
{% for download in entry.downloadableAssets %}
    {% set basePath = craft.config.environmentVariables.basePath %}
    {% set fileFolder = '/'~download.source.settings['path']~download.getFolder().path %}
	{% set filePath = basePath ~ fileFolder ~ download.filename %}
    <a href="{{ craft.linkVault.downloadURL(filePath) }}" >Download This</a>
{% endfor %}

{# Example 3: A hard-coded full system path. #}
<a href="{{ craft.linkVault.downloadURL('/home/user1337/www/uploads/songs/love.mp3') }}" >Download This</a>

Passing an instance of an AssetFileModel is the simplest way to create a Link Vault download URL. This method also works for files stored in an Amazon S3 bucket, a Google Cloud bucket or on a Rackspace account.

Below are some examples that make use of the second parameter to pass along element IDs. In Craft, entries and assets are both have unique element IDs. It is entirely up to you what you store in this column. It is for informational use only.

Sample Code

{# Example 4: The asset's parent entry's ID is stored in the elementId column. #}
{% for download in entry.downloadableAssets %}
    <a href="{{ craft.linkVault.downloadURL(download, {elementId : entry.id}) }}" >Download This</a>
{% endfor %}

{# Example 5: The asset's ID is stored in the elementId column. #}
{% for download in entry.downloadableAssets %}
    <a href="{{ craft.linkVault.downloadURL(download, {elementId : download.id}) }}" >Download This</a>
{% endfor %}

You can create custom fields to store any data you like with Link Vault. These fields are created from the Link Vault area in the control panel. Once you do create a field, just use the field's handle in the array parameter.

Sample Code

{# Example 6: Passing along a value for a user-defined field. #}
{% for download in entry.downloadableAssets %}
    <a href="{{ craft.linkVault.downloadURL(download, {userEmail : craft.session.getUser().email}) }}" >Download This</a>
{% endfor %}

totalDownloads

The totalDownloads variable returns the total downloads for a given set of criteria. It is very similar to the downloadURL variable except it only has one parameter.

Parameters

  • mixed : An instance of an AssetFileModel, an array of parameters, string containing the full system path to a file.

Sample Code

{# Example 7: Passing an AssetFileModel. #}
{% for download in entry.downloadableAssets %}
    <p>The {{ download.filename }} file has been downloaded {{ craft.linkVault.totalDownloads(download) }} times!</p>
{% endfor %}

{# Example 8: Passing an array of parameters. #}
{% for download in entry.downloadableAssets %}
    <p>Your bird.txt Downloads: {{ craft.linkVault.totalDownloads({userId:craft.session.getUser().id, fileName:"bird.txt" }) }}</p>
{% endfor %}

{# Example 9: Passing a string containing the full system path. #}
Total face.gif downloads: {{ craft.linkVault.totalDownloads('/home/user1337/www/uploads/face.gif') }}

fileSize

The fileSize template variable fetches a human-readable file size string for a specified file. This can be used for server files not stored in Craft as assets though it will work with asset files as well.

Sample Code

{# Example 10: Passing a file path. #}
bees.jpg is {{ craft.linkVault.fileSize('/home/user1337/hidden-files/bees.jpg') }}.

{# Example 11: Passing an instance of an AssetFileModel #}
{{ file.filename }} is {{ craft.linkVault.fileSize(file) }}.

{# Example 12: Display the file size with one decimal precision. (Default is 2) #}
{{ file.filename }} is {{ craft.linkVault.fileSize(file, 1) }}.

downloads

The downloads template variable fetches download records based on the specified criteria. Download records are Craft elements 

Sample Code

{# Example 13: Fetch the ten most recent download records for cheese.mpg. #}
{% for record in craft.linkVault.downloads.fileName('cheese.mpg').limit(10) %}
	<p>User {{ record.userId }} downloaded it on {{ record.dateCreated }}</p>
{% endfor %}

{# Example 14: Fetch 5 most recent downloads that occurred prior to March 1, 2016. #}
{% for record in craft.linkVault.downloads.before('2016-03-01').limit(10) %}
	<p>User {{ record.userId }} downloaded {{ record.filename }} before March 1.</p>
{% endfor %}

{# Example 15: Fetch records based on custom field value. In this example, assume existence of "downloadPage" field. #}
{% for record in craft.linkVault.downloads.downloadPage('super-mega-rockstar/free-songs') %}
    <p>User {{ record.userId }} downloaded {{ record.filename }} song file on {{ record.dateCreated }}</p>
{% endfor %}

leechAttempts

The leechAttempts template variable works in the exact same manner as the downloads variable except that it only return leech attempt records.

records

The records template variables works in the same manner as downloads and leechAttempts variables except it will return all records regardless of type.

groupCount

Added in v1.0.2.

The groupCount template variable queries record counts grouped by the values in a specified linkvault_downloads table column name. The resulting count variable is census.

Sample Code

{# Example 16: Fetch a particular user's top file downloads. Order the results by the count variable, descending. #}
{% set topDownloads = craft.linkVault.groupCount('fileName', {
	'userId' : currentUser.id,
	'order' : 'census desc'
}) %}
<ol>
{% for topDownload in topDownloads %}
	<li>{{ topDownload.fileName }} ({{ topDownload.census|number_format(0) }} downloads)</li>
{% endfor %}
</ol>

zipUrl

Added in v1.0.2.

The zipUrl template variable generates a Link Vault download URL for a collection of files that will be zipped on-the-fly when the URL is followed. Each file is tracked individually in the logs. Zipping files on-the-fly could require a lot of memory depending on the size of the files being zipped. It is recommended to only use this feature on smaller files <10MB.

Any numeric value included in the array parameter is assumed to be a valid asset ID.

Sample Code

{# Example 17 : Create a Link Vault zip URL where the zip file name will be "my-files.zip". #}

{# The files can come from numerous sources including asset IDs, system paths and URLs. #}
{% set myFiles = [
    5,
    assetFileVariable1.id,
    assetFileVariable2.id,
    '/full/system/path/to/another-file.pdf',
    'https://example.com/url/to/yet-another-file.gif'                  
] %}
<a href="{{ craft.linkVault.zipUrl(myFiles, 'my-files') }}" >Download Files</a>