Skip to content

Configuration

Jump to bottom Edit New page
blackcity edited this page Jul 12, 2013 · 19 revisions

###Configuration example In this example all options are set, mostly with the default values (Note: You do not have to set the default values explicitly in your real project). All options, settings and enumerations are suggested by the Visual Studio Intellisense and verified against the schema if you follow the setup instructions in Example 02 or Example 03.

<?xml version="1.0"?>
<fileUpload storageContext="Filesystem" enableIntegratedHandler="true" webFilesRoot="" uniqueFileNames="false" keepOrgFileNames="false" getInclSubFolders="true" returnFilesUrl="true" returnExtraInfo="basic" allowDelete="true" deleteHandler="~/Backload/UploadHandler" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:name="urn:fileupload-schema" xsi:noNamespaceSchemaLocation="Web.FileUpload.xsd" >
  <fileSystem filesRoot="~/Files" usersRoot="" objectsRoot="" copiesRoot="" />
  <database assemblyName="Backload_Tester" dbContext="Backload_Tester.UpFilesEntities" entitySetName="Files" primaryKeyName="ID" />
  <security allowAnonymous="true" allowedDownloadRoles="*" allowedUploadRoles="*" allowedDeleteRoles="*" />
  <images width="600" height="400" dpi="96" canvasColor="#ffffffff" forceImageType="none" resizeMode="none" />
  <thumbnails path="_thumbs" width="80" height="80" dpi="96" canvasColor="#00ffffff" resizeMode="ratio" imageType="image/png" />
  <clientFiles scripts="~/Scripts/FileUpload/" styles="~/Content/FileUpload/css/" />
  <contentTypes thumbnailPath="~/Content/FileUpload/content-types/" thumbnailSize="48" useThumbnailCanvas="true">
    <!-- <clear />              // Deletes all predefined types -->
    <remove name="_AdobePDFFile"/> <!--Remove predefined pdf type handling-->
    <add name="SamplePDFFiles" extFragment=".pdf" typeFragment="application/pdf" thumbnail="PDF.png" subFolder="pdfs" />
    <add name="SampleAllImageFiles" extFragment="" typeFragment="image/" thumbnail="" subFolder="images" />
  </contentTypes>
</fileUpload>

