eDocBuilder iFrame Interface

EDOCBUILDER > Integration

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 customization of the client's appearance and behavior to a great degree; you can pass your own CSS stylesheet, change the names on the completion buttons, adjust the available zoom levels for the preview, and even supply your own custom layout file to arrange the client sections in any manner you wish, interspersed with your own text and HTML elements.

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.

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 html5 based interface that allows the end user to modify the design by directly clicking on text and image elements on the design surface. Based on template settings, the user may move, delete, and create text and image elements.

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

URL Parameters

Parameter name Required Type Purpose Sample Interactive Standard Forms
addToCartButton no string Text label for the addtoCart button (only used for a new session)   X X
addToCartCausesUpdate no boolean 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. addToCartCausesUpdate=true   X
allowSaveForLater no boolean Saves the session without accepting it. Helpful for supporting a save-for-later option. saveForLater=true X  
altcss no URL Link to a CSS stylesheet for the interactive designer desktop version   X  
altmobilecss no URL Link to a CSS stylesheet for the interactive designer mobile version   X  
approveWhenDone no boolean 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. approveWhenDone=true X X
assetsurl no URL Link to JSON file containing asset images to build a categorized asset list in the image library. See below for details. assetsurl=http://www.ysite.com/files/myassets.json X X
cancelButton no string Text label for the cancel button (used for both kinds of session)     X
cssURL no URL Link to a CSS stylesheet to be applied to the standard forms based client     X
docCode yes GUID string Identifies which template is used for the document session.   X X
docPwd yes GUID string Password for the template   X X
docSession no GUID string When re-editing an existing session this identifies the session   X X
groupChoices no boolean Whether choices will be grouped by the page number they relate to. false (default)   X
idconfig no URL Link to javascript file containing one object assigned to a variable of “idconfig”. See below for details. http://www.mysite.com/files/myconfigfile.js X  
imageSizes no string Comma delimited name- value pairs giving the allowed preview image sizes Tiny=100,Normal=300,Huge=1000   X
layoutURL no URL Link to an HTML file describing the standard forms based client layout to be used. (See Layout File section)     X
postbackURL yes URL Page that will receive the final postback with the session results   X X
privileged no boolean If the client is not privileged, then template fields marked as protected will be hidden privileged=true   X
profile strings no string 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) firstName=John lastName=Smith
fullName=John Smith
addressLine1=123 Main St city=Chicago
stateOrProvince=IL postalCode=60609
  X
selectFileButton no string 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) selectFileButton=Pick+fie+on+your+computer   X
showfinalpreview no boolean Indicates if a final preview should happen or not showfinalpreview=false X  
updateButton no string Text label for the updateCart button (only used for re-editing an existing session) updateButton=Update   X
useAssetButton no string Text label for the "use asset" button, when appropriate. Default is "Use Asset" (with translations according to language) useAssetButton=Choose+Picture   X
 

Profile Strings

Often the user of your e-commerce application has logged in and has personal information stored in his profile, like name and address. It can be helpful to have an eDocBuilder template automatically fill in appropriate fields from his 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

jobTitle1

addressLine2

postalCode

mobilePhone

departmentName

middleInitial

jobTitle2

addressLine3

email

cellPhone

 

lastName

companyName

city

businessPhone

pager

 

fullName

addressLine1

stateOrProvince

homePhone

website

 

 

Layout File

To completely customize the arrangement of the sections of the client, you can provide your own layout file. This is a standard HTML file with the sections of the file marked in it with special tags like ###CHOICES###. When the client loads, it reads this layout file and substitutes its own controls for the tags. Any other content you put in the HTML file is copied literally. The tags are:
 
 

Tag

Required

Purpose

###INSTRUCTIONS###

no

An area where instructions to the user can appear.

###CHOICES###

yes

The area where the fields that the user must fill in will appear.

###DATAMAP###

no

If the template uses vdp functionality (variable data – lets  the user upload a data file and have a copy of the document generated for each record in the data), this is where the "data map" will appear that lets the user

match fields in his data file with fields in the template.

###RESPONSESET###

no

If the template has "response sets" defined, a pulldown selector will appear letting the user select a response set.

###PREVIEWIMAGE###

###PREVIEWIMAGES=n###

###PREVIEWIMAGES=ALL###

yes

Area where one or multiple preview images will appear.

###PAGESELECTOR###

no

If present, a radio button list will appear for selecting which page or pages of the document to preview.

Note: if all pages are currently shown, the selector will be hidden.

###SIZESELECTOR###

no

If present, a pulldown will appear allowing the user to select the size of the preview to be shown.

###UPDATEBUTTON###

yes

Area where the update preview button will appear. This is required so that changes the user make can be sent back to the eDocBuilder server.

###COPYRIGHT###

yes

Shows a label with the branding of the client (i.e., "Powered By eDocBuilder --- 2008")

###CONFIRMATION###

no

If present, the client can display a thank you message after the session is finished.

 
 

Postback

