Basic Concept / Printing

Installation

Install TFORMer Designer (the graphical layout editor) and TFORMer SDK (the reporting and label printing core) using the setup applications. TFORMer SDK is available as DLL, as COM component, as .NET assembly, as JAVA class and as stand-alone application (TFPrint). Both the COM component and the .NET assembly of TFORMer SDK are registered automatically. The .NET assembly is automatically placed in the GAC and in the Bin directory of the installation folder. The Java package JTFORMer8.jar (which is compatible with the Java Runtime Edition - JRE version 1.5 or higher) is copied into the Bin directory: It includes all classes that you need to create a TFORMer application with the Java language.

Design a FormLayout

Use TFORMer Designer to create a FormLayout graphically. Most likely a FormLayout contains dynamic data which will be provided by your application during print-time (e.g. an article number for a product label or a ticket number for an e-ticket). TFORMer uses DataFields as place-holders for such dynamic data. These DataFields are declared as well as used within the FormLayout.

Check out the following paragraphs to learn how to print or export a FormLayout with data provided by your application!

Create a .NET Project

Create a new .NET based project. In Visual Studio right-click on your project in the Solution Explorer and select Add Reference. Open the .NET tab and select TFORMer 8 SDK. Alternatively open the Browse tab and select the TFORMer .NET assembly called TECIT.TFORMer.dll.

Add the namespace TECIT.TFORMer in each source file that uses TFORMer SDK:

using TECIT.TFORMer;

License and Initialize TFORMer SDK

Licensing is not required for evaluation purposes. For production, apply a license key to TFORMer SDK before using any other properties or methods of TFORMer. This needs to be done only once, for example when initializing the application.

  // License TFORMer SDK (the license key is only for demonstration purposes)
  TFORMer.License("John Doe", LicenseKind.Workstation, 1, "00000000000000000000000000000000"); 

Select the FormLayout to be Used

Printing is done with the help of a print Job. Create a Job and select the FormLayout by setting the appropriate properties.

  // Create a new Job instance
  Job printJob = new Job();
  // Select the stand-alone FormLayout
  printJob.RepositoryName = "C:/Documents and Settings/All Users/Application Data/TEC-IT/TFORMer/8/Examples/Command Line/ODBCReportPDF/ODBCReportPDF.tff";

Note:

TFORMer Designer supports so-called stand-alone FormLayouts (which are created by default by TFORMer Designer) and Repository based FormLayouts (which enable you to organize a large number of FormLayouts in a structured way). Check out Repository / FormLayout for details.

Whenever properties or methods are requesting input files (e.g. FormLayouts, or file-based DataSources like XML or CSV files), these may be passed as usual via the filename or by using BASE64 encoded strings. In addition, files and BASE64 strings may be zipped to save bandwidth. Refer to Passing Files for details.

Provide JobData

As mentioned above a FormLayout usually contains DataFields which are used as place holders for dynamic data. Before printing a FormLayout you need to provide data for these DataFields by assigning suitable JobData to the Job. Various methods are available for providing JobData.

Note:

The field names available in the JobData (e.g. the column names returned by a SQL-SELECT statement or the column names in a CSV file) must match the names of the DataFields used in a FormLayout. When using user-defined data sources (see user-defined data source below) the mapping between fields in the DataSource to DataFields in the FormLayout can be adjusted freely.

Provide JobData via Program Code

This is the most direct method to pass data to TFORMer SDK. In this case the names and values of the DataFields used in a FormLayout are provided directly. The example below sets the values for the DataFields ArticleNo, ArticleName and ArticlePrice.

  // Create a new JobData instance. 
  // Here we are using the JobDataRecordSet which accepts Records containing name/value pairs 
  JobDataRecordSet jobData = new JobDataRecordSet();

  // Create a new Record
  Record record = new Record();
  // Add some name/value pairs for the DataField values to the Record
  record.Data.Add("ArticleName", "Speaker System HF1");
  record.Data.Add("ArticleNo", "12001234");
  record.Data.Add("ArticlePrice", "498.98");
  // Add the Record to the JobData
  jobData.Records.Add(record);
 
  // Create a second Record
  record = new Record();
  // This Record should be printed two times
  record.NumberOfCopies = 2;
  record.Data.Add("ArticleName", "Record Box 12 CDs");
  record.Data.Add("ArticleNo", "12021231");
  record.Data.Add("ArticlePrice", "8.85");
  jobData.Records.Add(record);

  // Assign the JobData to the Job
  printJob.JobData = jobData;

Load JobData From CSV Files

See also JobDataCsv

  // Create a new JobData instance. 
  // Here we import a CSV and specify separator and qualifier character
  JobDataCsv jobData = new JobDataCsv("path/data.csv", ',', '"');  

  // Assign the JobData to the Job
  printJob.JobData = jobData; 

Load JobData From XML Files

