Widget API Reference

Methods

PIO.config(options)

Configures the widget for future calls to PIO.open(options). Note that options can be passed in to both PIO.config(), PIO.options() or just one of them. See the section Config/Open Options API below for more details.

PIO.open(options)

Opens the widget. Note that one can pass in preset items/images.

PIO.close()

Closes the widget.

PIO.getCart()

Returns the user’s current cart.

PIO.getNumItems()

Returns the current number of items in the user’s cart. It is recommended that this be used in conjunction with the options fns.onCartChange() callback– PIO.getNumItems() is great for getting a pre-launched cart’s items count wereas fns.onCartChange() is great for changing based on the user’s live usage of the cart.

PIO.clearCart()

Removes all items from the user’s cart.

PIO.getOrdersPostData()

Retrieves widget orders post data using following code:

PIO.getOrdersPostData(function(data){
    // process order post data here
});

Options Reference

Important– these options can be passed into either the PIO.config(options) function or the PIO.open(options) function. It is recommended that one pass in items like images or items to PIO.open(options) and pass in items like the recipeId and fns callback functions to PIO.config(options).

PIO.config({

    //REQUIRED
    // apikey / recipeId
    recipeId: '',

    //REQUIRED
    // url of widget (can be staging or live)
    url: 'https://staging-widget.print.io/widget/',

    //optional
    //add the iframe to an existing dom place
    embedInElement:false,

    //optional
    //predefined images
    images: [],

    //optional
    //predefined items
    // an item should have the form
    // { productId:0, sku:'', templateName:'', images:[], meta: {} }
    items: [],

    //optional
    //turn widget functionality on/off
    canUseUpload: true,
    skipProductDetails:false,
    canBuyOtherProducts: true,
    canUseMap: true,
    alwaysUseSingleTemplate: false,

    // optional
    // hide coming soon products
    hideComingSoonProducts:false,

    //optional
    //go straight to a page in the widget
    goTo: '',
    goToCustomize: false,

    //optional
    //an orderid-- would make the widget go straight to an orderid/review
    orderId: null,

    //optional
    //use back button wisely
    usePushState: true,

    //optional
    //whether or not to fade out the page's background}
    fadeBackground: true,

    //all optional
    //pass in user preferences
    countryCode: '',
    currencyCode: '',
    languageCode: '',

    preLoad:{
        on:false
    },

    //all optional
    fns: {
        //callback for when the widget cart/order changes
        onCartChange: function (cart) {

        },
        //callback on widget close
        onClose: function () {

        },
        //callback on widget open
        onOpen: function () {

        },
        //lets get real generic here
        //anything that happens,
        //lets pass through here
        onEvent: function () {

        },

        // function that handles custom photo source data
        // request is an object like { page: 1, folder: "" }
        // replyFn is a callback that takes an object like
        /// { id:"", page: 1, totalPages: 1, items: [] }
        /// where items contains objects like
        /// { picture: "http://hi.com/hi.jpg" } for images
        /// { id: "", isFolder: true, name: ""} for folders
        onPhotoSourceReq : function(request, replyFn){

        }
    },

    // all optional
    style: {
        // whether or not to show the headerbar w/ logo
        showHeader: true,

        // use a custom CSS file
        // if you plan on doing this in production
        // email engineering@print.io the CSS you'd like to use
        // and we'll performance optimize it, CDN it on https site, etc etc
        cssUrl:''
    },

    //optional
    iframeStyles: {
        // any CSS rule names and values. these will be applied last
    },

    // set ordering/etc for photosources on upload page
    photosources:{
        local: {
            enabled: true,
            sortOrder: 1,
            isInitiallyOpen:false
        },
        facebook: {
            enabled: true,
            sortOrder: 2,
            isInitiallyOpen:false
        },
        instagram: {
            enabled: true,
            sortOrder: 3,
            isInitiallyOpen:false
        },
        photobucket:{
            enabled: true,
            sortOrder: 4,
            isInitiallyOpen:false
        },
        flickr: {
            enabled: true,
            sortOrder: 5,
            isInitiallyOpen:false
        },
        google: {
            enabled: true,
            sortOrder: 6,
            isInitiallyOpen:false
        },
        dropbox: {
            enabled: true,
            sortOrder: 7,
            isInitiallyOpen:false
        },
        custom: {
            sortOrder: 8,
            enabled: false,
            iconUrl: '',
            isInitiallyOpen:false
        }
    },


    //Optional
    helpUrl:'',

    //Optional
    productsUrl: '',

    //Optional
    confirmationUrl: '',

    //Optional
    supportEmail: '',

    //predefined coupon value
    coupon: null,

    // restore image collection
    preserveCollection: null,

    // restore currency from local storage
    restoreCurrency: true,
    
    // Optional
    // predefined shipping address
    // shippingAddress: {
    //    firstName: 'Keith',
    //    lastName: 'Richards',
    //    line1: "Exile on Main St., London, UK",
    //    line2: "Brown Sugar, Sticky Fingers rd., London, UK",
    //    city: "London",
    //    postalCode: "BD235HZ",
    //    countryCode: "UK",
    //    state: null,
    //    email: "keith@rollingstones.uk",
    //    phone: "2233322233322"
    //    }
    shippingAddress: null,
    
    // Optional
    // predefined object-based metadata for entire order
    // useful to identify separate orders and provide additional information
    meta: null
    
});