OS 2.1 to 3.0 Migration Guide for Private Themes – SHOPLINE Help Center

If you're currently using a private theme built on OS 2.1 and plan to upgrade to OS 3.0, this guide will walk you through the full migration process. It includes feature comparisons, syntax changes, plugin compatibility, multilingual configuration, UGC data migration, and important precautions. This version has been optimized for readability and clarity.

Migration Benefits Overview

When to Use:

This applies to merchants who have already developed and launched a private theme on OS 2.1 and plan to upgrade to OS 3.0 to benefit from a more unified architecture, enhanced functionality, and long-term performance improvements.

Comparison Area	OS 2.1 Private Theme	OS 3.0 Private Theme (Post-Migration)
System Architecture	Legacy system, nearing sunset	New architecture with ongoing improvements
Template Syntax	Handlebars	Sline (faster rendering, unified debugging)
Multi-language/Market	Limited flexibility	Full support for primary market, multi-language
Template Management	Single template support	Master and sub-template management
Module Configuration	Dispersed features	Stronger modular structure with nested support
Rendering Performance	Basic	Faster compilation and better performance
Plugin Compatibility	Heavy reliance on custom plugins	More native features and unified integration
Future Development	Maintenance only	Core innovations will focus on 3.0

Syntax Differences and Migration Guide

When migrating from a 2.1 private theme to OS 3.0, you will need to fully convert Handlebars template syntax to Sline. See the syntax comparison below:

Comparison Item		Handlebars (OS 2.1)	Sline (OS 3.0)
Data Context		Manual or inconsistent	Unified data structure
String	Single quotes	Multiple characters:`'str'`	Used only for single characters: `'a'`
	Double quotes	Multiple characters:`"str"`	Multiple characters:`"str"`
	Backticks	Not supported	Multiple characters: `str`
Scope	`this`	`{{ this.title }}`	`{{ title }}`
	`./`	`{{ ./title }}`	`{{ title }}`
	`../`	`{{ ../title }}`	Cannot access variables in the parent scope
Expression	Array indexes	`{{ products.[0].title }}`	`{{ products[0].title }}`
Expression	Variable access	`{{ get key (get index products) }}`	`{{ products[index][key] }}`
Comments		`{{!-- This is a comment --}}` `{{#comment}} Comments {{/comment}}`	`{{!-- This is a comment --}}`
Extended capability	Helper	Single line:`{{capitalize "test"}}` Block:`{{#if true}} OK {{/if}}`	Use tags/filters instead
	Tag	Not supported	Self-closing:`{{#component "a" /}}` Block:`{{#if true}} OK {{/if}}`
	Filter	Not supported	`{{ "a,b,c" \| split(",") \| join("-") }}`

Plugin Compatibility Overview

When to Use:

If third-party plugins were installed in your 2.1 private theme, you’ll need to confirm whether they are compatible with the 3.0 theme before migration.

Recommended Actions:

List all active plugins and cross-check with the official compatibility list.
Refer to the official plugin compatibility list (available from your Customer Success Manager).
If a plugin is not yet supported in OS 3.0, evaluate whether a built-in system feature provides equivalent functionality, or contact the plugin provider for support.
For plugins that are no longer compatible, consider removing them or developing a custom replacement.

Notes:

Plugins may differ in UI/UX behavior and data structure between OS 2.1 and OS 3.0.
It is strongly recommended to test plugin functionality thoroughly on a staging site before going live.

Multilingual Configuration Migration

When to Use:

If your 2.1 theme has multi-language content, ensure field structures remain intact in OS 3.0.

Steps:

Review translation fields in all rich text and module configurations.
Use the UGC Multi-Language Translator plugin to assist with migration.
Start validation from the primary market's default language.

Notes:

The translation logic in the theme editor remains largely unchanged.
Language switching still relies on the system translation module.
Nested rich text structures may behave differently in Sline—manual checks are recommended.

UGC Components Migration

When to Use:

If UGC are used in your 2.1 theme, they must be manually migrated to OS 3.0.

Steps:

Export each UGC's JSON configuration from the settings page before migration.
Recreate matching component structures in the OS 3.0 theme.
Import the JSON files into the new UGCs and bind them to your theme.

Notes:

Automatic migration is not supported.
Ensure full data export before starting.
Use consistent naming to ensure smooth binding and rendering.

Risks and Precautions

All Handlebars code must be manually rewritten using Sline syntax.
Confirm plugin compatibility in advance and prepare alternatives.
Market-specific localization for headers, footers, and global settings is not yet supported.
Recommended for merchants with developer support.
Strongly advised to test the full process in a staging environment before going live.
All UGC data must be exported, rebuilt, and reconnected manually.