ASP.NET uploader configuring

Intro

This document contains all steps to install and configure uploader for any of CKEditor or TinyMCE DOKSoft Upload plugins such are CKEditor Quick Image Upload, CKEditor Easy File Upload, TinyMCE Image or File Upload plugins or even Bootstrap Image Gallery plugin. All these plugins can use ASP.NET uploader if you are using server environment from Microsoft.

Note. DOKSoft is now JS+ and we changed all plugins prefixes (i. e. doksoft_image became jsplus_image). But server side uploader names were keeped unmodified. So all client keys (jsplus_uploader_url) are now with prefix "jsplus", but all .NET server configuration including paths are still with "doksoft" prefix - please keep it in mind when editing configuration. This manual is updated to show you correct preficies.

Installation

The installation of ASP.NET uploader is pretty simple: you need to extract the file DoksoftUploaderLibrary.dll file into your bin directory in the root of your server.

The root of your server is the directory where all files of your website are placed. Its name is wwwroot and on default IIS installations and the full path of bin directory in this case will be C:\inetpub\wwwroot\bin.

Or if you do not want to add it to standard bin directroy by some reasons, you can put this .dll file anywhere and register it in your IIS as native module. Make this steps to do this:

1. Put the file anywhere.
2. Open IIS Manager.
3. Click on the tree's root element (server node).
4. Click "Configure native modules" at the right panel.
5. Click "Register".
6. Type a name for the modele and specify file's path.
7. Click "OK".

This screenshot will demonstate you the steps described above:

Configuration

Next step is configuring the uploader. You need to map installed library to needed URL and configure directory where the files will be placed.

Configuring of the uploader can be made by editing of standard IIS configuration file Web.config placed in wwwroot directory. See sample Web.config from the archive with purchased plugins to copy values from. The sample config file contains configuration which can be used on clean installation (sample CKEditor/TinyMCE page without anything else).

Well, let's see the parameters available for you.

URL of uploader

At the bottom of the file you can see the string:

<add name="UploaderHandler" verb="*" path="/doksoft_uploader/uploader" type="DoksoftUploaderLibrary.UploaderHandler, DoksoftUploaderLibrary"/>

Change path parameter as you want to tell the IIS server what the URL to map to uploader library handler.
The same value MUST be specified in your client part of the plugins. For CKEditor add this line into your config.js:

config.jsplus_uploader_url = "/doksoft_uploader/uploader";

For TinyMCE use parameter in your initialization script:

jsplus_uploader_url: "/doksoft_uploader/uploader";

Directory for uploads

To set upload directory for your ASP.NET uploader just change doksoft_uploader_base_dir parameter in your Web.config:

<add key="doksoft_uploader_base_dir" value="/path/to/ckeditor/plugins/doksoft_uploader/userfiles/" />

Of course this may be any directory which is writable by IIS.

The path is defined from the directory root. So for example if you want to upload files into C:\inetpub\wwwroot\uploads\images you need to use /uploads/images as path's value.

Uploaded files URL mapping

Most of times you do not need to configure it. But if you have very special configuration (for example your /ckeditor/doksoft_uploader/userfiles/ directory can be accessed by /Public/files/ alias) you need to tell to the uploader about it.

Use doksoft_uploader_base_url parameter for this. By default it equals to doksoft_uploader_base_dir parameter and defines a prefix which will be used before filename when the tag is inserted into CKEditor or TinyMCE document. Uncomment it to override.

Here are examples of this parameter's values:

/Public/files (will be linked to http://your-domain.com/Public/files)

http://your-website.com/ckeditor/uploads (absolute path)

Note that this parameter will not create new URL alias, it just allows uploader to use your existing one. If you need to create this alias please use standard IIS tools for doing this.

Filename format

By default uploader tries to place the file with original filename to the server. When it is unable (another file with this name already exists) uploader will add "_x" suffix to file where "x" is the number from 1 and upper to make filename unique.

You can define your own filename format. It will not affect to extension, just to filename part.

Here is the sample of how you can set the filename format:

<add key="doksoft_uploader_filename_format" value="{ORIGINAL_NAME}-time_{DATE:yyyy-MM-dd}{NUMBER:_}" />

This example contains fill list of substitutable strings:

ORIGINAL_NAME - original name of uploaded file

DATE - current date (its format is defined after ":" symbol), see Microsoft date format documentation to construct date format

NUMBER - incremental number to resolve uniqueness problems. Please always use it. After ":" symbol you can set the delimeter between filename and number ("_" in this example).

Any of this substitution fragments can be used only once.

Other parameters

The other handy parameters are also exist in sample Web.config file. With their help you can limit maximum files' and images' sizes (in bytes), resolution limits (in pixels) and allowed extensions (* or list of extentions with "," delimiter). They can be understood without additional explanation.