Skip to main content

Working with CrystalHelper plugin

Set up the CrystalHelper plugin on your blog

Written by Matthew Schwartz

What is the CrystalHelper plugin?

The CrystalHelper plugin allows you to easily insert deck lists, grids, and product links in your WordPress blog posts. The inserted elements will link to those products on your CrystalCommerce store.

Limitations:

  • Because the plugin uses our global catalog, it is not compatible with custom products which are unique to your store's inventory database.

  • The plugin is not compatible with 3rd party page builder plugins such as Elementor, Beaver Builder, etc. It only works with the built-in, default WordPress block editor. You can work around this with various plugins and complex workflows, but we don’t offer support for doing that.

  • Because of the point above, you will need to make all of your blog posts / articles using the built in WordPress block editor, so you can include product displays in your posts.

  • If you want a single product link, inline in a paragraph of text, you should use the "Classic block" in your post / page, and then use the WYSIWYG plugin icon to embed the link into your text. See more info later in this article.

  • The keyboard shortcuts for the plugin only work when editing within a "Classic" block.

Updates:

Version 2.0.0 released October 15th, 2024

This version has some bug fixes to bring it back to full functionality and compatibility with current versions of WordPress and other plugins. If you have an older version of the plugin, some of the things described in this help article may not work properly.

Old versions of the plugin will need to be manually updated by deactivating and then deleting the old version, then uploading and activating the new version. To get the new version zip folder to upload, or for help with any of this, please contact the support team.

Example of Decklist (Newer version of plugin)

WordPress Admin Plugin Interface Example

Plugin Versions

Legacy
This plugin works with WordPress versions prior to 5.0 (which uses the Classic Editor for posts). The legacy version of the plugin is no longer available.

New
This plugin works with WordPress versions 5.0+ (which uses the Gutenberg / Block Editor).

Current version: 2.0.0 (Released 2024-10-15)

If you have an old version of the plugin, some of the things described in this help article may not work properly. We suggest updating your old version to the newest version. Contact the support team for assistance.

Updates/features in newer version:

  • Gutenberg blocks for Crystal Helper Products (List, Grid, Single*)

  • Improved appearance of “Shop Now” buttons on product hover

  • Improved appearance of “Buy this List” button

  • Improved plain text list features (“View Plain Text” / “View Formatted” toggle button, “Copy List” button)

  • *Single product block will insert the product name on its own line. If you need the text to be inline within a paragraph, you’ll need to use a “Classic” block for the paragraph text and insert the product link with the legacy plugin icon in the WYSIWYG bar. (See instructions earlier in this help article)

How do I install and set up the plugin?

When you sign up for a blog site with CrystalCommerce, the CrystalHelper plugin will come pre-installed and configured. If you need or want to adjust these settings, see the configuration instructions, later in this article.

If, for some reason, the plugin is not installed, please contact your account representative.
​

I made my own WordPress blog. How do I get the plugin?

Please contact the support team for assistance.

How do I Configure the plugin settings?

Sign in to your WordPress admin area
​
Click the "Crystal Catalog Helper" link which you'll find in the main WordPress menu

Store URL

The store URL  is used to generate the URL to which the inserted products will link to. Make sure the link is correct and that you test it, or else all of your product links in your posts will not work.

The store URL link should be formatted like: http://mystore.crystalcommerce.com, where "mystore" is your CrystalCommerce Database name.

IMPORTANT: If you use your own domain name (mystore.com) or any other URL other than your unique CrystalCommerce store URL, and you ever change your domain name / website address, all of the inserted CrystalHelper links will no longer work because they'll be pointing to the old domain / site. In that case, you'd need to do a find & replace within the WordPress database to update all the old URLs to use your new website domain / URL. If you use your CC URL (mystore.crystalcommerce.com) then the product links will not break, even if you change your main site domain. However, customers will be taken to the product pages on the cc subdomain instead of your main vanity domain. This may affect analytics and other things you are tracking on your vanity domain.

NOTE: The screenshot below shows http, but you should use https. Also, you may use your own domain / vanity domain URL instead of the CC subdomain URL, but see the above notes for caveats and considerations.

Default Product Type ID
​

There are two options for this field:

Option 1: Enter a product type ID
If a product type ID is entered in this field, the CrystalHelper plugin will only search for products within that category. You'll want to use this option if you're only going to use the plugin for one category of products (for example, Magic the Gathering).

Pros:

  • The search is faster

  • The products results will be more relevant

Cons:

  • You'll need to update the product type ID number field every time you want to search within a different category.

Option 2: Leave it blank
If this field is left blank, the plugin will search within, and show product results from, the entire CrystalCommerce catalog.

Pros:

  • You can find products from any category (MTG, Yu-Gi-Oh!, etc)

Cons:

  • The search will be slower

  • If there are many matching results it may be difficult to navigate them

Commonly used product type ID numbers

  • Magic Singles: 208

  • Yugioh Singles: 232

  • Cardfight Vanguard: 139

  • Pokemon Singles: 236

How do I add products to a post or page?

NOTE: If you want to use the CrystalHelper plugin on a particular page or post, you must create and edit that page or post using the built in WordPress editor. You cannot use this plugin on a post or page created with Elementor or any other page builder.

New Plugin (WordPress versions 5.0+, with Gutenberg block editor)

Sign in to your WordPress admin

Navigate to the post or page editing area

