Working With Related Assets

Often, when you have database item (such as a product, article, or event), you will want to associate one or more files with it. These may be photos, documents, spreadsheets, or anything else.

Because different situations have different requirements, there are several different ways to associate files with database items. When you add a custom field to an item type, you'll see the following choices among the field types:

• Dedicated File
• Related Assets
• Legacy Related Assets (deprecated)

The last of these options, Legacy Related Assets, uses an older approach that we do not recommend for new designs. It provides a single pool of related files for an item type, and you cannot have more than one Legacy Related Assets field for a given item type.

Using the Dedicated File Type

When creating a custom item type, add a field and set the field type to Dedicated File.

The Dedicated File field type is intended for situations in which you want to associate a single file with the database item, which is "dedicated" to that item; that is, the file is only used in the context of the item.

There are no options for a dedicated file; the goal of this field type is to provide the simplest possible path for attaching a file to a database item. It has the following behaviors:

• The file must be chosen from the admin user's computer and uploaded as part of the item creation. There is no option for using a file that is already on the server.
• If the item is deleted, the corresponding file is also deleted from the server.
• There are no upload options. You cannot apply tags or enter metadata, and renditions are always created.
• Files are stored in an automatically created folder structure, which ensures that there are never file-name collisions. The intent is that these files are accessed only through the database item edit screen.

Accessing a dedicated file using WebvantaScript is simplicity itself. If you have named the field "logo", you can display the logo on a page as follows:

<img src="<w:logo />">

If the file is a PDF document, for example in a field named "data_sheet", then you'd simply link to it:

<a href="<w:data_sheet />">Data Sheet</a>

While each Dedicated File field references only a single file, you can have as many Dedicate File fields as you need in one item type. For example, you might have one for a logo, and another for a data sheet.

Using the Related Assets Type

While the Dedicated File type provides the simplest admin experience and the easiest access from WebvantaScript, the Related Assets type is much more flexible.

When creating a custom item type, add a field and set the field type to Related Assets.

The admin user can then add files using various approaches when creating or editing a database item:

• Click the Add Files from Zip button. The files in the zip file are unpacked into an automatically created folder structure, using the name of the item type for the outermost folder, the name of the item for the inner folder, and the name of the zip file for the innermost folder. There are no options when using this path; renditions are always created, and the user cannot add metadata.
• Click the Add File button. This displays the standard Webvanta file selection dialog, which allows the user to choose a file already on the server, or to upload a file from their computer. If uploading a file, the file will go to the root of the site unless the user selects a folder first. No folders are automatically created when using this path. The user can choose whether or not to create renditions, and they can add metadata to the file.

If you want to allow selection of multiple files after clicking the Add File button, enter an asterisk (*) in the Type Options field. Otherwise, only one file can be selected.

Note that multiple file selection only applies to files that are already on the server. When uploading from the user's computer, only a single file can be selected. To upload multiple files at once, combine them into a zip file and upload the zip file.

Accessing Related Assets

Suppose you have two Related Assets fields: documents and photos. When you are in an item context (such as on an item page inside a <w:kb:item> block, or in a <w:kb:item:each> loop), you can access them as follows:

<w:photos>
  <w:assets:each>
    <img src="<w:path />" />   
  </w:assets:each> 
</w:photos> 
<w:documents>   
  <w:assets:each>     
    <a href="<w:path />"><w:filename /></a>   
  </w:assets:each> 
</w:documents>

For images, you can include a rendition name in the w:path statement if you want to access a size other than the original (see Creating and Accessing Image Renditions for details.

The Legacy Related Assets Type

The Legacy Related Assets type is an older feature that is now deprecated. For new designs, use the Related Assets field type.

The Legacy Related Assets type operates much like the new Releated Assets field type, except that you don't need to set the name context and there can be only one pool of files for a given item type. (If you use multiple Legacy Related Assets fields, you will not be able to access the groups separately.>

When you are in an item context (such as on an item page inside a <w:kb:item> block, or in a <w:kb:item:each> loop), you can access the related assets (assuming they are images) as follows:

<w:assets:each>   <img src="<w:path />" /> </w:assets:each>

Another Approach: Start With the Assets

Note that you can also define associations as part of the asset's metadata. For example, when you upload (or update) an asset (uploaded file of any type), you can assign it to one or more categories or tags. So you could, for example:

• Make a category "chairs"
• Assign the "chairs" category to all photos of chairs
• Assign the "chair" tag to each product that is a chair

You can then access all of the chair photos whenever you are displaying a chair product page.

For more details on this approach, see Accessing Images and Other Files.