Customizing assets

Introduction

Asset information can be customized since it is stored as Business Foundation objects. You can store general fields for all assets, for instance to store the display text associated with each asset. You can also create asset extensions for different document types. These extensions allow you to store information unique to that type of asset.

For example, there is a built-in extension class for images called ImageFolderElementExtension, which stores height and width information for images. These fields would not otherwise be stored for PDF documents. Another example might be that to create a MS Word document extension that stores the word count associated with the Word doc.

Classes referred to here are available in the following namespaces:

• Mediachase.Commerce.Assets

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 Business Foundation object that represents assets.
4. Add/edit properties as necessary and save your changes.

Creating asset extensions

Asset extension creation is done in two parts: creating the extension in Business Foundation (steps 1-5 below), and implementing the extension in code (step 6-13 below).

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. Make sure the following using statements are 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

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)
                {}
              }
            }
          }
        }

Information about the file can be found using the GetBlobInfo() method, which provides a BlobInfo object. This object can be used to return the BlobStorageProvider from the BlobStorage Providers collection. Finally the provider will allow you to create an instance of your object from a stream. From there, you can inspect the file and set custom properties associated with the file. You just have to update to properties of the FolderElementEntity passed in, and the API will handle saving the data to the database.

Note that 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

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

13. Build the project. After doing this you should be able to add documents of the type you specified with your extension and see the custom data for that asset type stored separately in the Business Foundation object.

Associating assets with catalog entries

This is useful for instance when you are 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 being 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, you can 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 the content type.

Note from the list below that .docx is not listed. You could support current MS Word Document formats using the following method call in your Initialize method:

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

This method will only register the content type once. Subsequent calls will simply update the existing registration. You can add this to the Commerce Manager Global.asax Application_Start() method.

Mapped extensions

File	Extension Type
323	text/h323
acx	application/internet-property-stream
ai	application/postscript
aif	audio/x-aiff
aifc	audio/x-aiff
aiff	audio/x-aiff
asf	video/x-ms-asf
asr	video/x-ms-asf
asx	video/x-ms-asf
au	audio/basic
avi	video/x-msvideo
axs	application/olescript
bas	text/plain
bcpio	application/x-bcpio
bin	application/octet-stream
bmp	image/bmp
c	text/plain
cat	application/vnd.ms-pkiseccat
cdf	application/x-cdf
cer	application/x-x509-ca-cert
class	application/octet-stream
clp	application/x-msclip
cmx	image/x-cmx
cod	image/cis-cod
cpio	application/x-cpio
crd	application/x-mscardfile
crl	application/pkix-crl
crt	application/x-x509-ca-cert
csh	application/x-csh
css	text/css
dcr	application/x-director
der	application/x-x509-ca-cert
dir	application/x-director
dll	application/x-msdownload
dms	application/octet-stream
doc	application/msword
dot	application/msword
dvi	application/x-dvi
dxr	application/x-director
eps	application/postscript
etx	text/x-setext
evy	application/envoy
exe	application/octet-stream
fif	application/fractals
flr	x-world/x-vrml
gif	image/gif
gtar	application/x-gtar
gz	application/x-gzip
h	text/plain
hdf	application/x-hdf
hlp	application/winhlp
hqx	application/mac-binhex40
hta	application/hta
htc	text/x-component
htm	text/html
html	text/html
htt	text/webviewhtml
ico	image/x-icon
ief	image/ief
iii	application/x-iphone
ins	application/x-internet-signup
isp	application/x-internet-signup
jfif	image/pipeg
jpe	image/jpeg
jpeg	image/jpeg
jpg	image/jpeg
js	application/x-javascript
latex	application/x-latex
lha	application/octet-stream
lsf	video/x-la-asf
lsx	video/x-la-asf
lzh	application/octet-stream
m13	application/x-msmediaview
m14	application/x-msmediaview
m3u	audio/x-mpegurl
man	application/x-troff-man
mdb	application/x-msaccess
me	application/x-troff-me
mht	message/rfc822
mhtml	message/rfc822
mid	audio/mid
mny	application/x-msmoney
mov	video/quicktime
movie	video/x-sgi-movie
mp2	video/mpeg
mp3	audio/mpeg
mpa	video/mpeg
mpe	video/mpeg
mpeg	video/mpeg
mpg	video/mpeg
mpp	application/vnd.ms-project
mpv2	video/mpeg
ms	application/x-troff-ms
mvb	application/x-msmediaview
nws	message/rfc822
oda	application/oda
p10	application/pkcs10
p12	application/x-pkcs12
p7b	application/x-pkcs7-certificates
p7c	application/x-pkcs7-mime
p7m	application/x-pkcs7-mime
p7r	application/x-pkcs7-certreqresp
p7s	application/x-pkcs7-signature
pbm	image/x-portable-bitmap
pdf	application/pdf
pfx	application/x-pkcs12
pgm	image/x-portable-graymap
pko	application/ynd.ms-pkipko
pma	application/x-perfmon
pmc	application/x-perfmon
pml	application/x-perfmon
pmr	application/x-perfmon
pmw	application/x-perfmon
pnm	image/x-portable-anymap
pot	application/vnd.ms-powerpoint
ppm	image/x-portable-pixmap
pps	application/vnd.ms-powerpoint
ppt	application/vnd.ms-powerpoint
prf	application/pics-rules
ps	application/postscript
pub	application/x-mspublisher
qt	video/quicktime
ra	audio/x-pn-realaudio
ram	audio/x-pn-realaudio
ras	image/x-cmu-raster
rgb	image/x-rgb
rmi	audio/mid
roff	application/x-troff
rtf	application/rtf
rtx	text/richtext
scd	application/x-msschedule
sct	text/scriptlet
setpay	application/set-payment-initiation
setreg	application/set-registration-initiation
sh	application/x-sh
shar	application/x-shar
sit	application/x-stuffit
snd	audio/basic
spc	application/x-pkcs7-certificates
spl	application/futuresplash
src	application/x-wais-source
sst	application/vnd.ms-pkicertstore
stl	application/vnd.ms-pkistl
stm	text/html
sv4cpio	application/x-sv4cpio
sv4crc	application/x-sv4crc
t	application/x-troff
tar	application/x-tar
tcl	application/x-tcl
tex	application/x-tex
texi	application/x-texinfo
texinfo	application/x-texinfo
tgz	application/x-compressed
tif	image/tiff
tiff	image/tiff
tr	application/x-troff
trm	application/x-msterminal
tsv	text/tab-separated-values
txt	text/plain
uls	text/iuls
ustar	application/x-ustar
vcf	text/x-vcard
vrml	x-world/x-vrml
wav	audio/x-wav
wcm	application/vnd.ms-works
wdb	application/vnd.ms-works
wks	application/vnd.ms-works
wmf	application/x-msmetafile
wps	application/vnd.ms-works
wri	application/x-mswrite
wrl	x-world/x-vrml
wrz	x-world/x-vrml
xaf	x-world/x-vrml
xbm	image/x-xbitmap
xla	application/vnd.ms-excel
xlc	application/vnd.ms-excel
xlm	application/vnd.ms-excel
xls	application/vnd.ms-excel
xlt	application/vnd.ms-excel
xlw	application/vnd.ms-excel
xof	x-world/x-vrml
xpm	image/x-xpixmap
xwd	image/x-xwindowdump
z	application/x-compress
zip	application/zip