To insert a List Product block, Grid Product block, or Single Product block on its own line, you'll use the "Add block" menu.

  1. Find and click the (+) icon to Add a Block, or enter into a new link and press / to open the block search popup

  2. In the block popup, find the Crystal Helper section and expand it, or search for "product"

  3. Click the option for which product block you'd like to add

  4. When the new block is added to the page, you'll need to click the 'pencil' icon to open up the Crystal Helper popup. Instructions continued below the screenshot...

For Single Product block

Note: the steps below only apply if you want the single product on its own line. If you want the link to be inline within a paragraph of text, you need to use a "Classic block." More info on that later.

  1. Within the popup, type the product name

  2. Select from the displayed results

  3. If desired, adjust the "Displayed text"

  4. Click "Insert Into Post"

For List Product block

  1. Within the popup, if desired, add a Sublist title (you can add as many as needed)

  2. Manually add individual products and quantities (not pictured below) or paste a pre-made list in the larger box and then click "Add to preview" (see example below)

  3. If desired, rearrange sublist titles and products in the Preview area by dragging and dropping them.

  4. When you're done creating the list, click "Insert Into Post"


​For Grid Product block

  1. Within the popup, manually add individual products or paste a pre-made list in the larger box and then click "Add to preview"

  2. If desired, rearrange the products in the Preview area by dragging and dropping them.

  3. When you're done creating the grid, click "Insert Into Post"

Single Product link within a paragraph

If you'd like to insert a Crystal Helper Single Product link within a paragraph of text, instead of on its own line, you'll use the Classic block instead of the Crystal Helper block:

  1. Click the (+) icon in Gutenberg to add a new block.

  2. In the "Add Block" popup, search for the "Classic" block

  3. Click the icon to add a classic block

  4. Type or paste your paragraph text within the Classic block

  5. Highlight the portion of the text that you'd like to link to the Crystal Helper product (see screenshot)

  6. Click the "Single Product" icon in the WYSIWYG bar of the Classic block (highlighted in screenshot below). or use either of the keyboard shortcuts: alt+1 or alt+s

  7. Type the product name

  8. Select from the displayed results

  9. If desired, adjust the "Displayed text"

  10. Click "Insert Into Post"

Note: Version 2.0.0 of the plugin now allows the use of any of the three product displays within a classic block (in some old versions of the plugin, the classic block did not always work with the list and grid displays)

Legacy Plugin (WordPress versions before 5.0, with classic editor)

Sign in to your WordPress admin

Navigate to the post or page editing area

Single Product (alt+1 or alt+S)

The first icon is for inserting a single product. It displays as a text link, and on hover it shows the product image.

How to insert a Single Product

  1. Place your mouse cursor in the post editing window, where you want the item to be inserted.

  2. Click the Single Product icon or use the keyboard shortcut

  3. Type the product name

  4. Select from the displayed results

  5. If desired, adjust the "Displayed text"

  6. Click "Insert Into Post"

Product List (alt+2 or alt+L)

The second icon is for inserting a deck list or generic list. It displays as a list of text links, with quantities (option), and a single preview image on the side.  As the items in the list are hovered upon, the preview image updates to show the current item.

How to insert a product list

  1. Place your mouse cursor in the post editing window, where you want the list to be inserted.

  2. Click the List icon or use the keyboard shortctut

  3. If desired, add a Sublist title (you can add as many as needed)

  4. Manually add individual products and quantities (not pictured below) or paste a pre-made list in the larger box and then click "Add to preview" (see example below)

  5. If desired, rearrange sublist titles and products in the Preview area by dragging and dropping them.

  6. When you're done creating the list, click "Insert Into Post"

Product Grid (alt+3 or alt+G)

The third icon is for inserting a Grid. It displays as a grid of large images, 4 across per row, and as many rows as you want.

How to add a product grid

  1. Place your mouse cursor in the post editing window, where you want the grid to be inserted.

  2. Click the Grid icon or use the keyboard shortctut

  3. Manually add individual products (not pictured below) or paste a pre-made list in the larger box and then click "Add to preview" (see example below)

  4. If desired, rearrange the products in the Preview area by dragging and dropping them.

  5. When you're done creating the grid, click "Insert Into Post"

How do I edit existing items which I've inserted with the plugin?​

New Plugin (WordPress versions 5.0+, with Gutenberg block editor)

  1. Make sure the block you want to edit is active by clicking within the block bounds (but not on a product or link)

  2. To remove the entire block: click the triple-dot icon for more options, then select "Remove Block." To edit the block: click the 'pencil' icon on the block to reopen the Crystal Helper popup

  3. Make edits as needed

  4. Insert into Post

Legacy Plugin (WordPress versions before 5.0, with classic editor)

  1. In the post or page editor window, find the existing single product, list, or grid 

  2. Hover over the item so the background becomes blue.

  3. To delete the entire inserted element, click the red "x" that appears when hovering. To edit the inserted element, click within the blue area.

  4. The plugin interface will pop up and you'll be able to edit the items

Troubleshooting

When I type a search term, it's not found

  • Check the plugin configuration settings to be sure you have the correct product type ID set.

  • Make sure the item you're looking for is not a custom product. (Only products in CrystalCommerce's global catalog are searchable with the CrystalHelper plugin)

  • If you believe you're doing everything correctly, but the plugin is not returning the expected search results, please contact our support team so we can look into the issue.             

                    

I cannot figure out how to embed full categories, or embed a checkout

  • You cannot embed categories.

  • You cannot embed any store functionality.

Did this answer your question?