Functionality

There are a variety of ways to customize widget functionality. We’re always open to new feature requests/ideas as well– feel free to submit a request on the pio.js github issues page.

Turn Off The Upload Screen

Turn off the file upload screen (great for if you’re passing in the images you want the customer to print):

PIO.open({
  recipeId:"6cfb4f30-34c7-4cf6-9490-f51925650811",
  url:"https://widget.print.io/widget/",
  // turn off the upload screen
  canUseUpload:false
});

Go to a Specific Section in the Widget

Often times it makes sense to start the widget on a specific page rather than the default product listing. Examples are white-labeling certain pages, resuming a widget session in a certain state, or returning a user to a specific section. This can be done with the goTo option.

Valid values for the option are products, details, options, templates, upload, edit, prints, and cart, listed in the order they appear in the widget. More information on the data required to start the widget at these points is outlined at the end of this page.

PIO.open({
  recipeId:"6cfb4f30-34c7-4cf6-9490-f51925650811",
  url:"https://widget.print.io/widget/",
  // starts the widget on the upload page
  goTo:'upload'
});

Use a Custom “Product Selection” Page

Some users prefer to host their own product selection page. Note that our /products API endpoint makes this simple to build.

PIO.open({
  recipeId:"6cfb4f30-34c7-4cf6-9490-f51925650811",
  url:"https://widget.print.io/widget/",
  // turn off the upload screen
  productsUrl:"http://www.hellopics.com/products",
  // note: since the products page is by default the first page shown
  // one needs to start the user at a different page
  // (typically product details, after they've selected a product)
  goTo:'cart'
});

Hide Products That Are Coming Soon

By default the widget will show on its products listing page items that are “coming soon”– meaning close to being available. This is easy to turn off:

PIO.open({
  recipeId:"6cfb4f30-34c7-4cf6-9490-f51925650811",
  url:"https://widget.print.io/widget/",
  // turn off coming soon products
  hideComingSoonProducts:true
});

Hide the Resume Item Popup

When users have unfinished items in their cart from a previous session or an account, they’re prompted to resume these items with a popup. This functionality can be turned off by setting the option hideResumeItemPopup to true.

PIO.open({
  recipeId:"6cfb4f30-34c7-4cf6-9490-f51925650811",
  url:"https://widget.print.io/widget/",
  // turn off the resume item popup
  hideResumeItemPopup: true
});

Localization

While the widget by default detects the user’s country, currency, and language, one can pre-set the ship to country, currency, and/or language (coming soon) quite easily:

PIO.open({
  recipeId:"6cfb4f30-34c7-4cf6-9490-f51925650811",
  url:"https://widget.print.io/widget/",

  // set the localization options here
  countryCode:"FR",
  currencyCode:"EUR",
  languageCode:"en"
});

Passing In Images

One can easily add images to the user’s printable images list by passing in their URLs. If the item passed in is a string, it will be treated as a URL to an image. If the item is an object literal, then one can set URLs for thumbnail (thumb), display image (picture), and final print URL (printUrl). Note that this assumes and requires that the images are all of the same aspect ratio.

PIO.open({
   recipeId:"6cfb4f30-34c7-4cf6-9490-f51925650811",
   url:"https://widget.print.io/widget/",

   // pass in an array of URLs
   images:[

        // could pass in an image
       "http://farm4.staticflickr.com/3731/11237222963_618e5bae33_o.jpg",

       // or could pass in an object literal that allows for more options
       { 
         // thumbnail
       thumb: "http://farm6.staticflickr.com/5499/11298896085_e02b32387d_o.jpg",
        // display image in the edit interface, for instance
          picture: "http://farm6.staticflickr.com/5499/11298896085_e02b32387d_o.jpg",
          // the image that gets printed (usually the highest quality)
        printUrl: "http://farm6.staticflickr.com/5499/11298896085_e02b32387d_o.jpg"
      }
  ],

   //turn off the upload since we're passing in images (not req'd to pass them in though)
   canUseUpload:false
});

Passing In Items

One can also easily pass in items to the user’s cart. The structure of an item passed in is as follows:

{
   productId:0,        //the product id
   sku:'',             //the SKU of the item
   templateName:'',    //the template the item is using
   images:[],          //images for the item
   quantity:0          //num items to add
}

Items such as productId, sku, and templateName are retrievable in the API.

In the following example, we pass in the product we want as well as the image. Since we set goTo to the edit screen, the user can immediately start customizing the item.

PIO.open({
   recipeId:"6cfb4f30-34c7-4cf6-9490-f51925650811",
  url:"https://widget.print.io/widget/",

  // pre set the images a user can use
  images:["http://cdn.print.io/img-manip/131031-11381435c2c53ff9-7.png"],

  // pass in an item to the widget
  // good luck telling me this isnt the sweetest phone case ever
  items:[{
        "productId":57,
        "sku":"PhoneCase-iphone5S-Matte",
        "templateName":"Single",
        "quantity":1
  }],

  // go straight to the edit screen!
   goTo:'edit'
});

Using Custom Metadata

It is possible to pass in custom variables at both the order and item level; this is useful for storing marketing/user/campaign/etc information.

