eDocBuilder iFrame Interface (UPDATED 2020)

Introduction

eDocBuilder IFRAME integration is an easy method of integrating the eDocBuilder client into your e-commerce application. As the name suggests, you can embed the client into your own page by adding an IFRAME to the HTML. Parameters from your application to the client are passed through the URL of the IFRAME's SRC attribute, and return information from the client after it is finished is passed back through a postback URL.

The IFRAME url parameters allow for some customization of the client's appearance and behavior, you can pass your own CSS stylesheet (with limitations), change the names on the completion buttons, adjust the available zoom levels for the preview.

The parameters in the URL are in the well-known querystring format, where a question mark follows the page URL and URLencoded parameters immediately follow, in a NAME=VALUE format. Upon completion of the customization session, the end user will either click a Save button or a Cancel button, and the client will send a FORM POST to the postback URL with the session ID, friendly name for the session, exit status, and the values of all user choices.

If you are not sure if you have eDocBuilder API access for your subscription, please check Can I use iFrame or SOAP API access with my eDocBuilder account?

User Interface

eDocBuilder templates can be presented to the end user in two distinct user interfaces. The iFrame client will decide, based on the template settings, which user interface to display.

The standard forms based approach provides a list of prompts and response controls for the user to enter data into. The document may be previewed by enter data and clicking a button to update the preview. The design itself may not be altered by the end user.

The interactive designer is an interface that allows the end user to modify the design by directly interacting with text and image elements on the design surface. Based on template settings, the user can have a range of control over text and image elements.

Because the purposes of each mode are unique, not all capabilities are available to both.

URL Parameters

• Required = no
• Type = string
• UI = Interactive and Forms
• Example = addToCartButton=Add To Cart
• Purpose = Text label for the addtoCart button (only used for a new session)

---

• Required = no
• Type = boolean
• UI = Forms only
• Example = addToCartCausesUpdate=true
• Purpose = Normally the user must press the Update Cart button to send field changes to the server. When this is true, the Add To Cart button will do an Update Cart too. Prevents changes from being lost because the user had forgotten to press Update Cart before finishing.

---

• Required = no
• Type = boolean
• UI = Interactive only
• Example = saveForLater=true
• Purpose = Saves the session without accepting it. Helpful for supporting a save-for-later option.

---

• Depreciated

---

• Depreciated

---

• Required = no
• Type = boolean
• UI = Interactive and Forms
• Example = approveWhenDone=true
• Purpose = Marks the session as closed and approved immediately when the user presses the Add To Cart button. Normally the site that invokes iFrame would need to call the API method approveDocSession, and would do that when the user actually checks out their cart; this makes it unnecessary to do that.

---

• Required = no
• Type = URL
• UI = Interactive and Forms
• Example = assetsurl=http://www.ysite.com/files/myassets.json
• Purpose = Link to JSON file containing asset images to build a categorized asset list in the image library. See below for details.

---

• Required = no
• Type = string
• UI = Forms only
• Example = assetsurl=http://www.ysite.com/files/myassets.json
• Purpose = Text label for the cancel button (used for both kinds of session)

---

• Depreciated

---

• Required = yes
• Type = GUID string
• UI = Interactive and Forms
• Example = --
• Purpose = Identifies which template is used for the document session.

---

• Required = yes
• Type = GUID string
• UI = Interactive and Forms
• Example = --
• Purpose = Password for the template

---

• Required = no
• Type = GUID string
• UI = Interactive and Forms
• Example = --
• Purpose = When re-editing an existing session this identifies the session

---

• Depreciated

---

• Depreciated

---

• Required = no
• Type = string
• UI = Forms only
• Example = Tiny=100,Normal=300,Huge=1000
• Purpose = Comma delimited name- value pairs giving the allowed preview image sizes

---

• Depreciated

---

• Required = yes
• Type = URL
• UI = Interactive and Forms
• Example = --
• Purpose = Page that will receive the final postback with the session results

---

• Required = no
• Type = boolean
• UI = Forms only
• Example = privileged=true
• Purpose = If the client is not privileged, then template fields marked as protected will be hidden

---

• Required = no
• Type = string
• UI = Forms only
• Example = firstName=John lastName=Smith fullName=John Smith addressLine1=123 Main St city=Chicago stateOrProvince=IL postalCode=60609
• Purpose = Any querystring parameter that matches one of the profile strings can pass elements from the user's profile to the template. (See Profile Strings section)

---

• Required = no
• Type = string
• UI = Forms only
• Example = selectFileButton=Pick+fie+on+your+computer
• Purpose = Text label for the "select" file button for all standard image upload controls, as well as for the VDP file upload control. Defaults to "Select" (with translations according to language)

---

• Required = no
• Type = boolean
• UI = Interactive only
• Example = showfinalpreview=false
• Purpose = Indicates if a final preview should show

---

