shopify-collection-dsl

Create Custom- and Smart Collections for Shopify programmatically.

This module is using Shopify-api-node for communicating with the Shopify API.

Features:

• CustomCollection & SmartCollection
• ES8 (async/await)
• ES6 (Promises)
• Debugging (dry-run)
• Tests

Table of contents

• Use Case
• CustomCollection
  • API Reference
  • Method Reference
    • Create a CustomCollection instance
    • Set title
    • Set sort-order
    • Set scope
    • Set body (description)
    • Set image
    • Create the collection
• SmartCollection
  • API Reference
  • Method Reference
    • Create a SmartCollection instance
    • Add rule
    • Set disjunctive
• Setup / Install
• Unit-Tests
  • Make
  • NPM
• Contributing
• License

Use Case

Here at Notixbit, one of our customers wanted us to create 40+ Smart Collections including multiple rules for those collections. Using the Shopify-API was a no-brainer for us, and so we started writing a parser that would allow us to programmatically create those collections. The parser reads data from a local/remote database while provisioning the collections that are needed for the customers shop.

This module (shopify-collection-dsl) is a wrapper around Shopify-api-node, and we decided to separate it from the parser and release it as an Open Source project.

CustomCollection

API Reference

CustomCollection(
    [String=title]
) -> Object {
    /* Constants */
    this: Object=this
    opts: Object=this.opts

    /* Methods */
    title: [String=title] | this
    sort: [String=order] | this
    scope: [String=scope] | this
    body: [String=html] | this
    image: [Object=image] | this
    async create: [Shopify=shopify, Boolean=dryrun, Object=opts] | Promise
}

Method reference:

Create a CustomCollection instance

Available options:

| Argument | Description | Required | | ------ | ----------- | ------ | | title | The collection title | Yes |

const collection = new CustomCollection('my-title')

Set title

You can change the collection title by calling the .title method, too.

Available arguments:

| Argument | Description | Default | | ------ | ----------- | ----- | | title | The collection title | None |

collection.title('my-title')

Set sort-order

Available arguments:

| Argument | Description | Default | | ------ | ----------- | ----- | | order | The sort-order | manual |

Reference:

alpha-asc: Alphabetically, in ascending order (A - Z).
alpha-desc: Alphabetically, in descending order (Z - A).
best-selling: By best-selling products.
created: By date created, in ascending order (oldest - newest).
created-desc: By date created, in descending order (newest - oldest).
manual: Order created by the shop owner.
price-asc: By price, in ascending order (lowest - highest).
price-desc: By price, in descending order (highest - lowest).

See Documentation

collection.sort('alpha-asc')

Set scope

Available arguments:

| Argument | Description | Default | | ------ | ----------- | ----- | | scope | The scope | global |

Reference:

web: The custom collection is published to the Online Store channel but not published to the Point of Sale channel.

global: The custom collection is published to both the Online Store channel and the Point of Sale channel.

See Documentation

collection.scope('web')

Set body (description)

Available arguments:

| Argument | Description | Default | | ------ | ----------- | ----- | | html | The description | None |

See Documentation

collection.body('Great <b>shoes</b> for men!')

Set image

Available arguments:

| Argument | Description | Default | | ------ | ----------- | ----- | | image | The image | none |

Reference:

attachment: An image attached to a custom collection returned as Base64-encoded binary data.
src: The source URL that specifies the location of the image.
alt: Alternative text that describes the collection image.
created_at: The time and date (ISO 8601 format) when the image was added to the collection.
width: The width of the image in pixels.
height: The height of the image in pixels.

See Documentation

collection.image({
  'src': 'http://example.com/shoes.png',
  'alt': 'Shoes picture'
})

Create the collection

Available arguments:

| Argument | Description | Default | | ------ | ----------- | ----- | | shopify | Shopify module instance | none | | dryrun | Whether to debug the request | false | | opts | Override internal this.opts | this.opts |

await collection.create(shopify)

// or

collection.create(shopify)
  .then()
  .catch()

To debug (dry-run) the payload for the request, simply pass true to the .create method.

const payload = await collection.create(shopify, true)
console.log(payload)

SmartCollection

API Reference

SmartCollection extends CustomCollection(
    [String=title]
) -> Object {
    /* Constants */
    this: Object=this
    opts: Object=this.opts

    /* Methods */
    title: [String=title] | this
    sort: [String=order] | this
    scope: [String=scope] | this
    body: [String=html] | this
    image: [String=image] | this
    rule: [String=column, String=relation, String=condition] | this
    disjunctive: [] | this
    async create: [Shopify=shopify, Boolean=dryrun, Object=opts] | Promise
}

Method reference:

A SmartCollection instance inherits all CustomCollection methods, including two additional methods.

Create a SmartCollection instance

Available options:

| Argument | Description | Required | | ------ | ----------- | ------ | | title | The collection title | Yes |

const collection = new SmartCollection('my-title')

Add rule

You can set multiple rules for your Smart Collection.

Available arguments:

| Argument | Description | Default | | ------ | ----------- | ----- | | rule | The rule | None |

See Documentation

collection.rule('title', 'contains', 'shoes')

Chain them like so:

collection
  .rule('title', 'contains', 'shoes')
  .rule('vendor', 'equals', 'Nike')

Set disjunctive

If this method is called, the internal opts.disjunctive is set to true, otherwise it is set to false.

true: Products only need to match one or more of the rules to be included in the smart collection.
false: Products must match all of the rules to be included in the smart collection.

See Documentation

collection.disjunctive()

Setup / Install

Use npm install @notixbit/shopify-collection-dsl

const { 
  Shopify, 
  CustomCollection, 
  SmartCollection 
} = require('@notixbit/shopify-collection-dsl')

const shopify = new Shopify({
  'shopName': 'your-shop',
  'apiKey': 'your-key',
  'password': 'your-pw'
})

// Now you can create Custom Collections...
const collection = new CustomCollection('my-collection')

await collection
  .body('Great products for young people')
  .sort('best-selling')
  .create(shopify)

// ... and/or Smart Collections

const collection = new SmartCollection('my-collection')

await collection
  .body('Great products for young people')
  .sort('best-selling')
  .rule('title', 'contains', 'shoes')
  .rule('vendor', 'equals', 'Nike')
  .disjunctive()
  .create(shopify)

Unit-Tests

The testing-framework used in this module is Mocha with the BDD / TDD assertion library Chai.

• test/test.default.js Performs 4 tests | Source

Output using Mocha list reporter:

Default reporter: list

Make

make test

NPM

npm test

Contributing

You're very welcome and free to contribute. Thank you.

License

MIT