Documentation

Installation

This plugin works in conjunction with WooCommerce for WordPress. WooCommerce must be activated on your WordPress site to continue.

To Install Gift Wrapper Plus Plugin

Deactivate and delete the free version of Gift Wrapper. It is not required going forward. Settings from the free version are safe in the database and will be used in the paid version. However, if you are using template overrides in the free version, you will need to integrate those manually into the paid version.

  1. Unzip the woocommerce-gift-wrapper-plus.zip (ZIP) package *
  2. Upload the entire “woocommerce-gift-wrapper-plus” folder to the “/wp-content/plugins/” directory
  3. Activate the plugin through the “Plugins” menu in WordPress

More about how to install manually via FTP/SSH.

Another different way to install a plugin is to go to Plugins -> Add New, click “Upload Plugin” and upload the ZIP file. Then activate the plugin.

Managing License Keys

Once Gift Wrapper Plus is installed and activated on your site, head over to the WooCommerce tab -> Settings -> Gift Wrapper Tab -> License Key. Activate your license key to get full access to all settings panels for setup.

Please note the plugin functions and gift wrapping occurs without the license key activated. However, if the license key expires or is inactivated, advanced settings panels will be inaccessible. Activating the license also allows your plugin to seek automatic updates via API.

Screen capture of license key screen in Gift Wrapper settings

  1. Enter your license key
  2. Click the “Activate License” button to activate your license. OR, click the “Deactivate License” button to deactivate your license if it is active

Deactivating your license on this screen will make the license available to be used on another site. You can also check the status of or deactivate license keys at via your Gift Wrapper online account (www.giftwrapper.app/account). do not count toward your license key activation count.

If your URL matches the following, it does not count toward key activations:

  • localhost
  • 10.0.0.0/8
  • 172.16.0.0/12
  • 192.168.0.0/16
  • *.dev
  • *.local
  • dev.*
  • staging.*

Set up Wrap

  1. Start by adding at least one WooCommerce product (Products -> Add New) called “Gift Wrapping” or whatever you desire. It needs a name and a price at least. You can also add a featured image, description, tax details, and inventory if desired.
  2. Create a unique product category (Products -> Categories) for this/these gift wrap product(s), and add them to this category.

Head over to the settings page at yoursite.com/wp-admin/admin.php?page=wc-settings&tab=wcgwp (applies to version 4.0 and newer)

On the Gift Wrapper settings tab, under the “General Options” sub-tab, you should set the category used for gift wrap products. If a product category is not set for wrap display, the plugin will not function. You can also set a separate category for products if desired, but this is not required for the plugin to work.

Also on this page, under “Order Wrapping,” you can add links on the Cart and/or Checkout page in case you want customers to be able to add wrap to their order. Options include “before cart,” “after cart” “after coupon/before collaterals,” “before checkout,” and “after checkout.” When the prompt for wrap is clicked, the wrap options will open in a slide-out or a modal/pop-up, depending on your settings.


Original wrap locations

The plugin comes with the option to place a link prompting customers to add giftwrapping–in five possible positions. This bare-bones 5-position option is featured in the free version of the plugin. Both free and Plus plugins use WooCommerce action hooks which are OUTSIDE the cart/checkout <form>, namely:

  1. ‘woocommerce_before_cart’
  2. ‘woocommerce_before_cart_collaterals’
  3. ‘woocommerce_after_cart’
  4. ‘woocommerce_before_checkout_form’
  5. ‘woocommerce_after_checkout_form’

The names of the hooks speak for themselves as far as where they are on the page. Here is a video showing all five positions with the Divi theme loaded, one by one, with the non-modal wrap display (a jQuery slide-down [“slideToggle”]). Depending on your theme, and if it has overridden any of these hooks, the positions may or may not show the wrap prompt link. If your theme has overridden cart/checkout action hooks, it is up to you to either choose another of the five prompt locations or work with your theme developer to devise a solution. Learn about custom wrap locations (not supported) below.

Not behaving as expected?

As always, when a web page isn’t loading as expected on the Internet, start by clearing your browser caches. If you are using a WordPress caching plugin, clear its caches as well, and review its settings to make sure caching is not over-aggressive. If this doesn’t help, keep reading below about some common issues.

Plus Settings

