> For the complete documentation index, see [llms.txt](https://help.pixfizz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.pixfizz.com/personalization/custom-design-tools/gang-sheet-tool-setup-and-activation.md).

# Gang Sheet tool: setup and activation

How to add the Gang Sheet Builder to a store, from an empty site to a working product page. The tool lets a customer upload several designs, set a printed size and quantity for each, and have them nested onto a roll that grows only as long as it needs to.

***

### Overview

The Gang Sheet Builder is a custom design tool. It replaces the ordinary file upload on a roll-goods product with a full nesting workflow:

* The customer uploads one or more PNGs.
* They set a printed width, height and quantity for each design.
* The tool nests every copy onto the roll and grows the sheet only as long as it needs to be.
* The sheet length is written to a priced variant, so the price on the page moves as the sheet grows.
* On submit, the tool renders a single transparent PNG of the whole sheet and attaches it to the order.

It is built for DTF transfer film, and works for any product sold by the running length of a fixed-width roll.

***

### Before you start

| Thing            | Where from                                                 |
| ---------------- | ---------------------------------------------------------- |
| The setup bundle | Attached below                                             |
| `gang-up.js`     | Your Pixfizz contact — always use the current build        |
| Parent snippets  | Already on the Shopper parent; a child store inherits them |

**Check the store is on the Shopper parent.** If it is, `product/gang-up`, `style/gang-up`, `style/px-tool-theme`, `style/px-notify` and `product/px-notify-boot` are all inherited and you paste nothing.

If the store has an **Override Snippet** for any of those, it is pinned to an old copy and will not pick up fixes. Remove the override.

`jszip.min.js` must also be on the parent. Without it the tool still works; only reopening a saved sheet stops working.

***

### How to set it up

#### 1. Upload the asset

Upload `gang-up.js` to **Assets** on the **parent** store. Child stores inherit it.

A copy uploaded to a child store pins that child to that version permanently. Only do that deliberately.

#### 2. Import the template

Import `template-export.tar.gz` from the setup bundle at **Admin > Products > Templates > Import**. Upload it as-is; do not unpack it.

It brings the template, its options, the product, the design and the 20-value length ladder.

**Every price in the export is 0.00.** That is deliberate — a product priced at zero is obviously not ready, whereas a product carrying somebody else's rates can reach a customer. Put your own rates in before publishing.

The template carries **eight options**. All are hidden from the customer — the tool drives every one of them.

| Code                  | Type             | Read only | What it holds                                                                          |
| --------------------- | ---------------- | --------- | -------------------------------------------------------------------------------------- |
| `gangup_artwork`      | file\_upload     | **No**    | The rendered sheet. **This is the print file, and this option also carries the mount** |
| `gangup_preview`      | file\_upload     | **No**    | The thumbnail shown on the cart line                                                   |
| `gangup_originals`    | file\_upload     | **No**    | The customer's uploaded files, as supplied                                             |
| `gangup_source`       | multiple\_choice | Yes       | `builder` or `print_ready_upload`                                                      |
| `gangup_designs`      | number           | Yes       | How many distinct designs are on the sheet                                             |
| `gangup_copies`       | number           | Yes       | How many copies in total                                                               |
| `gangup_sheet_length` | number           | Yes       | The length that was built, in inches                                                   |
| `gangup_output_dpi`   | number           | Yes       | The resolution actually achieved                                                       |

**Never set `gangup_artwork`, `gangup_preview` or `gangup_originals` to read-only.** The tool writes files to all three. A read-only file upload renders a display chip with a hidden input behind it rather than a real control, so the write does not land and nothing raises an error — the order reaches production with no print file and admin looks entirely correct.

**Check this after every import.** An unset boolean exports as the text `'false'`, which reads as true, so an option you intended to leave writable can come back effectively read-only. The checkbox looks unticked either way.

#### 3. Set the roll width

The bundle is built for a **12 inch** roll, which is also the tool's built-in default.

If you run a different width, two things must change together:

* the width setting — see the configuration reference
* all 20 `Sheet Length` value labels, which read `12 x 12 in (1 ft)`, `12 x 24 in (2 ft)` and so on

**The `12 x` in those labels is typed text.** Nothing validates it against the width the tool actually lays out at. Change one and not the other and the labels quietly lie to your customers while the sheet prints at the real width.

#### 4. Mount the tool

On the `gangup_artwork` template option, set **custom\_script**:

```liquid
{% snippet 'product/gang-up' %}
```

Nothing else renders the tool. **This is the first thing to check if it does not appear on the product page.**

#### 4a. The length variant

The product carries one variant type, `length`, hidden, with 20 values.

|             |                                                      |
| ----------- | ---------------------------------------------------- |
| Value code  | The length in whole inches: `12`, `24`, `36` … `240` |
| Value label | What the customer sees: `12 x 120 in (10 ft)`        |
| Price       | Yours to set. Ships at 0.00                          |

**The value code must be a plain number of inches.** The tool reads every code at start-up, sorts them, and rounds the sheet it has built up to the next one. A code of `10ft` or `12x120` is not a number and that value is dropped from the ladder silently.

**The longest value in the ladder is the tool's real maximum.** Whatever any other maximum-length setting says, the ladder wins. To sell longer sheets, add values — you do not need to change a setting.

Because the length is a priced variant, the platform recomputes the price and the tool's footer follows it. That is why the price moves as the sheet grows.

#### 5. Set the product and design flags

On the **product**:

* `btn_add_to_cart` checked
* `btn_design_tool` unchecked
* `requires_design` checked
* `skip_cart_redirect` checked

On the **design**:

* `cart_edit_url` set to `project-edit`, so Edit in the cart reopens this tool rather than the standard design tool
* `only_design_now` unset, or a real boolean false
* `disable_required_form` the same

**A template import can write those last two as the text `'false'` rather than the boolean.** In Liquid only `nil` and boolean `false` are falsy, so the text `'false'` reads as true. The checkbox looks unticked either way, so admin appears correct.

The symptom is that Add to Cart reads "Design Now" and opens the editor instead of the cart.

To fix it: tick the field, save, untick, save. That rewrites it as a real boolean. Do this on every design after an import.

#### 6. Send the print file to production

Without this step the order delivers nothing to production.

The print file is the `gangup_artwork` file\_upload option, and the stock `_additional_files.json` only ever delivered project images. Replace it on the fulfillment destination with a template that also walks `chosen_template_options`. Ask your Pixfizz contact for the current version — it is one block of Liquid and it is the same on every store.

What production receives is **a single transparent PNG of the whole sheet**, carrying a pHYs chunk that declares its physical size.

***

### How to check it worked

Load the product page and inspect `<div id="gu-root">`. Every setting is echoed back as a `data-` attribute, and the width and the design gate each carry a matching `-source` attribute saying where the value came from.

```
data-sheet-width          = 12
data-sheet-width-source   = site_checklist    <- or product_custom, or default
data-max-length-in        = 120
data-target-dpi           = 150
data-accept-formats       = png
data-background           = transparent
data-price-footer         = total
data-product-seen         = false
```

The browser console also prints one line at start-up:

```
[gang-up] ready { sheetWidthIn, sheetWidthSource, liquidSawProduct, mode, minLengthIn, maxLengthIn }
```

Two things about that line are worth knowing before you use it:

* **`maxLengthIn` is reported before the length ladder is read.** It shows the setting, not the effective maximum. The real ceiling is the longest value in the `length` variant. To check the effective maximum, open the builder and look at the **Buy length** picker.
* **`liquidSawProduct: false` is normal.** Product custom fields are only in scope when the page URL carries `?product=<id>`. See the configuration reference.

Then run through the tool once:

1. Open the product page and confirm Add to Cart is **disabled**.
2. Open the builder, upload a PNG, set a size and a quantity.
3. Watch the sheet length and the footer price change as you raise the quantity.
4. Confirm Add to Cart becomes **enabled**. That transition is the actual test — a button that greys out is not proof that it un-greys.
5. Place one real order and open the delivered PNG as your press operator would. Nothing short of a real order proves step 6.

***

### Tips

* **Leave the accepted formats as PNG.** JPEG cannot carry transparency. If you allow JPG, any transparent area becomes solid, and on DTF that means the whole background gets an ink and adhesive layer, which floods the film and ruins the transfer. For the same reason leave the background as `transparent`.
* **Check the achieved resolution on a long test sheet.** Browsers cap how large a canvas they will allocate, so a very long sheet is rendered below the resolution you asked for. The review step shows what was actually achieved, and it is recorded on the order in `gangup_output_dpi`. Check it before you promise a customer 300 dpi on a 20 ft run.
* **The XML definition's `dpi` is not what prints.** The tool renders at its own target resolution setting. If the two differ, the XML is the one being ignored. Set them to the same number so nobody has to work this out later.
* **Settings travel with the template.** `custom_script` is a field on the template option, and template options are included in a template export. Export a working template and the mount moves with it.

***

### Downloads

[gang-sheet-setup.zip](https://1409369501-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDLSaKAH9aauCVHoiuVBl%2Fuploads%2FFaI14do9EoiU8sMBADtK%2Fgang-sheet-setup.zip?alt=media)

The setup bundle: the template export with all prices zeroed, and a README covering import order and what to check afterwards. This is everything a lab needs.

`gang-up.js`, `product/gang-up` and `style/gang-up` are parent-side files and are not in this bundle. Ask your Pixfizz contact for the current builds.

***

### Related

* Gang Sheet tool: configuration reference