When the user presses one of the three session-ending buttons – add to cart, update cart or cancel – the results of the edition 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

For skinning the Interactive Designer, we give you the ability to provide a link to an external CSS style-sheet that will be applied within the iframe.
 
Currently, this CSS link that you provide will replace the default skin or look of the designer, requiring you to include the default skin in your CSS, with your additional styles. This can cause a number of long-term maintainability issues, one of which being that as we maintain and update the designer, the default style in your external CSS file will quickly become outdated and issues that we fix or updates that we add will not be applied when using this altcss parameter.
 
To fix this, in the near future this CSS will be added to (not replace) the existing look of the designer. This will allow us to maintain and update the application without requiring you to merge these changes with your custom CSS. You can then override or change the style or look, without worry of missing updates and fixes.

Direct edits to the Interactive Designer HTML or layout are not permitted, only the look may be changed.

Note: The iframe width and height should be set to 100%. The site skin should control the dimensions of the tag wrapping the iframe and those dimensions should not be smaller than 940px Width, or 700px Height.

Example of the altcss parameter within a complete iframe url.
<iframe width="100%" height="100%" scrolling="no" src="https://client.edocbuilder.com/iframeclient.aspx?approveWhenDone=false&postbackURL=https%3a%2f%2fabc.salzman.v4.pressero.com%2fcustomize%3faction%3dinteractivePostback&docCode=5b00a6c5-4efd-4607-b935-b58f396f38f3&docPwd=3cbc2670-066d-4a6e-8cfb-9a804562e07d&altcss=http%3a%2f%2fwww.myawesomecsslink.com/css/cool.css" id="testIframe"></iframe> 
 

Interactive Designer Config File

In order to provide specific configuration to the Edoc Interactive Designer we use a url parameter of “idconfig”. This parameter is a url string that will point to a javascript file hosted from a separate url.

Example iframe url with “idconfig” parameter.
 <iframe width="100%" height="100%" scrolling="no" src="https://client.edocbuilder.com/iframeclient.aspx?approveWhenDone=false&postbackURL=https%3a%2f%2fabc.salzman.v4.pressero.com%2fcustomize%3faction%3dinteractivePostback&docCode=5b00a6c5-4efd-4607-b935-b58f396f38f3&docPwd=3cbc2670-066d-4a6e-8cfb-9a804562e07d&altmobilecss=http%3a%2f%2fwww.myawesomecsslink.com/css/coolmobile.css&idconfig=http://www.mysite.com/files/config.js" id="testIframe"></iframe>
 
The javascript config file needs to have a specific format in order for the interactive designer to pull in the information. It will consist of one javascript object assigned to a variable called “idconfig”. Currently this object will have two properties “assetImages” type=array and “preview” type=object.

assetImages (deprecated.. use “assetsurl” parameter instead ) is an array of objects that indicate images used within the image library, all object properties are required for each image.

preview is an object that provides specific configuration information for previewing a template while editing.

Example idconfig file:
 
 var idconfig = {
    assetImages: [
    {
            url:"http://www.saobart.com/5idimages/v1.jpg",
            thumbUrl:"http://www.saobart.com/5idimages/v1-thumb.jpg",
            name: "v1",
            pixelWidth: 800,
            pixelHeight: 791
    }
],
    preview: {
        url: "http://www.w3schools.com/jsref/met_win_open.asp",
        display : "window",
        modalWidth: 700,
        modalTitle: "modal title here yay",
        iframeWidth: 500,
        iframeHeight: 400,
        iframeScrolling: "no",
        windowWidth: 900,
            windowHeight: 700,
            windowFullscreen: "no",
            windowLocation: "no",
            windowMenubar: "no",
            windowResizable: "no",
            windowScrollbars: "no",
            windowStatus: "no",
            windowTitlebar: "no",
            windowToolbar: "no",
            windowTop: 10,
            windowLeft: 10,
            windowChannelmode: "no"
}
};
 

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"
    }
  ]
}
 

Interactive Designer for Mobile Integration

Due to the nature of mobile devices, specifically tablets, it is suggested that the interactive designer be treated as a mobile application to conform to mobile standards and best practices. In order to accomplish this size adjustments need to be made to the iframe that is holding the interactive designer whenever a mobile device loads the iframe. The best solution is to use css to make the iframe 100% width and 100% height so it will fill the entire viewport of the mobile device.

 

Sample Integration

To help you get started, a sample integration site has been included. It provides a demonstration CSS stylesheet, three alternative layout files, and an ASP.NET container page and receiving page. It also contains a single HTML page that demonstrates the process.

The entire project, including both the ASP.NET site and the HTML page, can be downloaded from:
http://creator.edocbuilder.com/admin/IFrameDemoProject.zip

In addition, the HTML page can be reached online at http://creator.edocbuilder.com/admin/IFrameDemo.html

On the following pages is the content of the main ASP.NET file, IFramePage.aspx and its code-behind file, IFramePage.aspx.vb.

