Customizing assets

Note: The functionality described in this article is not available in Commerce versions 11 and up.

Note: Episerver uses the Episerver asset system by default. If you want to enable the legacy asset management system, set the UseLegacyAssetSystem configuration setting to true in the web.config files of both the Commerce Manager and the front-end sites. 

You can customize asset information because it is stored as a Business Foundation (BF) object. You can store general fields for assets, to store the display text associated with each asset. You also can create asset extensions for different document types. These extensions store information unique to that type of asset. For example, the built-in extension class for images, ImageFolderElementExtension, stores height and width information for images. These fields would not be stored for PDF documents otherwise. Another example: create an MS Word document extension that stores the word count associated with a Word doc.

Classes in this topic are available in the Mediachase.Commerce.Assets namespace.

• Customizing asset information
• Creating asset extensions
• Associating assets with catalog entries
• ContentType and MimeType
• Mapped extensions

Customizing asset information

Do the following to customize the asset information from the Episerver Commerce administration interface:

1. Go to the Administration section of Commerce Manager.
2. Go to System Settings and select Business Foundation.
3. Select FolderElementEntity. This is the BF object that represents assets.
4. Add or edit properties as necessary and save your changes.

Creating asset extensions

Create asset extensions in two parts: create the extension in BF (steps 1-5), and implement the extension in code (steps 6-13).

1. Go to the Administration section of Commerce Manager.
2. Go to System Settings and select the Business Foundation node.
3. Select New/Extension.
4. Enter names for extension, set the parent business object to FolderElement, and save.
5. Add whatever fields you want to store for that asset type.
6. Create a new project or one separate from the source code.
7. Add the following references to the project:
   • System.Configuration
   • CommerceLib/Mediachase.Commerce
   • Mediachase.BusinessFoundation
   • Mediachase.BusinessFoundation.Data
8. Add the following using statements in the extension class definition:

   using System;
   using System.IO;
   using Mediachase.BusinessFoundation.Blob;
   using Mediachase.Commerce.Assets;
   using Mediachase.Commerce.Assets.Configuration;

9. Create a new class which inherits from Mediachase.Commerce.Assets.IFolderElementExtension.
10. Create your implementation of the class.

    There are two methods required by this interface: Initialize() and Process(). The Initialize method is called during the asset creation process, by the FolderElementEntity.Create() method, which is called when new assets are being added. Use this method to do any initialization required for the extension. It is called before the Process() method by the FolderElementEntity.Create() method.

    The Process() method includes an input parameter of the FolderElementEntity object, which contains information about the file.

    Example: extracting file information and adding to the asset extension instance

    C#

    public void Process(FolderElementEntity element)
            {
              element.Card = cardName;
              BlobInfo blobInfo = element.GetBlobInfo();
    
              if (blobInfo != null)
              {
                BlobStorageProvider provider = BlobStorage.Providers[blobInfo.Provider];
                if (provider != null)
                {
                  using (Stream stream = provider.ReadStream(blobInfo))
                  {
                try
                    {
                      Image img = Image.FromStream(stream);
                      element["Width"] = img.Width;
                      element["Height"] = img.Height;
                    }
                    catch (ArgumentException)
                    {}
                  }
                }
              }
            }

    Find information about the file with the GetBlobInfo() method, which provides a BlobInfo object. Use this object to return the BlobStorageProvider from the BlobStorage providers collection. Finally, the provider creates an instance of your object from a stream. From there, you can inspect the file and set custom properties associated with the file. Update to properties of the FolderElementEntity passed in, and the API saves the data to the database.

    Note: The Card value of the FolderElementEntity instance is the place where you can store the name of the asset extension associated with the file. The Card value is useful for database queries but is not used for programmatic purposes.

11. Add a reference to the B2CSampleSite and Commerce Manager (may be the same).
12. In the ecf.asset.config file, add a new element under the ElementTypes (see also MimeType, below).

    Example: adding an element type in the asset configuration file

    XML

    <ElementTypes>
    ...existing types..
    <add mimeType="text/plain" type="CustomAssetExtension.TextFolderElementExtension, CustomAssetExtension" />
    </ElementTypes>

13. Build the project. You can add documents of the type you specified with your extension and see the custom data for that asset type stored separately in the BF object.

Associating assets with catalog entries

This is useful, for instance, when importing a catalog and want to link items to assets, such as images or documents. For each object in the catalog, you can have a list of assets, mapping, for example, product 123 to assets 345 and 567.

Example: creating an ItemAsset for each asset linking the asset and catalog item together

int assetId = 123;
        int entryId = 456;
        var entryDto = CatalogContext.Current.GetCatalogEntryDto(entryId);
        CatalogEntryDto.CatalogItemAssetRow assetRow = entryDto.CatalogItemAsset.NewCatalogItemAssetRow();
        assetRow.AssetKey = assetId.ToString();
        assetRow.AssetType = "file";
        assetRow.CatalogEntryId = entryId;
        assetRow.GroupName = "default";
        assetRow.SortOrder = 0;
        entryDto.CatalogItemAsset.AddCatalogItemAssetRow(assetRow);
        CatalogContext.Current.SaveCatalogEntry(entryDto);

ContentType and MimeType

When assets are added to the system through the API, or the Episerver Commerce administration interface which uses the API, most major file extensions are mapped to the correct content type. The content type is also known as a mimeType, which is critical to mapping a file imported into Episerver Commerce to the correct asset extension. However, not all file types are mapped, so you need to check if they are and register additional file types as necessary.

Below is a list of the mapped extensions. If the extension you are creating an extension for is not listed, add your own mapping of file extension to content type. To do this, use the Mediachase.BusinessFoundation.Blob.ContentTypeResolver.ContentType.Register() method, passing in the extension (without the ".") and content type.

Note: The .docx file extension does not appear in the following list. You can support current MS Word Document formats using the following method call in your Initialize method. This method registers the content type only once. Subsequent calls will simply update the existing registration. You can add this to the Commerce Manager Global.asax Application_Start() method.

Mediachase.BusinessFoundation.Blob.ContentTypeResolver.ContentType.Register("docx", "application/msword");

Mapped extensions