#######################
Creating a PDF Document
#######################

Introduction
------------

PDF documents can be defined with a wide variety of page layouts.
Here is a description of the different techniques that Advanced Publishing can support.
The application sample DemoFunctionalities provided in the Advanced Publishing package illustrates many of these page layout definitions.

* Simple page layouts can be defined 'from scratch' entirely using Advanced Publishing functions to create and position different entities such as texts, tables, images, and 3D.
* Some scenarios might require complex page layout and content generated from an external solution.
  For example, some customers might use Microsoft Excel to generate a PDF with a complex spreadsheet automatically exploded on several pages, or dedicated solutions can generate a rich dashboard and reports with interactive graphs.
  In this situation, the external solution primarily creates the PDF, then Advanced Publishing is used to open it and enrich it with 3D and other content.
* A PDF page layout can also be defined using PDF Templates.
  The idea of a PDF Template is to enable the application user to easily customize the PDF page layout, for example by setting a company logo, a specific color scheme, or legal statements.
  A PDF Template is defined using Adobe Acrobat application and the Acrobat Forms tool.
  This tool is an interactive tool to create and position some widget fields on the PDF page.
  PDF Templates should be provided with the customer application, so that the application user can customize the template if needed.
  Later, the application uses Advanced Publishing to populate the PDF Template with live data and generate the final PDF.
  Sample PDF Templates are provided with the Advanced Publishing package and can be a good inspiration for customers to build their own template files.
* Also, widgets might be used in scenarios that require the PDF page to have some interactive fields.
  The widget fields must be defined using Acrobat Forms tool or with Advanced Publishing functions, and can be populated using Advanced Publishing functions.
  These widget fields are for example list boxes, combo boxes, and buttons and have actions associated that enable an interaction of the field with the 3D or other part of the PDF.
  For example, selecting an item in a list could populate other fields on the page, or pushing a button could print or send the PDF file to another person.


Creating a PDF From Scratch
---------------------------

Using Advanced Publishing functions, the definition of a PDF document can start by creating an empty document (``A3DPDFDocumentCreateEmpty``), or by using an existing PDF file (``A3DPDFDocumentCreateFromPDFFile``).

Pages can be appended to any document with ``A3DPDFDocumentAppendNewPage2`` or ``A3DPDFDocumentAppendPageFromPDFFileEx`` (this one should be preferred to import pages from PDF files that contain form fields). A page is determined with a predefined set of formats (A4, letter ...) and an orientation (portrait / landscape). The unit of a page is a point. A point is approximately 1/72 inch.

Pages objects are returned by append functions or can be accessed at any time using ``A3DPDFDocumentGetNumberPages`` and ``A3DPDFDocumentGetPage`` functions.

.. code-block:: c

   A3DPDFDocument* pDoc = NULL;
   iRet = A3DPDFDocumentCreateEmpty(&pDoc);
   A3DPDFPageData2 sPageData = A3D_MAKE_DATA(A3DPDFPageData2);
   sPageData.m_ePageOrientation = kA3DPDFPageLandscape;
   sPageData.m_ePageSize = kA3DPDFPageLetter;  // standard letter format: 612 x 792
   A3DPDFPage* pPage = NULL;
   iRet = A3DPDFDocumentAppendNewPage2(pDoc, &sPageData, &pPage);

Or

.. code-block:: c

   A3DPDFPage* pPage = NULL;
   A3DInt32 indexpage, nbpages;
   iRet = A3DPDFDocumentAppendPageFromPDFFileEx(pDoc, "c:\\temp\\mypdf.pdf", false, &pPage);
   iRet = A3DPDFDocumentGetNumberPages(pDoc, &nbpages);
   for (indexpage = 0; indexpage < nbpages; indexpage++)
   {
       iRet = A3DPDFDocumentGetPage(pDoc, indexpage, &pPage);
   }

Once a page is accessed, functions can be used to create and position entities such as 3D, text, image, scroll table, or view carousel. See insertion functions described in section :doc:`Page layout <inserting_data>`.

Using Template
--------------

In a template scenario, an existing PDF file is opened with ``A3DPDFDocumentAppendPageFromPDFFileEx``.

The functions ``A3DPDFPageGetFields`` and ``A3DPDFFieldGetInformation`` can be used to get information on the fields in a page. Ultimately these functions can be useful to dynamically generate reports with only a sub-set of fields selected beyond a large possible list (the application supports hundreds of type of fields, but the end-user only selects a limited number of them to figure in the report).

Once the page is accessed, widget fields on pages can be populated using the field functions described in :doc:`Populating fields <populating_fields>` section.
