Click or drag to resize

IDocumentHandler Interface

Represents an object for handling of the input files in DocumentViewer. Implement this interface to provide a custom way of loading the input files.

Namespace:  GleamTech.DocumentUltimate.AspNet
Assembly:  GleamTech.DocumentUltimate (in GleamTech.DocumentUltimate.dll) Version: 5.9.6
Syntax
public interface IDocumentHandler

The IDocumentHandler type exposes the following members.

Methods
  NameDescription
Public methodGetInfo
Gets the required information which corresponds to the current input file. This method will be called every time DocumentViewer requests a document. The cache key and document format will be determined according to the info you return here. The returned UniqueIddetermines the cache key, so when uniqueId is changed it's considered a different file.
Public methodOpenRead
Opens a readable stream which corresponds to the current input file. This method will be called only when original input document is required to be read by the DocumentViewer, for example if DocumentViewer already did the required conversions and cached the results, it will not be called.
Top
Examples

How to implement IDocumentHandler interface:

public class CustomDocumentHandler : IDocumentHandler
{
    public DocumentInfo GetInfo(string inputFile, DocumentHandlerParameters handlerParameters)
    {
        // Return info here which corresponds to identifier
        // passed in inputFile parameter.
        // In this example, inputFile parameter will be "InputFile.docx".
        // This method will be called every time DocumentViewer requests a document.
        // The cache key and document format will be determined according to the info you return here.

        // Either provide a file name with extension
        // uniqueId: determines the cache key, so when uniqueId is changed it's considered a different file.
        // fileName: can be the inputFile or a value calculated/constructed via identifier in inputFile.
        return new DocumentInfo(uniqueId, fileName);

        // Or specify an explicit document format if you don't have a file name
        //return new DocumentInfo(uniqueId, null, DocumentFormat.Docx);

        // which can also be written as
        //return new DocumentInfo(uniqueId, format: DocumentFormat.Docx);
    }

    public StreamResult OpenRead(string inputFile, InputOptions inputOptions, DocumentHandlerParameters handlerParameters)
    {
        // Open a readable stream here which corresponds to identifier
        // passed in inputFile parameter.
        // In this example, inputFile parameter will be "InputFile.docx".
        // The input file will be read from this stream.
        // This method will be called only when original input document is required, 
        // for example if DocumentViewer already did the required conversions and cached the results, 
        // it will not be called.

        return new StreamResult(stream);
    }
}
// This loads the document with passed identifier via CustomDocumentHandler
documentViewer.DocumentHandlerType = typeof(CustomDocumentHandler);
documentViewer.Document = "InputFile.docx"; // a file path or identifier

Sample IDocumentHandler implementation for loading documents from a database:

// This is a sample IDocumentHandler implementation for loading a document from database.
// You can instruct DocumentViewer to use this handler by setting DocumentViewer.DocumentHandlerType
// property to type of this class, i.e. typeof(DbDocumentHandler)
// This sample demonstrates raw db access with System.Data objects
// but you can use any type of db access (e.g. Entity Framework), the idea is same.
public class DbDocumentHandler : IDocumentHandler
{

    // Get the document information required for the current input file.
    // This is called for determining the cache key and document format whenever 
    // DocumentViewer requests a document.
    // 
    // inputFile parameter will be the value that was set in DocumentViewer.Document property, i.e.
    // the input file that was requested to be loaded in DocumentViewer
    // 
    // Return a DocumentInfo instance initialized with required information from this method.
    public DocumentInfo GetInfo(string inputFile, DocumentHandlerParameters handlerParameters)
    {
        var fileId = inputFile;
        string fileName;

        using (var connection = new SqlConnection("CONNECTION STRING"))
        {
            connection.Open();

            var sql = "SELECT FileName FROM FileTable WHERE FileId=" + fileId;
            using (var command = new SqlCommand(sql, connection))
            using (var reader = command.ExecuteReader())
            {
                if (!reader.Read())
                    throw new Exception("File not found");

                // read the file name from the selected row (first column in above query)
                fileName = reader.GetString(0);
            }
        }

        return new DocumentInfo(
            // uniqueId parameter (required):
            // The unique identifier that will be used for generating the cache key for this document.
            // For instance, it can be an ID from your database table or a simple file name; 
            // you just need to make sure this ID varies for each different document so that they are cached correctly.
            // For example for files on disk,
            // we internally use a string combination of file extension, file size and file date for uniquely
            // identifying them, this way cache collisions do not occur and we can resuse the cached file
            // even if the file name before extension is changed (because it's still the same document).                
            fileId,

            // fileName parameter (optional but recommended):
            // The file name which will be used for display purposes such as when downloading the document
            // within DocumentViewer> or for the subfolder name prefix in cache folder. 
            // It will also be used to determine the document format from extension if format 
            // parameter is not specified. If not specified or empty, uniqueId will be used 
            // as the file name.                    
            fileName
        );
    }