###Options and settings ####fileUpload (configuration section) General settings for the Backload. component. #####Attributes

  • storageContext: Files may be stored in the file system or in a database (by the Entity Framework) [Default: "Filesystem", Pro/Enterprise].
  • enableIntegratedHandler: By default the internal file upload handler is running and ready to receive incoming files (PUT/POST) or requests (GET or DELETE). If you do not want the built in controller to be rinning, e.g. you'll handle requests by your own controllers in order to do some business logic (see Example 04), set this to "false". [Default: "true", Pro/Enterprise].
  • webFilesRoot: Leave this an empty string, if filesRoot is relative to the web root (starts with '~/', see filesRoot). If filesRoot is an absolute local path (see filesRoot) this must be an absolute web url to the files root (e. g. "http://myfiles.filestore.com/files/" [Default: "", Pro/Enterprise].
  • uniqueFileNames: Generates unique file names based on guids [Default: "false"].
  • keepOrgFileNames: Only applies if you use the uniqueFileNames option. If set to true, the original file name will be tracked (subfolder: _mappings) [Default: "false"].
  • getInclSubFolders: On a GET request (return list of existing files) only the upload root folder (Default: filesRoot/[objectsRoot]) is searched for uploaded files. If "true", the search includes subfolders. (Example: A content-type specific subfolder is set to "pdffiles". If getInclSubFolders="true" the search on a GET request will list all files within this subfolder. There are several other ways setting up subfolders, e.g. uploadContext and objectContext) [Default: "false"].
  • returnFilesUrl: By default the url to the uploaded files is returned, so the user is able to open the uploaded file (download). If you do not want that default behaviour set this to "false", so users are not able to download files. In this case, in order to provide download capabilities, you can setup your own contollers/handlers with your own business logic [Default: "true", Pro/Enterprise].
  • returnExtraInfo: Returns information about original file names, folders (returnFilesUrl must be "true") and extra message [Default: "basic"].
  • allowDelete: Set to "false" if deletion of uploaded files should be not possible [Default: "true", Pro/Enterprise].
  • deleteHandler: By default (deleteHandler="") the Backload component handles incoming delete requests. If you need to delete uploaded files within your own business logic set a relative (~/...) or absolute path (starts with http or https). The url of the handler is returned to the browser in the json output for the delete url [Default: "", Pro/Enterprise].
  • xmlns:xsi: No custom setting. Used for schema validation and Visual Studio Intellisence. Registers the xsi namespace [Default: "http://www.w3.org/2001/XMLSchema-instance"].
  • xmlns:name: No custom setting. Used for schema validation and Visual Studio Intellisence. Registers the namespace for the schema [Default: "urn:fileupload-schema"].
  • xsi:noNamespaceSchemaLocation: No custom setting. Used for schema validation and Visual Studio Intellisence. Path to the schema file [Default: "Web.FileUpload.xsd"].

#####Configuration elements

  • fileSystem: Sets up the root folders if storageContext="Filesystem". If you don't need a greater control on the storage structure all files will be stored directly in the root folders (flat structure). Otherwise you may use the content type based subfolder settings (config file) or the objectContext/uploadContext parameters sent with each client side request, which altogether support a very complex storage structure.
  • database: Database related settings if storageContext="Database". Backload. leverages your DBContext derived classes (Entity Framework). The component needs to know the related DBContext class, root entity set and primary keys. Backload. uses the same storage structure as the filesystem. So, if you setup content based subfolders, in a database context this will be the entities accessed with the help of navigation properties (for more information on this, see MSDN Entity Framework) [Enterprise].
  • security: Security related settings like authentication and authorization. Define if users must be authenticated or if there are roles-based restrictions. By default there are no restrictions. If you need a greater control, set up your own controller to receive the request, do the authentication/authorization and then call the Backload. handler [Pro/Enterprise].
  • images: Backload. is able to resize and crop images when they are uploaded. These settings determine the max. width and height, canvas and canvas color (if a canvas is used) and several resize options. The image can also be converted to a new target type (e.g. tiff to png).
  • thumbnails: This setting determines how thumbnails will be created. It has the same attributes like "images". The "path" attribute, determines the path of the thumbnail.
  • clientFiles: If the bundeling feature of the Backload. component is used (see Example 01), set the appropriate client files folders here.
  • contentTypes: ContentTypes serves two purposes: First, it is used to send an appropriate thumbnail of the file type back to the browser if it is not an image. Second: On uploads you can define a subfolder for a content-type that matches a regular Expression you define, in order to store any content of this type in a related subfolder (e.g. pdf files in a "pdfs" subfolder) [Enterprise].

####fileSystem (configuration element) Sets up the _root folders_ if storageContext="Filesystem". If you don't need a greater control on the storage structure all files will be stored directly in the root folders (flat structure). Otherwise you may use the content type based subfolder settings (config file) or the objectContext/uploadContext parameters sent with each client side request, which altogether support a very complex storage structure. #####Attributes * **filesRoot**: Root upload folder. If the value starts with "~/" (e.g. ~/files) the path is relative to the web root, otherwise set an absolute local path (e.g. d:/files) [Default: "~/Files"]. * **objectsRoot**: Subfolder within the filesRoot (e.g. "uploads"). Set it to objectsRoot="" if you do not need a subfolder [Default: ""]. * **usersRoot**: Special subfolder within the filesRoot to store user related files like photos etc. Set it to usersRoot="" if you do not need this subfolder [Default: ""]. * **copiesRoot**: Root of a folder where Backload stores a copy of an uploaded file, if set to a none empty string, else no copies were stored. If the value is empty ("") not copies are stored. If the value starts with '~/' (e.g. ~/copies) the path is relative to the web root. if the value not starts with '~/' and it isn't an absolute local path, the value will be treated as a subfolder to filesRoot ('copies' -> ~/files/copies). Otherwise set an absolute local path (e.g. d:/backup) [Default: ""].
####database (configuration element) Database related settings if storageContext="Database". Backload. leverages your DBContext derived classes (Entity Framework). The component needs to know the related DBContext class, root entity set and primary keys. Backload. uses the same storage structure as the filesystem. So, if you setup content based subfolders, in a database context this will be the entities accessed with the help of navigation properties (for more information on this, see MSDN Entity Framework) [Enterprise]. #####Attributes * **assemblyName**: Name of the assembly where the DBContext class is defined. You can leave this an empty string, if it is defined in the executing assembly (caller of the Backload component library) [Default: ""]. * **dbContext**: Full qualified name of the DBContext derived class [Default: ""]. * **entitySetName**: Name of the root entity where the files will be stored directly or the navigation begins (with the help fo navigation properties) [Default: "Files"]. * **primaryKeyName**: Primary key(s) of the root entity (Seperate multiple key names by comma) [Default: "ID"].
####security (configuration element) Security related settings like authentication and authorization. Define if users must be authenticated or if there are roles-based restrictions. By default there are no restrictions. If you need a greater control, set up your own controller to receive the request, do the authentication/authorization and then call the Backload. handler [Pro/Enterprise]. #####Attributes * **allowAnonymous**: When set to "true", anyone is allowed, when "false" the user must be authenticated [Default: "true"]. * **allowedDownloadRoles**: By default there are no restrictions on who can download files by a GET request. You can change this by adding a comma seperated list of roles [Default: "*"]. * **allowedUploadRoles**: By default there are no restrictions on who can upload files whithin a POST/PUT request. You can change this by adding a comma seperated list of roles [Default: "*"]. * **allowedDeleteRoles**: By default there are no restrictions on who can delete files by a DELETE request. You can change this by adding a comma seperated list of roles [Default: "*"].
####images (configuration element) Backload. is able to resize and crop images when they are uploaded. These settings determine the max. width and height, canvas and canvas color (if a canvas is used) and several resize options. The image can also be converted to a new target type (e.g. tiff to png). #####Attributes * **width**: Width or max width (depends on resizeMode) of the resulting image [images range: 20-5000, Default: "1024"; thumbnails range: 20-500, Default: "80"] * **height**: Height or max height (depends on resizeMode) of the resulting image [images range: 20-5000, Default: "768"]. * **dpi**: Resolution of the resulting image (dots per inch) [Range: 72-600, Default: "96"]. * **canvasColor**: Background color of the canvas. Only used when resize mode is fit and the image ratio of the source and target image differ. You can also use argb (rgb with alpha channel, e.g. background: `#00ffffff` (transparent), `#80ffffff` (white, 50% transparency), `#ffffffff` (white, opaque)) [Default: `#ffffff`]. * **forceImageType**: By default the image type of the original image keeps untouched. Set this attribute to an output image content type, so stored images will always have the same type (e.g. image/png or image/jpeg [Defailt: none]):
_none_: Use the original image type.
_image/png_: Files with .png (protable network graphics) extension.
_image/jpeg_: Files with .jpeg or .jpg extension.
_image/tiff_: Files with .tif or .tiff extension.
_image/gif_: Files with .gif extension.
_image/bmp_: Microsoft bitmap format * **resizeMode**: The resizeMode enumeration determines how the image should be resized [Default: "none"]:
_none_: Keep original image, no resizing or cropping.
_ratio_: No canvas, preserves ratio, width and height are max sizes.
_fit_: Fit into canvas, preserves ratio, centered on canvas.
_place_: If the source image is bigger than the canvas same as fit. If it's smaller, it'll be placed in the center of the canvas without resizing.
_crop_: Placed on the canvas, cropped if neccessary with center of the original image.
####thumbnails (configuration element) The Backload. component creates thumbnails for each incoming file. If the file is an image, a preview thumbnail is created, if it's not an image a thumbnail of the file type is stored (See also [contentTypes configuration element](Configuration#contentTypes-configuration-element)) in a subfolder (default: "_thumbs"). These settings determine the max. width and height, canvas and canvas color (if a canvas is used) and several resize options. #####Attributes * **path**: Subfolder name within the folder where the main file is stored [Default: "_thumbs"]. * **width**: Width or max width (depends on resizeMode) of the resulting thumbnail [Range: 20-500, Default: "80"]. * **height**: Height or max height (depends on resizeMode) of the resulting thumbnail [Range: 20-500, Default: "60"]. * **dpi**: Resolution of the resulting thumbnail (dots per inch) [Range: 72-600, Default: "96"]. * **canvasColor**: Background color of the canvas. Only used when resize mode is fit and the image ratio of the source and target image differ. You can also use argb (rgb with alpha channel, e.g. background: #00ffffff (transparent), #80ffffff (white, 50% transparency), #ffffffff (white, opaque)) [Default: #ffffff]. * **imageType**: Thumnails will all have the same image type in order the upload handler can find and return the correct thumbnail path [Default: "image/png"]. * **resizeMode**: The resizeMode enumeration determines how the image should be resized [Default: "none"]:
_none_: Keep original image, no resizing or cropping.
_ratio_: No canvas, preserves ratio, width and height are max sizes.
_fit_: Fit into canvas, preserves ratio, centered on canvas.
_place_: If the source image is bigger than the canvas same as fit. If it's smaller, it'll be placed in the center of the canvas without resizing.
_crop_: Placed on canvas, cropped if neccessary with center of the original image.
####clientFiles (configuration element) If the bundeling feature of the Backload. component is used (see [Example 01](Example-01)), set the appropriate client files folders here. #####Attributes * **scripts**: Scripts folder [Default: "~/Scripts/FileUpload/"]. * **styles**: Styles folder [Default: "~/Content/FileUpload/css/"].
####contentTypes (configuration element) ContentTypes serves two purposes: First, it is used to send an appropriate thumbnail of the file type back to the browser if it is not an image. Second: On uploads you can define a subfolder for a content-type that matches a regular expression you define, in order to store any content of this type in a related subfolder (Examples: Store all pdf files in a "pdfs" subfolder, store all images of an arbitrary type in an "img" subfolder, store all songs and movies in an "multimedia" subfolder). ContentTypes is build as a collection of contentType elements, and supports adding new alements, removing an element and clearing the whole collection. The Backload component has some predefined content types already included that can handle common file types (see list below). If you need a different handling of those predefined types, just remove this entry by its name and add your own definition as shown in the [configuration example](Configuration#configuration-example) above [Enterprise].

#####Attributes

  • thumbnailPath: Path to the content-types thumbnail folder (contains different resolutions) [Default: "~/Content/FileUpload/content-types"].
  • thumbnailSize: This entry points to an existing subfolder within the path where the thumbnail image for a specific content type is stored ("thumbnailPath"). Content type thumbnails will not be resized with one exception: You explicitely set useThumbnailCanvas="true" and the content type based thumbnail is bigger than canvas size (resizeMode "place" is used) [Default: "64"].
  • useThumbnailCanvas: Uses the thumbnail canvas (width, height, canvasColor) and places the content type specific thumbnail in the center of it [Default: "true"].

#####Clear the collection: Use <clear />as a sub element of the contentTypes element.

#####Remove a predefined type from the collection: Use <remove name="(name)" />where (name) is the name of a predifined contentType element (see below).

#####Add a new content type to the collection: Use <Add name="(name)" ... /> with the following attributes:

  • name: Unique name of the new entry.
  • extFragment: Complete or fragment of the file extension as RegEx string (e.g. .mp finds .mp3, .mp4, .mpeg, etc). Leave it blank, to skip this test.
  • typeFragment: Complete or fragment of the content-type as RegEx string (e.g. "mpeg" audio/mpeg, video/mpeg, etc). Leave it blank, to skip this test. Content-types matches are preferred over extension matches.
  • thumbnail: Name of the thumbnail image within the content-types thumbnail folder (see thumbnailPath). Special handling of image types: Leave it blank, to send a preview of the uploaded image back, or set a thumbnail if you do not want to return a preview and want to use a static image instead.
  • subfolder: Subfolder of the current upload folder. Has to be set only if files of this content-type should be stored seperatly from other types (e.g. "movies"). [Default: ""].

#####Predifined types This is a list of predifined content-types. Subfolder attribute is always empty (""). * _Adobe PDF_: Name: "_AdobePDFFile", extFragment: ".pdf", typeFragment: "application/pdf", thumbnail: "PDF.png". * _MS Excel -2003_: Name: "_MSExcel2003", extFragment: ".xl", typeFragment: "application/vnd.ms-excel", thumbnail: "Excel.png". * _MS Excel 2007-2012_: Name: "_MSExcel2012", extFragment: ".xl", typeFragment: "spreadsheetml", thumbnail: "Excel.png". * _MS Powepoint -2003_: Name: "_MSPowerpoint2003", extFragment: ".pp", typeFragment: "application/vnd.ms-powerpoint", thumbnail: "Powerpoint.png". * _MS Powepoint 2007-2012_: Name: "_MSPowerpoint2012", extFragment: ".pp", typeFragment: "presentationml", thumbnail: "Powerpoint.png". * _MS Word -2003_: Name: "_MSWord2003", extFragment: ".do", typeFragment: "application/msword", thumbnail: "Word.png". * _MS Word 2007-2012_: Name: "_MSWord2012", extFragment: ".do", typeFragment: "wordprocessingml", thumbnail: "Word.png". * _OpenOffice_: Name: "_OpenOfficeWriter", extFragment: ".od", typeFragment: "opendocument", thumbnail: "OpenOffice-Writer.png". * _Text file_: Name: "_TextFile", extFragment: ".txt", typeFragment: "text/plain", thumbnail: "Text.png".

License

Backload. (Standard version): Copyright 2013, Steffen Habermehl, License (Standard version): MIT license
Professional and Enterprise (source code) version are available under a commercial license.
Follow us on Twitter: @Backload_MVC

Add a custom footer
Add a custom sidebar
Clone this wiki locally