Custom theme: integration

Web-to-print themes
25/10/2010

The web-to-print extension comes with a default theme modified to include all the necessary code from the extension. A Magento website can use a different theme modified to include the code as explained in this manual.

  1. Read this manual
  2. Study the default theme files
  3. Transfer the code from the default theme to your custom theme
  4. Test on w2p and non-w2p products

Disclaimer: theme modifications require a certain level of programming skill.

All files listed here can be found in the extension on Magento-Connect or in the SVN repository.

Every file has the new code divided into several sections. Every section has its sequence number (e.g. ZP-CODE:1) and is enclosed with comments similar to this:

/****** ZP-CODE:1 Short description of code in the block ******/ some code /****** ZP-CODE:1 End ******/

Personalization form

The form is a modified product details page. You need to insert certain function calls at places where the blocks of HTML should show. This screenshot is only a guide to how it can be laid out on the screen. The functions are described below in the article. Web-to-print personalization

Custom theme requirements

The web-to-print extension has several requirements to HTML code of the custom theme.

  • app/design/frontend/default/<your_custom_theme_name>/template/catalog/product/view.phtml

Set id attribute of preview image container (can be a parent, but not immediate one) to zetaprints-preview-image-container value. Search for zetaprints-preview-image-container string in view.phtml file from zptheme theme for example.

  • app/design/frontend/default/<your_custom_theme>/template/catalog/product/view/addtocart.phtml

Set id attribute of Add to cart button to zetaprints-add-to-cart-button value. Search for zetaprints-add-to-cart-button string in addtocart.phtml file from zptheme theme for example.

  • app/design/frontend/default/<your_custom_theme>/template/catalog/product/view/media.phtml

Set id attribute of product image tag to image value. Search for image string in media.phtml file from zptheme theme for example

Files in app/design/frontend/default/<your_theme_name>/

You need to modify some files behind the user interface.

template/catalog/product/view.phtml

This file shows form for ordering on product page. This form contains product images, product name, product description, product price, etc.

New code checks for web-to-print features in a product and adds additional options (ajax image preview, colour picker, stock images chooser and support for multipage templates).

The code is divided into 4 sections.

Section 1: Checking if a product has web-to-print features then printing tabs component for switching pages in multipage templates.

1
<?php $this->helper('webtoprint/personalization-form')->get_page_tabs($this); ?>

Section 2: Checking if а product has web-to-print features then printing text fields, stock images choosers, color pickers.

1
2
<?php $this->helper('webtoprint/personalization-form')->get_text_fields($this); ?>
<?php $this->helper('webtoprint/personalization-form')->get_image_fields($this); ?>

Section 3: Checking if a product has web-to-print features then printing Update preview button.

1
<?php $this->helper('webtoprint/personalization-form')->get_preview_button($this); ?>

Section 4: Checking if a product has web-to-print features then printing javascript code for web-to-print personalization form.

1
<?php $this->helper('webtoprint/personalization-form')->get_js($this); ?>

template/catalog/product/view/media.phtml

This file shows product image, additional images and image zoomer on product page.

New code checks for web-to-print in a product and puts correct images urls additional images.

Section 1: Remove web-to-print images for multi-page templates from the gallery thumbs.

1
<?php $this->helper('webtoprint/personalization-form')->prepare_gallery_images($this) ?>

template/checkout/cart/item/default.phtml

This file shows various information for cart item on shopping cart page.

New code checks for web-to-print in a product and puts correct images urls for cart item, also it adds link to PDF proofs.

Section 1: Checking if product has web-to-print features and then printing <img> tag with correct url; add link to PDF proof for the template.

1
<?php if(!$this->helper('webtoprint/personalization-form')->get_cart_image($this)): ?>

template/sales/order/items.phtml

This file show various information for order item on user orders page.

New code checks for web-to-print in a product and shows preview images for order items.

Section 1: Add link to hide/show all previews one time

1
<?php echo $this->helper('webtoprint/personalization-form')->show_hide_all_order_previews($this); ?>

Section 2: Add preview images for web-to-print products from the order.

1
<?php $this->helper('webtoprint/personalization-form')->get_order_preview_images($this, $_item); ?>

Section 3: Add JavaScript code for preview images.

1
<?php $this->helper('webtoprint/personalization-form')->get_js_for_order_preview_images($this); ?>

template/sales/order/items/renderer/default.phtml

This file shows various information for particular order item on user orders page.

The following ZetaPrints code shows links to generated output files (PDF/PNG/JPG/GIF) in order details. The links appear if the files were generated and the template config (in ZetaPrints) has download by customer setting set to either allow (a user can download files) or only (the order is for downloading only, nothing gets printed). The function returns nothing if the conditions above are not met.

Section 1: inserting links to web-to-print generated files.

1
<?php echo $this->helper('webtoprint/personalization-form')->get_order_webtoprint_links($this, $_item); ?>

The following ZP code adds re-order link to an order item. After clicking on the link the corresponding product page will be opened and fields from personalization form will be filled with values from the order.

Section 2: Insert re-order link.

1
<?php echo $this->helper('webtoprint/personalization-form')->get_reorder_button($this, $_item); ?>

template/catalog/product/view/addto.phtml

This file needs to be modified only of you want to show Share preview link so that users can grab the URL of the image and share it with someone else. In this case the image is downloaded from ZetaPrints to your Magento site for keeping (ZetaPrints deletes unused images quickly). The download happens asynchronously when the user clicks on the sharing text box.

