getcontent

The Axiell WebAPI has built-in functionality to retrieve images, movies and audio files, using the getcontent command. When a URL containing getcontent is executed in an internet browser, the media file type will be recognized by the browser (if the browser supports the file format) and the file becomes (dis)playable instantly. On the other hand, when a URL containing getcontent has been set as a retrieval path for an image field in an Adlib for Windows application, Adlib won't recognize the media types of files other than images and will therefore only display linked media files in the Media Viewer if those are image files: instead of the getcontent command in retrieval paths, we must therefore use the getmediainfo command for Adlib for Windows applications. For Axiell Collections applications this is not so and you should use the getcontent command for all media types. However, since the Media Viewer in Collections uses browser functionality for media display, Collections can only display or play media file formats which the browser supports. (Add-ons are available for most browser to extend file format support.)
To be precise: the range of media formats which can be displayed by the Media Viewer in Axiell Collections is limited by either browser support or HTML5 video/audio player support.

• Image formats which are supported amongst all browsers* are: .jpeg, .tiff (in Firefox and Chrome not by default), .bmp, .gif, .svg and .png.

• For audio, HTML5 only supports .mp3, .wav, .opus and .ogg extensions, of which only .mp3 is supported by all browsers*.

• For video, HTML5 only supports .mp4 (H.264), .webm (VP8/VP9) and .ogg (Daala), of which only .mp4 is supported by all browsers*.

• "all browsers" meaning the browsers supported by Axiell Collections: Chrome, Firefox, Edge and Safari.
  

To use the getcontent functionality, the server manager must have setup an "image handler" using the adlibweb.xml parameter file. Images, movies or audio files (the latter two only in browsers) will be retrieved (downloaded, not streamed) using the getcontent command. To retrieve a file, the caller needs to provide at least two arguments: the name of the server in the server argument and the file identifier in the value argument. The media file id can be retrieved from database records. Image ids are usually stored in the reproduction.reference field.
All arguments other than server and value apply to images files only, not to other media files. If you do specify any of them for other media files, the WebAPI attempts to load an image file with the same id but with the .jpg extension instead. If that file is not present, the WebAPI tries to load a default image named movie.jpg. If that fails as well, a system exception will be thrown. So if you want to use a single query to retrieve both images and movies while applying any of the image specific getcontent arguments, do at least make sure a default movie.jpg image is present to avoid the exception.

An image with incorrect rotation metadata was rotated "back" due to automatic (since 3.5.1.2266) rotation correction by the WebApi when it was retrieved by the WebAPI. This was fixed in 3.7.1.3066 by introducing a new <imageServerConfiguration> setting: you can now optionally disable the default rotation correction for any rotation metadata by setting the new <adjustRotation> property to false.

The Axiell WebAPI does not support streaming media. You'll have to set up a third-party streaming media server to be able to stream movies or audio.

Syntax

command=getcontent&<parameter>=<value>&...

• server (String) name of the image server to retrieve content from.
• value (String) identifier of the digital content to be retrieved, namely a file name, a file name preceded by a partial path, or URL (URLs allowed in WebAPI versions of 2011-10-18 and later). From WebAPI version 3.0.21342.1 it is no longer allowed for local files to be included this way if their path is beyond the path configured for the image server. If an attempt is made to include a file from a higher folder anyway, an error is returned: <message>Error retrieving document for content id: relevant_path</message>.
  Also use the whiteList setting (available from 3.0.21309.1) in adlibweb.xml to limit allowed URLs to websites you trust.
• width (Integer) [optional] width of target area into which the digital content must be resized, if it concerns an image; the aspect ratio of the image will always remain intact. Consider using %width% instead of a specific value to automatically retrieve an image in the size requested by Axiell Collections for detail or thumbnail display and for printing: this saves processing time and fixes an issue where images are printed too small. When using height=%height% as well, the aspect ratio of the image will remain intact.
• height (Integer) [optional] height of target area into which the digital content must be resized, if it concerns an image; the aspect ratio of the image will always remain intact. Consider using %height% instead of a specific value to automatically retrieve an image in the size requested by Axiell Collections for detail or thumbnail display and for printing: this saves processing time and fixes an issue where images are printed too small. When using width=%width% as well, the aspect ratio of the image will remain intact.
• scalemode (String) [optional, available from wwwopac.ashx version 3.6.278.0] determines how an image to be retrieved should be scaled and how it should be presented. You can choose from two modes:
  
  • fit - will scale an image (whilst keeping the aspect ratio of the image intact) to fit into the box defined with the width and height parameters. This means that the entire image will be visible, and that if the box has a different aspect ratio from the image, the image will be centered in the box, either in height or width, leaving part of the background of the box (the so-called canvas) empty. The empty part of the canvas can be given a colour using the canvascolor parameter.
  • fill - will scale an image (whilst keepting the aspect ratio of the image intact) to completely fill the box defined with the width and height parameters. This means that only part of the image will be visible if the box has a different aspect ratio from the image. Which part of the image will be visible, can be determined by the fillmode parameter; by default the left or top part of the image will be visible.

  Besides scaling the image, the box containing the image can be presented with rounded corners, using the cornerradius and cornercolor parameters.

• fillmode (String) [optional, to be used with the scalemode=fill argument] determines which part of the image will be visible. You can choose from three options:
  
  • topleft - will display the left or top part of the image.
  • center - will display a centre part of the image.
  • bottomright - will display the right or bottom part of the image.
• canvascolor (String) [optional, to be used with the scalemode=fit argument or the imageformat parameter] determines the colour of the empty part of the canvas of the box specified using the width and height parameters. Colour names are determined by the .NET Framework 4 Color Structure object, which is documented on: MSDN. Examples of colour names are: black, white, transparent, orange, etc.
• cornerradius (Integer) [optional, to be used with the scalemode or imageformat parameter] specifies the radius (in pixels) of rounded corners of the box specified using the width and height parameters. The minimum value is 10.
• cornercolor (String) [optional, to be used with the scalemode or imageformat parameter] determines the colour of the space left open by rounded corner of the box specified using the width, height and cornerradius parameters. Colour names are determined by the .NET Framework 4 Color Structure object, which is documented on: MSDN. Examples of colour names are: black, white, transparent, orange, etc.
• imageformat (String) [optional] specifies the output file format of the image to be retrieved. You can use it to retrieve all images in an internet browser compatible and memory usage friendly format, like jpg for example. With this parameter, the source image file format will automatically be transformed to the target format before sending the file; the source file format and the cached file format* remain unchanged. Valid values for this parameter are: jpg, tiff, png, and ico. If you choose png you can choose to set the canvascolor and/or the cornercolor parameters to the value transparent.
  Without the imageformat parameter, the image will always be retrieved in the original image file format.
  * If you ever check your cache folders, you'll notice that all cached image files have the bmp format and have a double file extension of the type .<original extension>.bmp. This intermediate storage format is for internal image handler purposes only, to improve its performance, but you can forget all about it when you use the getcontent command (with or without the imageformat parameter).
• folderId (Integer) [optional] must be filled with the record number of the reproduction record from which the digital content must be retrieved, if you are using an enterprise solution in which each branch of your organisation uses its own images folder and dataset in a common reproductions database. In that case, image file names might not be unique, so the WebAPI also needs to know from which images folder the image must be retrieved. The record number of the relevant reproduction record provides this information, albeit indirectly because it allows the api to match the record number with an appropriate record number range specified for one of the datasets of the reproductions database, via the <folderMappingList> in the image server specification in adlibweb.xml, which specifies the lower and upper record number limits for all branch reproduction datasets and their associated branch-specific folders containing the images.

Examples

- no Adlib.Data-specific syntax or examples available yet -

- no jQuery-specific syntax or examples available yet -