Accusoft.FSInvoices1.Net - Updated
Template Provider
User Guide > How To > Perform Advanced Operations > Template Provider

A template provider is a class that implements the ITemplateProvider.

This provider performs the methods associated with getting and saving templates for the user application. These methods are:

GetTemplateIds Get a list of currently saved template identifiers.
GetTemplate Get a template associated with a specific template identifier.
GetTemplateImage Get a template image associated with a specific template identifier.
SaveTemplate Save a template with a given identifier.
SaveTemplateImage Save a template image with a given identifier.
SaveTemplateWithImage Save a template and image with a given identifier.
CreateTemplateId Create a new template identifier. This identifier will be used for saving a new template and template image.

The template provider is called at two different times during processing:

A file based template provider is included with the API, see FileTemplateProvider.

Setting the template provider into the processor class is done as follows:

Example
Copy Code
// Setup the template provider
ITemplateProvider templateProvider = new TemplateProvider("Templates");
invoiceProcessor.TemplateProvider = templateProvider;

An example of a file based implementation of a template provider is provided below.

Example
Copy Code
/// <summary>
/// Implement an ITemplateProvider that uses the file system.
/// The templates will be read/written from the [templateRooDirectory]\[Company Name]\[Vendor Name]
/// Template are Serialized/Deserialized using DataContractSerialization.
/// Note: The template Id is the file name without a file extension or path.
/// </summary>
public class TemplateProvider : ITemplateProvider
{
    /// <summary>
    /// Root path to the templates
    /// </summary>
    private string templateRootDirectory;
 
    /// <summary>
    /// Extension added to the template file
    /// </summary>
    private string templateExtension = ".template";
    /// <summary>
    /// Extension added to the template reference image
    /// </summary>
    private string templateImageExtension = ".tImage";
 
    /// <summary>
    /// Create an instance of the template provider with the given directory.
    /// </summary>
    /// <param name="templateRootDirectory"></param>
    public TemplateProvider(string templateRootDirectory)
    {
        this.templateRootDirectory = templateRootDirectory;
        // Create the directory if needed
        if (System.IO.Directory.Exists(templateRootDirectory) == false)
        {
            System.IO.Directory.CreateDirectory(templateRootDirectory);
        }
    }
 
 
    /// <summary>
    /// Build a path to the template files for a given company and vendor
    /// </summary>
    /// <param name="company">Company data associated with the templates</param>
    /// <param name="vendor">Vendor data associated with the templates</param>
    /// <returns>A path that combines the root, comapany name and vendor name</returns>
    private string BuildTemplateDirectoryPath(ICompanyData company, IVendor vendor)
    {
        string path = templateRootDirectory;
        if (company != null && string.IsNullOrWhiteSpace(company.CompanyName) == false)
        {
            path += path + System.IO.Path.DirectorySeparatorChar + company.CompanyName;
        }
        else
        {
            path += path + System.IO.Path.DirectorySeparatorChar + "UnknownCompany";
        }
        if (vendor != null && string.IsNullOrWhiteSpace(vendor.Name) == false)
        {
            path += path + System.IO.Path.DirectorySeparatorChar + vendor.Name;
        }
        else
        {
            path += path + System.IO.Path.DirectorySeparatorChar + "UnknownVendor";
        }
        return path;
    }
 
 
    /// <summary>
    /// Build a file path to a template file
    /// </summary>
    /// <param name="company">Company data associated with the template</param>
    /// <param name="vendor">Vendor data assoicated with the template </param>
    /// <param name="templateFile">Template file name, with extension</param>
    /// <returns>Path to the template file.</returns>
    private string BuildTemplateFilePath(ICompanyData company, IVendor vendor, string templateFile)
    {
        return BuildTemplateDirectoryPath(company, vendor)+System.IO.Path.DirectorySeparatorChar+templateFile;
    }
 
    /// <summary>
    /// Check if the path exists, if not create it
    /// </summary>
    /// <param name="path">Path to create</param>
    private static void CheckAndCreateDirectory(string path)
    {
        if (string.IsNullOrEmpty(path) == false && System.IO.Directory.Exists(path) == false)
        {
            System.IO.Directory.CreateDirectory(path);
        }
    }
 
 
    /// <summary>
    /// Create a unique template Id for a template.  This is call when a new template is to be created.
    /// This implementation creates a template id using a new guid.
    /// </summary>
    /// <param name="company">Company data assoicated with the template.</param>
    /// <param name="vendor">Vendor data associated with the template.</param>
    /// <returns>A unique identifer for a template</returns>
    public string CreateUniqueTemplateId(ICompanyData company, IVendor vendor)
    {
        // Return a guid as a template id
        return Guid.NewGuid().ToString();
    }
 