Remember that if an alternate layout file is provided, it is the edocBuilder Client that must be able to read it. Therefore it should be a web page that is publicly accessible to the Internet in general. The CSS file and the postback file, on the other hand, only need to be accessible to the browser. So during testing, you can run your project on localhost, but if you want to use an alternate layout file you must put it on the public Internet somewhere.

IFramePage.aspx
 
 <%@ Page Language="VB" AutoEventWireup="false" CodeFile="IFramePage.aspx.vb" Inherits="IFramePage" %>
 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title>Untitled Page</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
    This page encapsulates the eDocBuilder IFRAME client.<br />
    Final URL: <asp:TextBox runat=server ID="FinalURL" TextMode="MultiLine" ReadOnly=true width="700px"/><br />
    <iframe id="eDocIFRAME" runat="server" scrolling="auto" width="1000px" height="700px"/>
    </div>
    </form>
</body>
</html>
 
 
IFramePage.aspx.vb
 
 Partial Class IFramePage
    Inherits System.Web.UI.Page
 
    Const baseurl As String = "http://devclient.edocbuilder.com/iframeclient.aspx"
 
    Private Function ResolveFullUrl(ByVal relative As String) As String
        With Request.Url
            Return String.Format("{0}{1}{2}:{3}{4}", .Scheme, .SchemeDelimiter, _
               .Host, .Port, Page.ResolveUrl(relative))
        End With
    End Function
 
 
    Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) _
     Handles Me.Load
        ' here we will set the IFRAME url.
        ' These are the variables you need to build up the URL
 
        ' REQUIRED VARIABLES
        ' document code -- should be in your product catalog db
        'Dim docCode As String = "D23B7999-2FB2-42ED-BEFF-B5A397734546"
        Dim doccode As String = "7bd3f908-874c-4cb7-86e6-43c4f350aa60"
        ' document password -- should be in your product catalog db
        'Dim docPwd As String = "D5337D34-C97E-4306-BE0A-350B4C793069"
        Dim docPwd As String = "ec637f54-7637-420a-bfde-c405dd332c36"
        ' URL for a page to receive the final information (REQUIRED)
        Dim postbackURL As String = ResolveFullUrl("Receive.aspx")
 
        ' OPTIONAL VARIABLES
        ' session identifier -- required if you are re-editing something from cart
        Dim docSession As String = Nothing '"8B03671B-D71F-4940-913C-A24B2E06571F"
        ' URL for a custom CSS stylesheet (optional)
        Dim cssURL As String = ResolveFullUrl("Demo.css")
        ' URL for an HTML layout page for the edoc client
        Dim layoutURL As String = ResolveFullUrl("AlternateLayout-2previews.htm")
        ' Text label for the addToCart button
        Dim addToCartButton As String = "I approve"
        ' Text label for the updateCart button
        Dim updateButton As String = "OK, I'm done now for real"
        ' Text label for the cancel button
        Dim cancelButton As String = "Never mind"
        ' String describing the allowed image sizes
        Dim imageSizes As String = "Tiny=100,Normal=300,Huge=1000"
        ' Collection of profile strings. One per line, NAME=VALUE format
        Dim ProfileStrings As String = "firstName=John" & vbCrLf & _
         "lastName=Smith" & vbCrLf & "fullName=John Smith" & _
         vbCrLf & "city=Chicago"
 
        Dim url As New System.Text.StringBuilder
 
        url.Append(baseurl)
        url.AppendFormat("?docCode={0}", docCode)
        url.AppendFormat("&docPwd={0}", docPwd)
        If docSession <> "" Then url.AppendFormat("&docSession={0}", docSession)
        If cssURL <> "" Then url.AppendFormat("&cssURL={0}", _
     HttpUtility.UrlEncode(cssURL))
        url.AppendFormat("&postbackURL={0}", HttpUtility.UrlEncode(postbackURL))
        If layoutURL <> "" Then url.AppendFormat("&layoutURL={0}", _
     HttpUtility.UrlEncode(layoutURL))
        If addToCartButton <> "" Then url.AppendFormat("&addToCartButton={0}", _
     HttpUtility.UrlEncode(addToCartButton))
        If updateButton <> "" Then url.AppendFormat("&updateButton={0}", _
     HttpUtility.UrlEncode(updateButton))
        If cancelButton <> "" Then url.AppendFormat("&cancelButton={0}", _
     HttpUtility.UrlEncode(cancelButton))
        If imageSizes <> "" Then url.AppendFormat("&imageSizes={0}", _
     HttpUtility.UrlEncode(imageSizes))
 
        If ProfileStrings <> "" Then
            For Each line As String In ProfileStrings.Split("vbCrlf")
                Dim s() As String = line.Split("=")
                If s.Length = 2 Then
                    url.AppendFormat("&{0}={1}", _
               HttpUtility.UrlEncode(s(0)), HttpUtility.UrlEncode(s(1)))
                End If
            Next
        End If
 
        FinalURL.Text = url.ToString
        eDocIFRAME.Attributes("SRC") = url.ToString
 
    End Sub
 
End Class