The Gift Wrapper Plus (paid version) plugin has a WooCommerce settings tab with sub-sections, and some settings on every product edit page. If you have used the free version, you are familiar with the main “Cart/Checkout Wrapping” settings page. There are also links to the settings tab from the Plugins listing page. Please test your gift wrapping options by making mock purchases before going live to make sure it works and looks great!

Product wrapping

Per-product wrapping settings, for both on product pages and inside the cart (line item), is under the “Product Wrapping” tab.

If you wish to create special rules for specific products, additional settings panels are found in each product editor screen, in WooCommerce’s “Product Data” panel.

The “Product Wrapping” section allows you to decide whether and how to show per-product gift wrap options. There are several options to add per-product gift wrapping:

  1. On the product page as a simple, no-frills “add wrap” checkbox before the “add to cart” button
  2. On the product page as a slide-out selection with a description and optional textarea for customer notes
  3. On the product page as a pop-up/modal (two modal styles possible) with optional textarea for customer notes
  4. On the cart page per line item, under the product name, as a slide-out or pop-up/modal

What is a “Line Item?”

You will notice the use of the term “line item” in this plugin. WooCommerce calls it a “cart item.” It is a row in the cart, usually one item/product. A cart might have several line items (cart items) inside, and with Gift Wrapper, each one can be wrapped individually if you desire.

Using Gift Wrapper settings, ratio of line item to gift wrap can be kept

  • One-to-one 1:1 with one wrapping per product
  • Only one wrap no matter how many quantity line item, or
  • Ad lib quantity, any quantity of wrap per line item

gift wrap quantity settings

This setting applies to line-item gift wrapping on the cart page, and could help prevent customers ordering too much or too little wrap.

Per-product setting overrides

If you are offering per-product wrapping, you may want to set wrap differently for different products. Visit the product with the wrap you want to edit, and click the Gift Wrapper tab. This tab is in the same section as the price/inventory/attributes settings. You will see the option to override the default/global wrap settings for this product:

woocommerce per product gift wrap settings

With this panel, you can also turn OFF the option to gift wrap certain items even though most other things in your catalog get wrapped. For example, you might not want to gift wrap pianos or refrigerators, just the smaller things.

Hide the Textarea Box

If you don’t want customers entering notes, then set the textarea length to 0 (zero) in the settings.

how to hide the gift wrap textarea

Translating Gift Wrapper

The Gift Wrapper is fully translation-ready. Many people have written online about how to translate WordPress plugins, and quite a few plugins exist to assist. Here’s a place to start, with some background and decent advice on how to go about with translating ANY plugin (including this one).

Read below if you prefer to use hooks to just change the wording on some customer-facing strings.

If you don’t understand WordPress localization or hook use and don’t have time to learn, a quick way to change Gift Wrapper default text strings is with the handy built-in string editor. It has its own settings tab called “Language” in the Gift Wrapper main settings area.

If you are using WPML and struggling to translate the “details” field, it’s because it might be stored in the wp_options database table (if you have been using this plugin since inception). WPML doesn’t peruse these table entries unless asked to. This makes it a little trickier to translate, but not too tricky! Learn how to translate details stored in wp_options using WPML here.

In version 5.0 the “details” field, notoriously difficult to translate using WPML, was moved alongside the rest of the strings. Now if you delete the string in the Gift Wrapper “Language” tab, and leave that blank, a default can be set using the ‘wcgwp_wrap_offerings’ filter hook, and the string will be picked up by WPML for translation. How to do that?