    // Open a readable stream for the current input file.
    // This is called only when necessary, i.e first time the document is loaded. For consecutive views
    // as long as cached files are valid, it will not be called. This can be also called when "Download"
    // button is clicked to download the original document.
    // 
    // inputFile parameter will be the value that was set in DocumentViewer.Document property, i.e.
    // the input file that was requested to be loaded in DocumentViewer
    // 
    // inputOptions parameter will be determined according to the input document format
    // Usually you will not need to check this parameter as inputFile parameter should be sufficient
    // for you to locate and open a corresponding stream.
    // 
    // Return a StreamResult instance initialized with a readable System.IO.Stream object.
    public StreamResult OpenRead(string inputFile, InputOptions inputOptions, DocumentHandlerParameters handlerParameters)
    {
        var fileId = inputFile;
        byte[] fileBytes;

        using (var connection = new SqlConnection("CONNECTION STRING"))
        {
            connection.Open();

            var sql = "SELECT FileBytes FROM FileTable WHERE FileId=" + fileId;
            using (var command = new SqlCommand(sql))
            using (var reader = command.ExecuteReader())
            {
                if (!reader.Read())
                    throw new Exception("File not found");

                // read the file data from the selected row (first column in above query)
                fileBytes = (byte[])reader.GetValue(0);
            }
        }

        // We need to return a stream that has the file contents here.
        // As we don't have a stream but a byte array, we can wrap it with a MemoryStream.
        var stream = new MemoryStream(fileBytes);
        return new StreamResult(stream);
    }
}
// This loads the document with passed ID (176) from the database via DbDocumentHandler.
documentViewer.DocumentHandlerType = typeof(DbDocumentHandler);
documentViewer.Document = "176"; // a file path or identifier

Sample IDocumentHandler implementation for passing multiple parameters at once:

public class MultiParameterDocumentHandler : IDocumentHandler
{
    public DocumentInfo GetInfo(string inputFile, DocumentHandlerParameters handlerParameters)
    {
        // Get your parameters that were set in documentViewer.DocumentHandlerParameters property
        // The type for the generic Get<T> method should be the same as the set value's type.
        var parameter1 = handlerParameters.Get<string>("parameter1");
        var parameter2 = handlerParameters.Get<int>("parameter2");
        var parameter3 = handlerParameters.Get<string[]>("parameter3");

        // Do your thing with these parameters and construct and return your info

        return new DocumentInfo(uniqueId, fileName);
    }

    public StreamResult OpenRead(string inputFile, InputOptions inputOptions, DocumentHandlerParameters handlerParameters)
    {
        // Get your parameters that were set in documentViewer.DocumentHandlerParameters property
        // The type for the generic Get<T> method should be the same as the set value's type.
        var parameter1 = handlerParameters.Get<string>("parameter1");
        var parameter2 = handlerParameters.Get<int>("parameter2");
        var parameter3 = handlerParameters.Get<string[]>("parameter3");

        // Do your thing with these parameters and contruct and return your stream

        return new StreamResult(stream);
    }
}
documentViewer.DocumentHandlerType = typeof(MultiParameterDocumentHandler);

// When you need to pass custom parameters along with the input file to your handler implementation,
// use documentViewer.DocumentHandlerParameters property to set your parameters.
// These will be passed to the methods of your handler implementation:
documentViewer.DocumentHandlerParameters.Set("parameter1", "some string");
documentViewer.DocumentHandlerParameters.Set("parameter2", 45);
documentViewer.DocumentHandlerParameters.Set("parameter3", new[] { "a", "b", "c" });

documentViewer.Document = "InputFile.docx";
See Also