PIO.open({
  recipeId:"6cfb4f30-34c7-4cf6-9490-f51925650811",
  url:"https://widget.print.io/widget/",
   
  // pass in an order-level metadata (optional)
  meta: {
    hi: 'there',  // any key-value pairs could be used
    anyvalue: 'Value1',
    value2: 'Value2'
  },
   
  // pass in an item to the widget
  items:[{
    "productId":57,
    "sku":"PhoneCase-iphone5S-Matte",
    "templateName":"Single",
    "quantity":1,
    "meta": { // item-level metadata (optional)
      metakey21: 'Simple',  // any key-value pairs could be used
      value22: 'Value2'
   }
  }],

  // go straight to the edit screen!
  goTo:'edit'
});

Passing In Customer’s Shipping Address

It’s possible to prefill customer’s shipping address fields.

PIO.open({
   recipeId:"6cfb4f30-34c7-4cf6-9490-f51925650811",
   url:"https://widget.print.io/widget/",
  
   // predefined shipping address (optional)
   shippingAddress: {
      firstName: "Sherlock",
      lastName: "Holms",
      line1: "Baker St., 221B, London, UK",
      line2: "New Scotland Yard, 8-10 Broadway, London, UK",
      city: "London",
      postalCode: "NW16XE",
      countryCode: "UK",
      state: null,
      email: "sherlock@holmes.uk",
      phone: "2233322233322"
    }
});

Turning Off Pushstate/URL Modification

By default, the widget uses HTML5 pushstate in order to save the user’s progress in the browser URL, as well as enable the back/forward buttons of the browser to work.

This can be disabled:

PIO.open({
   recipeId:"6cfb4f30-34c7-4cf6-9490-f51925650811",
   url:"https://widget.print.io/widget/",
   usePushState: false
});

White Labeled Upload Page

It’s possible to use a custom upload page on your own domain to create a white-labeled upload experience. This is useful, for example, in cases where photo collection management is otherwise handled by your application. Note: This assumes you are starting the widget on or after the edit page (using goTo:'edit').

PIO.open({
   recipeId: "6cfb4f30-34c7-4cf6-9490-f51925650811",
   url: "https://widget.print.io/widget/",
   uploadPageUrl: "http://yourdomain.com/upload",
});

When users select the ‘Add Photos’ button on the edit page or select the back button they will be redirected to the url specified in the uploadPageUrl option. The widget will append the current Item ID as a query parameter, as follows: http://yourdomain.com/upload?itemid=16A28C72-97F8-4D90-9468-BCE9FE05A6CB.

You can then use PIO.getCart(recipeId, uniqueUserId, callback) to retrieve the user’s cart.

Once a user is ready to return to the product customization process, you can restart the widget by passing in the existing cart and images along with the new images uploaded by the user. It’s also often useful to specify which item the widget should start on, which can be defined using the PIO option focusItemId outlined below.

Starting the Widget with a Specific Item Focused

When passing in items, it can be helpful to instruct the widget to focus on a specific item. This ensures that users can resume customization on the specific product they left off on.

PIO.open({
   recipeId:"6cfb4f30-34c7-4cf6-9490-f51925650811",
   url:"https://widget.print.io/widget/",
   focusItemId:"16A28C72-97F8-4D90-9468-BCE9FE05A6CB",
   items:[...]
});

In order to use focusItemId, you must pass in the specific item you would like the widget to focus on. See more in ‘Passing in Items’ above.

Going Straight To The Product Details Page

In order to go to the product details page one needs to pass in an item that specifies the productId of the product they wish to see the details of.

In this example we’re going to go to the product details page for canvas wraps, which have a productId of 43.

PIO.open({
    recipeId:"6cfb4f30-34c7-4cf6-9490-f51925650811",
    url:"https://widget.print.io/widget/",

    // canvas wrap productId is 43
    items:[{productId: 43}],

    goTo:'details'
})

Going Straight To Sku Selection

Just like going to product details, in order to go to the sku selection pages one needs to pass in an item that specifies the productId of the product they wish to see the details of.

PIO.open({
    recipeId:"6cfb4f30-34c7-4cf6-9490-f51925650811",
    url:"https://widget.print.io/widget/",

    // canvas wrap productId is 43
    items:[{productId: 43}],

    goTo:'options'
})

Going Straight To Edit

In order to go to the edit page, one must have an item with a productId, sku, template, quantity, and there needs to be images passed in:

PIO.open({
    recipeId:"6cfb4f30-34c7-4cf6-9490-f51925650811",
    url:"https://widget.print.io/widget/",

    images:["http://cdn.print.io/img-manip/131031-11381435c2c53ff9-7.png"],

    items:[{
      "productId":57,
      "sku":"PhoneCase-iphone5S-Matte",
      "templateName":"Single",
      "quantity":1
    }],

    goTo:'edit'
})

Going Straight To The Cart

After a user has a built item in the cart you can launch the widget and take them straight to the cart:

PIO.open({
   recipeId:"6cfb4f30-34c7-4cf6-9490-f51925650811",
   url:"https://widget.print.io/widget/",
   // go to the cart!
   goTo:'cart'
});