• Required = no
• Type = string
• UI = Forms only
• Example = updateButton=Update
• Purpose = Text label for the updateCart button (only used for re-editing an existing session)

---

• Required = no
• Type = string
• UI = Forms only
• Example = useAssetButton=Choose+Picture
• Purpose = Text label for the "use asset" button, when appropriate. Default is "Use Asset" (with translations according to language)

Profile Strings

Often the user of your e-commerce application has logged in and has personal information stored in his or her profile, such as name and address. It can be helpful to have an eDocBuilder template automatically fill in appropriate fields from his or her profile.

You can do this by adding the profile fields to the Querystring url. When the template loads, it will automatically match the profile strings you provide to the template fields that have been flagged as that profile type.

For example, if you provide "fullName=John Smith" in the Querystring, and the template has a field called "person" that has been marked as profile type fullName, then when the session begins, the "person" field will automatically be filled with "John Smith".

Here are the available profile types:

firstName middleInitial lastName fullName

jobTitle1 jobTitle2 companyName

addressLine1 addressLine2 addressLine3 city stateOrProvince

postalCode mobilePhone departmentName

email businessPhone cellPhone homePhone pager website

Layout File

The layout file has been depreciated and will be removed from eDocBuilder on 12/31/2020. If you have any questions on how to transition away from layout file useage please contact support.

Postback

When the user presses one of the three session-ending buttons – add to cart, update cart or cancel – the results of the edited session will be sent as a FORM POST to the postbackURL that was provided. The inputs that will be sent are:

docSession	a GUID string identifying the session. This should be saved so that your application can later retrieve the final output file for printing.
docSessionCancelled	True if the cancel button was clicked, false if the add or update button was clicked.
docSession_id	A "friendly name" for the session, equal to one of the choices made by the user.
docSession_fieldName	For each choice made by the end user, a variable will be sent giving that choice's results. If the choice was a file upload, the filename that it was saved under (not necessarily the original file) will be provided here. The fieldname refers to the name of the field in the eDocBuilder template.
fotolia_id_name	For each fotolia image acquired during the design session, the name of the image will be included. The id refers to the Fotolia numeric id.
fotolia_id_cost	For each fotolia image acquired during the design session, the number of credits utilized will be included. The id refers to the Fotolia numeric id.
fotolia_id_dimensions	For each fotolia image acquired during the design session, the dimensions of the image utilized will be included. The id refers to the Fotolia numeric id.
fotolia_id_thumbHTML	For each fotolia image acquired during the design session, a url to the thumbnail of the image utilized will be included. The id refers to the Fotolia numeric id.

Protected fields and privileged clients

Sometimes a template may have certain fields that the user must not or cannot update, and that the printer must update after the order has been placed. In this case the fields are marked as protected when the template is created. Protected fields are normally hidden when the IFRAME client runs; however the printer will want to actually update them, so the client can be told it is privileged (by adding privileged=true to the querystring) and then the protected fields will be shown. Please note this capability applies to standard forms based templates only.

Interactive Designer CSS Files

Customizaton of the interactive designer has been depreciated an is not longer possible.

Interactive Designer Config File

Configuration changes to the interactive designer has been depreciated an is not longer possible.

Categorized Assets

When utilizing the "assetsurl" iframe url parameter and providing a well formatted json file users will be able to browse and search through a large number of image assets to choose for uploading to their templates. A new "Asset Images" tab will show within the image library of the interactive designer and "Use Asset" buttons will show for forms based edoc templates. Each field can be customized to allow the use of asset images or not. Each field can also have a starting category indicated, the starting category name must match a category indicated in the json file.

Example assets.json file

     {
      "assetImages" : [
        {
          "url":"http://blah.com/assetImages/aircraft/0001.jpg",
          "thumbUrl":"http://blah.com/assetImages/aircraft-thumb/0001-thumb.jpg",
          "name": "0001.jpg",
          "category": "aircraft",
          "description": "Velit leberkas ut, eu ball tip ad duis."
        },
        {
          "url":"http://blah.com/assetImages/aircraft/0002.jpg",
          "thumbUrl":"http://blah.com/assetImages/aircraft-thumb/0002-thumb.jpg",
          "name": "0002.jpg",
          "category": "aircraft-blue",
          "description": "Prosciutto tri-tip magna exercitation excepteur."
        }
    ],
      "categories" : [
        {
          "name":"aircraft",
          "parent":""
        },
        {
          "name":"aircraft-blue",
          "parent":"aircraft"
        }
      ]
    }

Related Articles

• Iframe Client depreciated and removed by 12/31/2020
• Can I customize the colors or layout of the eDocBuilder template window?
• Edocbuilder iFrame interface (UPDATED 2020)
• eDocBuilder Custom Interface Colors and Window Layout
• What restrictions apply when using the eDocBuilder iFrame API interface to use assets passed through the URL with assetsURL?