See also JobDataXml

  // Create a new JobData instance. 
  // Here we import a XML file (must comply with the supported XML schemes)
  JobDataXml jobData = new JobDataXml("path/data.xml");

  // Assign the JobData to the Job
  printJob.JobData = jobData; 

Load JobData From a Database

See also JobDataOdbc

  // Create a new JobData instance
  // Here we import data from an ODBC connection using the specified SQL SELECT statement
  JobDataOdbc jobData = new JobDataOdbc (
    "DSN=TFORMer_Sample",
    "", // Username
    "", // Password
    "SELECT * FROM tbl_Example"
  );

  // Assign the JobData to the Job
  printJob.JobData = jobData;

Load JobData From a User-Defined Data Source

See also JobDataDataSource

Last but not least TFORMer Designer offers the possibility to specify a "user-defined" DataSource as part of a FormLayout. Such a DataSource defines how data is retrieved (e.g. from an ODBC database) and it specifies the mappings between fields in the DataSource and DataFields in the FormLayout. If you want to use such a user-defined DataSource for JobData retrieval, select the DataSource by name as shown below. Use optional DataSourceParameters to control certain aspects (like the filename, SQL SELECT statement or DSN) of the DataSource during runtime.

  // Create a new JobDataDataSource instance
  // The DataSource named myTextDataSource must be defined in the FormLayout or Repository
  JobDataDataSource jobData = new JobDataDataSource ("myTextDataSource");

  // Set the DataSourceParameter named parFile   
  jobData.ParameterValues.Add ("parFile", "/YourPath/InputData.txt");

  // Assign the JobData to the Job
  printJob.JobData = jobData;   

Generate Output

Print on a Printer

Use PrinterName to specify the target printer. Provide an empty string, if you want to send the output to the default printer.

  // Select the printer name on Windows or Linux (CUPS printer name), use null for the default printer
  printJob.PrinterName = null; 
  
  // Print
  printJob.Print(); 

Export as PDF, PostScript, HTML, ZPL-II or as an Image

Instead of printing on a printer, you can export the output as a PDF, PostScript, HTML, ASCII or image file. ZPL-II (the ZEBRA printer language) generation is supported too. Instead of setting a printer name, set the name and type of the output file.

  // Select PDF output to /temp/out.pdf 
  printJob.OutputName = "/temp/out.pdf";
  printJob.PrinterType = TECIT.TFORMer.PrinterType.PdfFile;
 
  // Generate PDF 
  printJob.Print();

Generate Output as an In-Memory Stream

Starting with TFORMer version 7 it is possible to generate the output as an in-memory stream. No output or temporary files are required, the performance for creating the output is dramatically improved. Currently PDF- and image-output (excluding multi-page TIFF) are generated completely in-memory. If the output results in a single stream (this is true for Postscript, PDF, multi-page TIFF and ZPL output) use PrintToStream. If the generated output results in several streams (e.g. generating multiple labels as single PNG images) use PrintToStreams.

Use a Single Stream

  // Select PDF output 
  printJob.PrinterType = PrinterType.PdfFile;

  // Generate output using the streaming API (no temporary files will be needed on the file-system)
  // For demonstration purposes we provide a FileStream, a PDF file named /temp/out.pdf will be generated
  // In real life you will most likely use the stream to generate the response for some web-client
  using (FileStream streamOut = new FileStream("/temp/out.pdf", FileMode.Create))
  {
    // Generate PDF 
    printJob.PrintToStream (streamOut);
  }

Use Multiple Streams

//-------------------------------------------------------------------------------------------
// Delegate to create a new stream 
// This delegate will be called for each requested stream before any output is generated
// You may use this delegate to open files or to reserve memory
//-------------------------------------------------------------------------------------------
Stream CreateStream (string sName)
{
  // For demonstration purposes we create a file stream
  Stream stream = new FileStream (sName, FileMode.Create);
  return stream;      
}

//-------------------------------------------------------------------------------------------
// Delegate to close a stream
// This delegate will be called for each requested stream if it is no longer used
// You may use this delegate for cleanup purposes
//-------------------------------------------------------------------------------------------
void CloseStream(Stream stream)
{
  stream.Close ();    
}

  // Generate a PNG image named StreamToFileExample.png
  // The provided OutputName is passed to CreateStream
  // If multiple pages are generated page numbers will get appended (e.g. StreamToFileExample_002.png)
  printJob.OutputName = "StreamToFileExample.png"; 
  printJob.PrinterType = PrinterType.ImagePng;

  // Generate output with the streaming API using the specified delegates
  printJob.PrintToStreams (CreateStream, CloseStream);

Clean Up

Although not required, you may call dispose.

  // Free resources used by TFORMer SDK
  printJob.Dispose ();
  // To invalid the object internally set the variable to null
  printJob = null;

More Information

• Job / JobData
• Repository / FormLayout
• Samples
• General Information

• Architecture
• Distribution & Deployment