function my_custom_wrap_offering_text( $text ) {
    /*add any conditionals here, e.g. "if ( is_product() )" etc. */
    $text = 'Wrapping this makes this gift all the more special.';
    return $text;
add_filter( 'wcgwp_wrap_offerings', 'my_custom_wrap_offering_text', 10, 1 );

New in version 3.0, Gift Wrapper uses a vanilla JS modal which will not conflict with theme modals.

Older versions of this plugin uses the Bootstrap modal, version 4+, which occasionally caused some issues. The new modal avoids those issues, but still uses Bootstrap styling, which is good for anyone who customized their Gift Wrapper modals previously. It’s good for anyone, really, because with template overrides and CSS tags it can be made your flavor of rad.

Using Bootstrap documentation and CSS/HTML, you will be able to adjust styling of your modal ad lib using the plugin’s templating system. For example, you could get a small popup window instead of a large one by editing your modal template (modal.php or modal-product.php depending on modal location, cart/checkout or product page) to use the ‘modal-sm’ instead of ‘modal-lg’ inside the ‘modal-dialog’ <div>. Alternatively, if you’re familiar with WP hook use, you can use the ‘wcgwp_modal_size’ filter hook to change to the ‘modal-sm’ size.

You can also choose to animate your modal entry and/or exit with the choice of over 1500 CSS animation combinations, with the click of a button (no coding required).

gift wrapper modal animation.css settings
Gift Wrapper modal animations settings panel. There are forty CSS animation styles for the gift wrap pop-up, meaning a ton of combinations are possible!

Using Templates

If you would like to change the structure or appearance of gift wrap lists and modals, you can use the Gift Wrapper templating system to do that. You will need to create a folder called woocommerce in a child theme folder if it doesn’t already exist. (Learn what a child theme is, why use one, and how to make one.) Inside that ‘woocommerce’ folder, create another folder called wcgwp.

Move any overridden (over-written) Gift Wrapper plugin template files into this wp-content/child-theme/woocommerce/wcgwp folder. Any code changes you’ve made to that new template file inside the child-theme will be visible online. Read more information on WooCommerce templating.

For example, if you wanted to alter and style the modal on a single product page, the template you’d look at is in the woocommerce-gift-wrapper-plus/templates/wcgwp/ folder, called modal-single-product.php. Copy and move that php file to your child-theme-whatever-its-called/wooommerce/wcgwp/ folder. At that point you can make changes to the modal display. You will want to make sure you keep the basic Bootstrap modal syntax intact, so that the modal continues to function. Changing modal form input names is also strongly discouraged, as it will also break function. If you have suggestion for DOM items or CSS tags which could help everyone and prevent you from templating, please get in touch.

Keep reading below (under “hooks” ↓) about how to change text using hooks.

Some available hooks

Editing templates works, but is less future-forward than using hooks. This means that if a parent template is updated/changed by the developer for better function or to fix an issue, and you don’t have time to also fix your template override, you might have problems. Updates to templates ARE announced on your backend with plugin updates, so at least you will have warning.

Filter hook ‘wcgwp_hide_details‘ allows you to hide the gift wrap “details” (explanation) area above the wrap selection and note textarea. Example use (in theme functions.php file, for example):

add_filter( 'wcgwp_hide_details', '__return_true' );

Filter hook ‘wcgwp_change_thumbnail‘ will allow one to change the image size for gift wrap options. Default is “thumbnail.” An example of how to change to another existing WordPress image size (such as “medium,” “large” or “full”) is as follows:

add_filter( 'wcgwp_change_thumbnail', 'wcgwp_change_thumbnail_full', 10, 1 );
function wcgwp_change_thumbnail_full( $size ) {
    $size = 'full';
    return $size;
}

Boolean filter hooks ‘wcgwp_continue_after_cart_item_name’ and ‘wcgwp_continue_before_add_to_cart_button’ allow for more granular (e.g. product-by-product) control of whether “add gift wrap” prompts are shown. Their parameters, $cart_item and $cart_item_key would allow you to inspect the cart item and determine if you wish to proceed with offering wrapping for it or not.

Edit Text Displayed

Boolean filter hook ‘wcgwp_add_price_to_name‘ allows one to decide if the price will be shown with the gift wrap item.

Filter hook ‘wcgwp_filter_link_in_cart‘ allows for adjusting the output of the gift wrap product link which brings your customer to the full gift wrap product page.

Filter hook ‘wcgwp_display_item_meta‘ allows one to show price meta in order confirmation, etc.

Filter hook ‘wcgwp_product_name‘ allows one to change the appearance of the gift wrap product name for the simple gift wrap option.

Filter hook ‘wcgwp_add_wrap_prompt‘ allows for changing the “Add gift wrap?” prompt text, when template changes or WP translation can not or will not be used. Similarly, ‘wcgwp_add_wrap_message‘ allows you to change the “Add Gift Wrap Message:” text.

In the following example, the “Add gift wrap?” text is changed to read “Gift wrapping?”

add_filter( 'wcgwp_add_wrap_prompt', 'wcgwp_change_wrap_prompt', 10, 1 );
function wcgwp_change_wrap_prompt( $prompt ) {
    $prompt = 'Gift wrapping?';
    return $prompt;
}

In the following example, the “Add Gift Wrap Message:” text is changed to read “Add a note?”

add_filter( 'wcgwp_add_wrap_message', 'wcgwp_change_wrap_message', 10, 1 );
function wcgwp_change_wrap_message( $msg ) {
    $msg = 'Add a note?';
    return $msg;
}

If you are uncomfortable editing your child theme functions.php file, you can use the plugin “Code Snippets” to add this PHP to your WordPress installation.

Filter hook ‘wcgwp_line_item_parent_name‘ and ‘wcgwp_product_parent_name‘ allow for altering how a wrap product’s parent product name is displayed in the cart and admin, when wrap is added as its own line item. Associating it with its parent product (the product to be wrapped) helps the customer and admin see the correlation between the two.

Change gift wrap listing Order & Order by parameters

By default, gift wraps are listed by date posted, newest first. This can be changed with the filter hooks ‘wcgwp_order‘ and ‘wcgwp_orderby‘. For instance if you wanted to re-order them by title A-Z instead of date newest first, you could add the following code to your functions.php file:

add_filter( 'wcgwp_orderby', function() {return 'title';} );

A more popular configuration might be to use menu_order, to take advantage of drag-and-drop-style product menu re-ordering.

add_filter( 'wcgwp_orderby', function() {return 'menu_order';} );

Default is descending (DESC) order. You could switch this to ascending using:

add_filter( 'wcgwp_order', function() {return 'ASC';} );

The post query arguments (for looking up wrap items) can be filtered using the ‘wcgwp_post_args’ hook. In rare circumstances this might be desired, or perhaps necessary. Learn more about available query parameters here.

Custom wrap locations

As long as a WooCommerce action hook isn’t inside a cart/checkout <form>, you can put gift wrap prompts in other locations on those pages with custom code snippets. Here is an example of how to use the `custom_wrap_location` method to add wrap prompt to the `woocommerce_cart_contents` hook inside the Woo cart template:

function my_custom_wrap_location() {
	if ( method_exists( 'Gift_Wrapper_Plus_Wrapping','custom_wrap_location' ) ) {
		// 'wcgwp_custom_location' is a label that will be used for class tags in the DOM
		// Change the label ad lib
		WCGWrap()->wrapping->custom_wrap_location( 'wcgwp_custom_location' );
	}
}
add_action( 'woocommerce_cart_contents', 'my_custom_wrap_location', 10 );

Depending on the hook you choose this may or may not work. There’s a specific reason Gift Wrapper comes with the locations it does. Some hooks will not work, and some hooks may be difficult to style. Use at your own risk.

Dealing with virtual products

By default, this plugin will hide gift wrapping options if only virtual product is in the cart.

Filter hook ‘giftwrap_exclude_virtual_products‘ allows one to turn off giftwrap offerings when only virtual products are in the cart.

add_filter( 'giftwrap_exclude_virtual_products', '__return_true' );

Filter hook ‘wcgwp_virtual_products_only‘ allows one to fool the Gift Wrap plugin into thinking there are or aren’t all virtual products in the cart (when there are). This would cause gift wrap options to show even when you have a cart full of virtual product. Example of use:

add_filter( 'wcgwp_virtual_products_only', '__return_false' );

Filter hook ‘giftwrap_single_virtual_products‘ would allow you to still show gift wrap options for a virtual product. You would change it to true as follows, in your functions.php file (or in a custom plugin):

add_filter( 'giftwrap_single_virtual_products', '__return_true' );

Filter hook ‘wcgwp_remove_cod_gateway‘ would allow you to hide the COD payment option if your cart contains a gift wrap product (this might suggest the cart is a gift, and the recipient shouldn’t have to pay for it). You would change it to true as follows, in your functions.php file (or in a custom plugin):

add_filter( 'wcgwp_remove_cod_gateway', '__return_true' );

You could also use the ‘wcgwp_change_gateways‘ filter hook to name which payment gateways show when gift wrap is in the cart.

There are even more filters which your developer will find digging around the code. Need new hooks or tweaks? Please get in touch – we are happy to help!

Make wrap options visible by default

Gift Wrapper generally keeps the gift wrap options hidden until the customer clicks a prompt. This is because gift wrap takes a good amount of screen real estate, and in many shops, perhaps most, most orders are not gift-wrapped. To have gift wrap (slide-outs, not modal) show by default, try using this CSS:

body .wc-giftwrap .wcgwp_slideout{display:inline-block}

We also recommend dequeuing the related Javascript:

For cart/checkout area slide-outs:

function dequeue_wcgwp_cart_scripts() {
    wp_dequeue_script( 'wcgwp-slide-cart-checkout' );
}
add_action( 'wp_enqueue_scripts', 'dequeue_wcgwp_cart_scripts', 99 );

For product page slide-outs:

function dequeue_wcgwp_product_scripts() {
    wp_dequeue_script( 'wcgwp-slide-product' );
}
add_action( 'wp_enqueue_scripts', 'dequeue_wcgwp_product_scripts', 99 );

This saves extra, unnecessary JavaScript loading on your pages and also prevents possible errors with orphaned code.

Theme Issues

Every once in a while we get a report that the Gift Wrapper plugin “doesn’t work.”

Putting aside the fact that it’s just not enough information to help anything, oftentimes we find it’s not the plugin that is “broken.” It’s the theme. We generally confirm this by quickly testing the plugin with different WordPress themes. If Gift Wrapper works with other themes, then the problem is unique to the theme in use.

Due to the staggering number of WordPress themes and individualized shop arrangements, Gift Wrapper could not possibly satisfy everyone out-of-the-box. Sometimes the plugin seems to be missing functionality. Often we find that is because the user’s current theme has removed hooks necessary for plugin functioning or has aggressively styled WordPress with CSS z-indexing. This is a bit beyond our control, but usually a work-around can be found in cooperation with the theme developer.

Gift Wrapper contains a number of highly customizable templates and hooks, which should allow you to achieve your desired results. See above for how to use the templating system to make changes to how gift wrap products are shown.

Things themes do wrong

More and more we are finding that premium WordPress themes (with WooCommerce “support”) are doing one or two things with their code which interferes with how plugins can cooperate to make a great website.

  1. Z-index issues
  2. Hook (action/filter) issues

Z-index issues

Themes and plugins sometimes use CSS z-indexing to create stacking panels, for example, sticky headers that hide a part of the screen below. Unfortunately, Wild West

stacking, with numerous plugins and then the theme all setting z-indexing, can prevent pop-ups/modals from showing. If your pop-up is greyed out and you can’t click its buttons, maybe first check your browser error console to make sure you don’t see any JavaScript issues. If you don’t see JS errors, it’s probably just CSS z-indexing getting in the way. Often z-indexing can be re-stacked with some custom CSS added to your child theme or WP/theme options “custom CSS” panel.

Here are some helpful reference articles to help you learn more about z-indexing:

4 reasons your z-index isn’t working (and how to fix it)

The Z-Index CSS Property: A Comprehensive Look

Hook issues

Plugins sometimes remove or re-arrange critical WooCommerce hooks that developers use to add functionality. As soon as these hooks are added back in, plugins like ours start working again.

An example of missing hooks

The Bridge theme, with over 125,000 sales, has inexplicably removed the hook ‘woocommerce_after_cart_item_name’ from the woocommerce/cart/cart.php template. For the Gift Wrapper plugin, this hook allows the “Add Gift Wrap?” prompt to show after each line item product name in the cart. So, for customers trying to use Gift Wrapper with the Bridge theme, that prompt does not show.

If your theme authors have for some reason tampered with the ‘woocommerce_after_cart_item_name’ hook, e.g. removed and re-named it, the prompt link for wrap will not show.

Let’s Fix Bridge

The quickest option is to create a cart.php WooCommerce template override in a child theme /woocommerce/cart folder, and add the hook back in!

do_action( 'woocommerce_after_cart_item_name', $cart_item, $cart_item_key );

The line above is the hook needing back in. Where to add in that line of code? Add it in right before where you see this line:

/*** Our code modification inside Woo template - end ***/

The hook omission in the Bridge theme is still in place as of version 19.2.1, but was noted in version 18.0.6. I contacted the theme developers and didn’t hear back. For other themes, you will add the line

<?php do_action( 'woocommerce_after_cart_item_name', $cart_item, $cart_item_key ); ?>

near (before or after) where you see the line:

<?php echo wc_get_formatted_cart_item_data( $cart_item ); ?>

The Moral

The moral of the story is… WordPress and WooCommerce use “hooks,” like clothes hooks, on which plugins can hang their wares (add-on functionality). Themes and plugins can also remove hooks, or move hooks. If some of those hooks are missing because the theme has removed them, third-party plugins have no way to add functionality. If the problems with the theme are not addressed, the user will continue to struggle with plugins. Themes advertising WooCommerce compatibility should NOT be entirely removing WooCommerce hooks.

Themes confirmed to work:

Astra
Avada (needs Bootstrap JS dequeued in Gift Wrapper settings)
Divi
Flatsome
GeneratePress
Go (from GoDaddy)
Hello Elementor
OceanWP
Storefront
WordPress’ Twentytwelve through Twentytwenty
Woostify

Themes with confirmed troubles:
The following themes remove the necessary ‘woocommerce_after_cart_item_name’ action hook:

Bridge (includes z-indexing on product pages which interferes with modal)
Claue
Martfury
Node (similarly to Bridge theme, has removed the ‘woocommerce_after_cart_item_name’ hook so line item wrap prompts do not show)
Shopkeeper (z-indexing issues interfere with modal)
The Retailer (“after cart” wrapping covered up by rest of cart, and disappears. Try this CSS to un-bury it: .giftwrap_after_cart{clear:both})

If you are using one of these themes, we recommend you contact the theme authors and request they add the ‘woocommerce_after_cart_item_name’ back in place where it should be.

Mini carts and cart drawers

Gift Wrapper is designed to show wrap prompts in the cart, checkout and single product pages. If you have a fancy theme or plugin which adds functionality to WooCommerce such that it shows a more detailed cart on other pages of your website, the Gift Wrapper prompts (esp. for modals) might not work without additional coding. This is in consideration but not planned for addition to Gift Wrapper as a feature, and you will need to build it on your own. For now, we recommend hiding line-item (cart item) add gift wrap prompts while on other pages than the cart/checkout pages, using a filter such as:

function maybe_no_show_after_cart_item_name( $bool = TRUE, $cart_item, $cart_item_key ) {
    if ( ! is_cart() && ! is_checkout() ) {
        $bool = FALSE;
    }
    return $bool;
}
add_filter( 'wcgwp_continue_after_cart_item_name', 'maybe_no_show_after_cart_item_name', 10, 3 );

or selectively remove WooCommerce’s ‘woocommerce_after_cart_item_name’ action hook if not on the official WooCommerce cart/checkout page. Default (non-fancy, for lack of aa technical term) mini carts do not include this action hook, and will not give you grief.

The Is-There-Wrap-in-Cart? Conditional

Gift Wrapper has a helper class that checks for gift wrap in the cart. The giftwrap_in_cart method (WCGWrap()->wrapping->giftwrap_in_cart) returns boolean TRUE if there is wrap. It can be used for things like adding a Gift Wrap handling fee, for example:

function maybe_add_giftwrap_fee() {

    if ( ! class_exists( 'Gift_Wrapper_Plus' ) || ! WCGWrap()->wrapping->giftwrap_in_cart ) {
        return; // exit if there is no gift wrap in cart
    }
    // add a $1 fee with the title “Gift Handling Fee"
    WC()->cart->add_fee( __('Gift Handling Fee', 'woocommerce'), 1 );
	
}
add_action( 'woocommerce_cart_calculate_fees', 'maybe_add_giftwrap_fee' );

Get in Touch

Questions? Please get in touch. For technical issues, please perform the following steps before making contact (or be ready to do them):

  • Complete a basic plugin troubleshooting process.
  • Please also rule out a theme conflict by briefly activating a different theme, esp. a WordPress theme like twentytwentytwo and seeing if the issue still exists.
  • 500 error or critical error or WSOD (white screen of death)? Make sure WordPress debugging is enabled so that you can quickly get to the root of the problem by reading through error messages in your wp-content/debug.log file. Or send us the file and we will read it for you!

Please do not use the WordPress.org forum to seek support for or review this – or any other paid – plugin. That is against WordPress.org policy, and you will get much faster help if you email us directly. Thank you!

To top