Method: Perfion.WriteFile( … )
- Morten Lindequist Køhler
Will write any file and image stored by Perfion to a file. For images it can resize, change the image format and change the aspect by exact fitting or cropping or smart fitting. It performs all of the same well known image manipulation functionality as the Media Server, and the syntax is identical.
This method will also check if the file you intend to write has already been written, and only spend time on retrieving and updating the file if its timestamp is different from the file stored in Perfion.
This method is also capable of writing multiple files, e.g. from a Multi-valued feature in Perfion.
Syntax
{ScriptObject} WriteFile( string id = "", string file = "{@id}{@par}", string par = "", string root = "" )All the parameters to this method are optional. Therefore it is recommend to include them by name, as shown in the examples below. The behavior of each parameter is described in the following table.
Method Parameters
string | The unique Perfion Guid ID of a file, or a ';' separated list of multiple IDs, specifying which files or images to deliver. Default: Will take the Value of the current Map-entry. So if used on a Map-entry that contains valid IDs you do not need to specify this parameter. |
|
string | Specify the filename(s). If unspecified it defaults to the following template "{@id}{@par}" When specifying a template you can use static content as well several different parameters about the file as described in the following table: |
|
| @id | The unique Perfion Guid ID |
| @par | Short-form describing the most important aspects of the requested file or image, such as version, image-size, dpi, fitting, quality and background.color. The value could look like this, if you requested an image to be cropped and fit within 300x300 pixels: -300x300-Crop |
| @filename | The name of the file as it is stored in Perfion |
| @index | A numeric index, that can be used for Multi-valued features, if you do not want to use the unique @id or @filename is not unique, or you simply want to use a shared name (e.g. the SKU) so they would all have the same filename unless an index was added. |
Alternative:
As an alternative to the above template naming. You can also specify the name exactly as you want it, or specify a ';' separated list of filenames to be used when multiple id's are requested. In the latter case, the number of filenames must of course match the number of id's requested.|
string | Specify what (if anything) to do or change about images before writing them. |
|
| size | The size in pixels (width x height) that an image has to fit within. |
| dpi | The size in DPI (dots per inch). |
| fit | How an image is made to fit within a specified size. |
| format | The requested image-format. The Perfion stored image, is automatically converted to the requested format such as jpg, png, tif, bmp, gif etc. It is also possible to specify the format as follows: |
| version | If logging of binaries is enabled in Perfion this makes it possible to request the logged version of the binary file. Values are 0 (not versioned) or 1 (versioned) binary. |
| quality | The image quality. |
| tiffcomp | The TIFF compression method. |
| backgroundcolor | The requested background color of an image. |
| canvascolor | The requested canvas color of the image. It is only usable when image is resized with 'fit' option set to 'aspectratio'. |
| colorprof | The color profile of the target image. It is only usable with images which support color profiles. If specified the image colors will be converted to that color profile and the profile itself will be embedded to the image file. |
|---|---|---|
| usepoi | The request to use the Point-of-Interest (POI) of the image if it has POI specified in its metadata. If image does not have POI specified or the POI is not used, then POI will be equivalent to value 50x50 which is the center of the image. |
| poi | The request to use the custom Point-of-Interest (POI) of the image. This parameter can only be used if 'usepoi' is used and set to '1'. If this parameter is used, then it will overwrite the original image POI value saved as its metadata. |
| wa | Write Always |
string | Specifies the root of a path. |
|
Example 1
Below automatically takes the image-ids from the current Map-entry, and generates filenames based on the specified template by including the static part "Binaries/SKUImage-" and concatenating this with a lookup from the current Input-row of the "{SKU}" followed by a name-part "{@par}" constructed automatically based on the requested image parameters.
The root-path is taken from a global variable named $RootPath.
The image is requested as "size=200x200&format=web", meaning to fit within 200x200 pixels and be delivered in one of the web-formats (jpg, gif or png).
The method returns a simple object that delivers the OutFileName (which is the name the file was written as based on the file-naming-template, rootpath etc. This OutFileName is written to the Value of the Output-row so it contains information about where the file is. Voila!
var info = Perfion.WriteFile(
file: "Binaries/SKUImage-{SKU}{@par}",
root: "{=$RootPath}",
par: "size=200x200&format=web" );
Value = info.OutFileName;Example 2
Below example is a tiny bit more advanced? It shows how a multivalued image feature could be written. Again by using a file-naming template, but this time including the @index parameter to make sure each image get a unique name, since they would otherwise end up with the same name (in this example). You can of course always use the unique Perfion Guid ID, but sometimes you want to export the images or files by using other more readable names.
var info = Perfion.WriteFile(
file: "Binaries/SKUMultiImages-{SKU}[{@index}]*{@par}",
root: "C:/FileRoot/",
par: "size=300x200&format=web" );
Value = info.OutFileName;