Preview downloading is initiated only when user clicks on text input with URL. All previews downloaded from ZetaPrints are saved in media/tmp/catalog/product/previews/ directory. The directory is created automatically during the extension installation process. Old preview images need to be removed manually from the temp directory.

The following ZetaPrints code adds link to show text field with sharing url for a generated preview. You can insert this function into any other place in the layout, which may be in a different file.

Section 1: Add preview sharing link.

1
<?php $this->helper('webtoprint/personalization-form')->get_preview_image_sharing_link(); ?>

Functions

Most of the extension code is encapsulated in functions. The functions make all necessary checks of the context and return values only if needed. E.g. get_text_fields ($context) function returns nothing if the product has no web-to-print features. This way they do not affect products that have nothing to do with web-to-print.

  • get_product_image ($context, $product) – Outputs nothing, always returns false. (Deprecated)
  • get_page_tabs ($context) – outputs image tabs for multipage templates
  • get_text_fields ($context) – outputs text fields for products with web-to-print features
  • get_image_fields ($context) – outputs image fields (stock images, color picker) for products with web-to-print features
  • get_preview_button ($context) – outputs Update preview button for products with web-to-print features
  • get_js ($context) – outputs javascript code for products with web-to-print features
  • get_js_css_includes ($context) – Outputs nothing, always returns false. (Deprecated)
  • get_preview_images ($context) – Outputs nothing, always returns false. (Deprecated)
  • get_gallery_thumb ($context, $product, $image) – Outputs nothing, always returns false. (Deprecated)
  • get_gallery_image ($context) – Outputs nothing, always returns false. (Deprecated)
  • get_cart_image ($context) – outputs a slightly modified <img> tag to prevent image resizing with correct image url and returns true for products with web-to-print features
  • get_order_preview_images ($context) – outputs previews images for order.
  • get_reorder_button ($context, $item) – outputs A tag with link to re-order web-to-print product page.

Adjust size for different images (preview, stock and user images)

Previews are generated by ZetaPrints at a certain default size. Magento can reduce the preview size, but cannot make it larger. If the preview provided by ZetaPrints is not large enough you need to generate a bigger one first.

Preview images

Size of preview images can be changed in zp-style.css file, see a.zetaprints-template-preview img CSS selector.

1
2
3
4
a.zetaprints-template-preview img {
max-width: 265px;
...
}

Stock images

Size of stock images in a library scroll can be changed in zp-style.css file for PNG and GIF and in common-templates.xslt file for other supported image types. By default every stock image is scaled down to 100px in height.

PNG and GIF images

Change max-width attribute in div.images-scroller img CSS selector in zp-style.css file.

1
2
3
4
5
div.images-scroller img {
...
max-height: 100px;
...
}

Other supported image types

Change 0×100 part of image URL to preferred one where template is WEIGHTxHEIGHT (in pixels) in common-templates.xslt file.

1
2
3
<xsl:otherwise>
<img src="{$zetaprints-api-url}photothumbs/{substring-before(@Thumb,'.')}_0x100.{substring-after(@Thumb,'.')}" />
</xsl:otherwise>

User images

Size of user images in library scroll can be changed in zp-style.css file for PNG and GIF and in PersonalizationForm.php (for already uploaded images) and UploadController.php (for newly uploaded images) files for other supported image types. By default every user image is scaled down to 100px in height.

PNG and GIF images

Same as for PNG or GIF stock images.

Other supported image types

Change 0×100 value of parameter to preferred one where template is WEIGHTxHEIGHT (in pixels) in PersonalizationForm.php and UploadController.php files.

1
2
if ($image['mime'] === 'image/jpeg' || $image['mime'] === 'image/jpg')
$thumbnail = str_replace('.', '_0x100.', $image['thumbnail']);

Spinners for progress of AJAX requests

There’s two types of spinners: big and normal. Big spinner is used for preview loading progress. Normal spinner is used for different AJAX requests to Magento.

Styling links added by the extension

Here is list of CSS class name selectors for links added by the extension:

    • Product page:
      • .add-to-links span.zetaprints-share-link a – selector for “Share preview” link
      • .add-to-links span.zetaprints-share-link.empty a – selector for “Share preview” link in disabled state
    • Shopping cart page:
      • a.zetaprints-lowres-pdf-link – selector for “PDF Proof” link
    • Order details page:
      • a.zetaprints-reorder-item-link – selector for “Reorder” link
      • a.zetaprints-order-file-link – selector for web-to-print order files
      • a.all-order-previews – selector for “Show all order previews” and “Hide all order previews“
      • div.zetaprints-previews-box a.show-title – selector for “Show previews” links
      • div.zetaprints-previews-box a.hide-title – selector for “Hide previews” links

Links to different types (i.e. PDF, PNG, GIF, JPEG, CDR) of web-to-print order files can be distinguished by additional class name (same as file type). E.g. a.zetaprints-order-file-link.pdf – selector for PDF web-to-print order files.

Hiding extension interaction buttons

Web-to-print extension interaction buttons

Put following CSS rule in your custom theme CSS file if you want to hide a button:

1
2
3
4
5
.zp-buttons-wrapper #<id_of_the_button_to_hide>

{
display: none;
}

Button IDs:

  • Enlarge button: zp-enlarge-button
  • Editor button: zp-editor-button
  • Form button: zp-form-button
  • Update preview button: zp-update-preview-form-button
  • Next page button: zp-next-page-button

NOSCRIPT

Product personalization form requires JavaScript. The form won’t load fully if JS is disabled. Make sure your theme has <NOSCRIPT> area to warn customers about the requirement in a visible and informative way.

See also: