Login
Get Started

Configuring Custom Modules

[mirrorpress_documentation_nav]

SirSync automatically recognizes common media fields used by supported WordPress editors and page builders. Custom shortcodes, widgets, and builder modules may store attachment IDs or media URLs in fields that SirSync cannot safely identify automatically.

Rules & Custom Mapping lets you identify these custom media fields. During synchronization, SirSync can then collect the referenced Media Library item and replace its original attachment ID or URL with the corresponding value on the receiving website.

Custom mapping rules currently support media references only.

When Custom Media Rules Are Needed

You may need a custom mapping rule when a custom or third-party module synchronizes successfully but one of its media references does not update correctly.

Common signs include:

  • An image continues to load from the original website.
  • An attachment ID points to the wrong Media Library item on the receiving website.
  • A background image or video poster is missing.
  • A gallery or repeating module contains incorrect images.
  • A custom shortcode or widget stores media in a field SirSync does not recognize automatically.

A mapping rule does not install or recreate the shortcode, widget, block, or module. The theme or plugin that provides the feature must already be installed on the receiving website. The rule only tells SirSync which stored field contains media that must be collected and remapped.

Open Rules & Custom Mapping

In the WordPress dashboard, go to SirSync > Rules & Custom Mapping.

From this screen, you can:

  • Scan website content for shortcode attributes that may contain media references.
  • Add custom media mapping rules manually.
  • Exclude attributes that should never be interpreted as media.
  • Activate, deactivate, or delete existing rules.
  • Import and export rule sets.
  • Push the saved configuration to the connected website.

Scan the Website for Possible Media Fields

Use Scan Site to search existing shortcode content for attributes whose values resemble attachment IDs or media URLs.

Scan results are grouped by shortcode and can include:

  • The shortcode tag
  • The candidate attribute
  • An example value found in the content
  • An Add Rule action

Scanning only identifies possible media fields. It does not determine what every ID or URL represents, and it does not automatically create or save rules.

Add a Rule From the Scan Results

  1. Click Scan Site.
  2. Locate the appropriate shortcode in the scan results.
  3. Review the attribute and its example value.
  4. Confirm that the value represents an item in the WordPress Media Library.
  5. Click Add Rule.
  6. Review the rule under Custom mapping rules.
  7. Click Save Rules.

Add a Rule Manually

Custom Elementor, WPBakery, and SiteOrigin modules may store their settings in structured builder data and may not appear in the shortcode scan. You can add these media fields manually when you know the module identifier and field structure.

  1. Select the appropriate builder or detection scope.
  2. Click Add Rule.
  3. Enter the shortcode tag or widget type when required.
  4. Enter the attribute name or field path containing the media reference.
  5. Leave the rule set to Active.
  6. Click Save Rules.
  7. Synchronize a content item containing the module and review the result.

Mapping Elementor Widget Fields

For a custom Elementor widget, enter the widget’s registered technical type and the path to the setting containing the media reference. The technical widget type may differ from the label shown in the Elementor editor.

Simple fields can use their setting name:

  • hero_image
  • background_image
  • video_poster

For media stored inside nested or repeating settings, use a field path:

  • hero.background_image
  • slides.*.image_id
  • items.*.video_url

The * segment matches every item in a repeating collection. For example, slides.*.image_id processes the image_id value in each slide.

Mapping SiteOrigin Widget Fields

Custom SiteOrigin widgets may store media within their widget settings. Add the field name or supported field path containing the attachment ID or Media Library URL.

The rule should identify only the field containing media. Post selections, page selections, form IDs, and other content references should not be added as custom media rules.

Supported Media Values

Custom mapping rules can be used for supported media values such as:

  • A single attachment ID
  • Comma-separated attachment IDs
  • A single Media Library URL
  • Comma-separated Media Library URLs
  • Supported arrays containing attachment IDs or media URLs

When SirSync encounters a mapped field, it collects or matches the referenced Media Library item. It then replaces the source attachment ID or URL with the corresponding value on the receiving website.

Values That Should Not Be Mapped

Do not create custom media rules for:

  • Post, page, product, or custom post type IDs
  • Form IDs
  • Template IDs
  • Taxonomy term IDs
  • User IDs
  • Layout dimensions or spacing values
  • Animation durations or delays
  • Slider speeds or item counts
  • External URLs that do not identify WordPress Media Library items
  • Other plugin-specific object IDs

SirSync includes built-in handling for some known content and template references. Custom mapping rules do not extend that handling to arbitrary post or plugin object IDs.

Never Treat These Attributes as Media

Use Never treat these attributes as media to exclude fields that may contain numeric values but do not represent WordPress attachments.

Enter one pattern per line. You can use an exact attribute name or a prefix followed by a wildcard:

  • form_id
  • post_id
  • padding
  • offset*

An exact pattern excludes only that attribute. A pattern such as offset* excludes every attribute whose name begins with offset.

This safety list is useful for form identifiers, content selections, layout settings, timing values, and other fields that might otherwise resemble attachment IDs.

Activate, Deactivate, or Delete a Rule

Use the Active setting to enable or disable a rule. A deactivated rule remains in the configuration but is not used during synchronization.

Use Delete to remove a rule. Click Save Rules after activating, deactivating, editing, or deleting rules.

Push Rules to the Connected Website

Custom rules are website settings and are not automatically included when synchronizing a page or post. Use Push Rules to Remote when the connected website should use the same configuration.

  1. Finish adding or editing the rules on the current website.
  2. Click Save Rules.
  3. Click Push Rules to Remote.

Pushing rules replaces the remote website’s existing rule configuration. If the remote website has unique rules that must be retained, export or record them before pushing the replacement configuration.

Export Rules

Click Export to download the custom mapping rules as a JSON file. Exporting is useful for:

  • Backing up a rule set
  • Moving rules between websites that are not connected
  • Sharing rules across multiple environments
  • Saving the current rules before troubleshooting or replacing them

Save recent changes before exporting.

Import Rules

Click Import and select a previously exported SirSync rules file. Imported rules are added to the rules currently displayed; they do not automatically remove existing rows.

  1. Click Import.
  2. Select the exported JSON file.
  3. Review the imported rules for duplicates or conflicts.
  4. Delete or deactivate any rules that should not be used.
  5. Click Save Rules.

Imported rules do not take effect until you click Save Rules.