    /// <summary>
    /// Get a template given a template Id
    /// </summary>
    /// <param name="company">Company associated with templateId</param>
    /// <param name="vendor">Vendor associated with templateId</param>
    /// <param name="templateId">Id of template to retrieve</param>
    /// <returns>Retrieved template; null if none found</returns>
    public TemplatePage GetTemplate(ICompanyData company, IVendor vendor, string templateId)
    {
        TemplatePage templatePage = null;
        string filePath = BuildTemplateFilePath(company, vendor, templateId + templateExtension);
        if (System.IO.File.Exists(filePath))
        {
            DataContractSerializer serializer = new DataContractSerializer(typeof(TemplatePage));
            using (System.IO.FileStream stream =
  new System.IO.FileStream(filePath,
  System.IO.FileMode.Open,
  System.IO.FileAccess.Read))
            {
                templatePage = (TemplatePage)serializer.ReadObject(stream);
            }
        }
        return templatePage;
           
    }
 
    /// <summary>
    /// Get Ids of templates matching a given company and vendor
    /// </summary>
    /// <param name="company">Company associated with templateId</param>
    /// <param name="vendor">Vendor associated with templateId</param>
    /// <returns>Ids of matched templates</returns>
    public List<string> GetTemplateIds(ICompanyData company, IVendor vendor)
    {
        List<string> templateIds = new List<string>();
        string templateDirectoryPath = BuildTemplateDirectoryPath(company, vendor);
        if (System.IO.Directory.Exists(templateDirectoryPath))
        {
            System.IO.DirectoryInfo dirInfo = new System.IO.DirectoryInfo(templateDirectoryPath);
            if (dirInfo != null)
            {
                System.IO.FileInfo[] files = dirInfo.GetFiles("*" + templateExtension);
                foreach (var file in files)
                {
                    templateIds.Add(System.IO.Path.GetFileNameWithoutExtension(file.Name));
                }
            }
        }
        return templateIds;
    }
 
    /// <summary>
    /// Get template image given a template Id
    /// </summary>
    /// <param name="company">Company associated with templateId</param>
    /// <param name="vendor">Vendor associated with templateId</param>
    /// <param name="templateId">Id of template associated with image</param>
    /// <returns>Stream for retrieved image; null if none found</returns>
    public System.IO.Stream GetTemplateImage(ICompanyData company, IVendor vendor, string templateId)
    {
        string templateImagePath = BuildTemplateFilePath(company, vendor, templateId + templateImageExtension);
        if (System.IO.File.Exists(templateImagePath))
        {
            return new System.IO.FileStream(templateImagePath, System.IO.FileMode.Open, System.IO.FileAccess.Read);
        }
        else
        {
            return null;
        }
    }
 
    /// <summary>
    /// Get template image given a template Id
    /// </summary>
    /// <param name="company">Company associated with templateId</param>
    /// <param name="vendor">Vendor associated with templateId</param>
    /// <param name="templateId">Id of template associated with image</param>
    /// <returns>Stream for retrieved image; null if none found</returns>
    public void SaveTemplate(ICompanyData company, IVendor vendor, TemplatePage pageTemplate)
    {
        if (pageTemplate != null)
        {
            if ( string.IsNullOrWhiteSpace(pageTemplate.TemplateId) == true)
            {
                pageTemplate.TemplateId = CreateUniqueTemplateId(company, vendor);
            }
            CheckAndCreateDirectory(BuildTemplateDirectoryPath(company, vendor));
            string templatePath = BuildTemplateFilePath(company, vendor, pageTemplate.TemplateId);
            DataContractSerializer serializer = new DataContractSerializer(typeof(TemplatePage));
            using (System.IO.FileStream fs = new System.IO.FileStream(templatePath, System.IO.FileMode.Create, System.IO.FileAccess.Write))
            {
                serializer.WriteObject(fs, pageTemplate);                   
            }
        }
    }
 
    /// <summary>
    /// Save a template
    /// </summary>
    /// <param name="company">Company template is associated with</param>
    /// <param name="vendor">Vendor template is associated with</param>
    /// <param name="pageTemplate">Page template</param>
    public void SaveTemplateImage(ICompanyData company, IVendor vendor, string templateId, System.IO.Stream imageStream)
    {
        CheckAndCreateDirectory(BuildTemplateDirectoryPath(company, vendor));
        string templateImagePath = BuildTemplateFilePath(company, vendor, templateId + templateImageExtension);
        using (var file = new System.IO.FileStream(templateImagePath, System.IO.FileMode.Create, System.IO.FileAccess.Write))
        {
            file.Position = 0;
            imageStream.Position = 0;
            imageStream.CopyTo(file);
        }
    }
 
    /// <summary>
    /// Save a template image
    /// </summary>
    /// <param name="company">Company associated with templateId</param>
    /// <param name="vendor">Vendor associated with templateId</param>
    /// <param name="templateId">Id of template associated with image being saved</param>
    /// <param name="imageStream">Stream to save with</param>
    public void SaveTemplateWithImage(ICompanyData company, IVendor vendor, TemplatePage pageTemplate, System.IO.Stream imageStream)
    {
        SaveTemplate(company, vendor, pageTemplate);
        SaveTemplateImage(company,vendor, pageTemplate.TemplateId, imageStream);
    }
}