You are looking at the old Apostrophe 0.5 documentation. It is deprecated for new projects. Check out the latest version!

Files - nunjucks helpers

← Previous: Files - browser-side methods

Overview

User-uploaded files, such as images, PDFs or Word documents, are part of every Apostrophe site.

Use these Nunjucks helpers to sift through Apostrophe areas and widgets to locate the file objects you want, and also to generate URLs referring to them. This is great when you want to bypass the regular markup and user interface of slideshow widgets and the like.

aposAreaImage(page, name, options)

aposAreaImage({ area: area, options... })

Find an image referenced within an area, such as an image in a slideshow widget. Returns the first file object matching the criteria. Only GIF, JPEG and PNG images will be returned.

The returned object can be passed to aposFilePath to obtain a URL for use in an img element.

Options

extension

To force Apostrophe to return only images with a specific file extension (gif, jpg or png), specify the extension option. Do not specify a leading .. Note that Apostrophe always uses these three extensions for images.

extensions

Specify an array of allowed file extensions. (You do not need to specify jpeg, JPG, etc. Apostrophe always uses jpg.)

Example:

{% set image = aposAreaImage(page, 'body') %}
{% if image %}
  <img src="{{ aposFilePath(image, { size: 'small' }) }}" />
{% endif %}

aposAreaImages(page, name, options)

aposAreaImages({ area: area, options... })

Find images referenced within an area, such as an image in a slideshow widget. Returns an array of file objects that meet the criteria. Only GIF, JPEG and PNG images will be returned.

The returned objects can be passed to aposFilePath to obtain a URL for use in an img element.

Options

extension

To force Apostrophe to return only images with a specific file extension (gif, jpg or png), specify the extension option. Do not specify a leading .. Note that Apostrophe always uses these three extensions for images.

extensions

Specify an array of allowed file extensions. (You do not need to specify jpeg, JPG, etc. Apostrophe always uses jpg.)

Example:

{% set images = aposAreaImages(page, 'body') %}
<ul>
  {% for image in images %}
    <li>
      <img src="{{ aposFilePath(image, { size: 'small' }) }}" />
    </li>
  {% endif %}
</ul>

aposAreaFile(page, areaName, options)

aposAreaFile({ area: area, options... })

Find an file referenced within an area, such as a PDF in a file widget or an image in a slideshow widget. Returns the first file object matching the criteria.

The returned object can be passed to aposFilePath to obtain a URL.

Options

extension

To force Apostrophe to return only images with a specific file extension (gif, jpg, pdf, xlsx, png, etc.), specify the extension option. Do not specify a leading .. Note that Apostrophe always uses specific extensions, always lower case, typically three letters except for xlsx and other recent Microsoft Office formats.

extensions

Specify an array of allowed file extensions.

Example:

{% set pdf = aposAreaFile(page, 'body', { extension: 'pdf'}) %}
{% if pdf %}
  <a href="{{ aposFilePath(pdf) }}">Download PDF</a>
{% endif %}

aposAreaFiles(page, areaName, options)

aposAreaFiles({ area: area, options... })

Find files referenced within an area, such as a PDF in a file widget or an image in a slideshow widget. Returns an array of file objects that meet the criteria.

The returned objects can be passed to aposFilePath to obtain a URL.

Options

extension

To force Apostrophe to return only images with a specific file extension (gif, jpg, pdf, xlsx, png, etc.), specify the extension option. Do not specify a leading .. Note that Apostrophe always uses specific extensions, always lower case, typically three letters except for xlsx and other recent Microsoft Office formats.

extensions

Specify an array of allowed file extensions.

Example:

{% set pdfs = aposAreaFiles(page, 'body', { extension: 'pdf' }) %}
<ul>
  {% for pdf in pdfs %}
    <li>
      <a href="{{ aposFilePath(pdf) }}">Download {{ pdf.name | e }}</a></a>
    </li>
  {% endif %}
</ul>

aposFilePath(file, options)

Given a file object, as returned by aposAreaFile for instance, return the file URL. If options.size is set, return the URL for that size (one-sixth, one-third, one-half, two-thirds, full).

full is "full width" (1140px), not the original. For the original, don't pass size.

Additional image sizes can be configured on a per-project basis.

Both the server side and the browser side have equivalent JavaScript methods accessible as apos.filePath.

Always use this function to create URLs to files. Otherwise your code will cease to work if your project's file storage is moved to Amazon S3 at a later date.

Example:

{% set image = aposAreaImage(page, 'body') %}
{% if image %}
  <img src="{{ aposFilePath(image, { size: 'small' }) }}" />
{% endif %}

Next: Files - web API →