Structure of a custom section project

Every Instant Site section project has the same file structure. The actual section code is stored inside the sections/{section_name} folder.

As you start building custom sections, you create a local project with the @lightspeed/crane module. Inside this project, you’ll find a .Vue file and three folders, including the example-section template. Let's use it to cover the project file structure.

Section contains the following files:

• settings/content.ts - Declares name and type for interactive elements available to users in the Instant Site Editor. Element examples: input field, image uploader, button, drop-down list, etc.
• settings/design.ts - Adds design settings for elements declared in the 'content.ts' file. Such settings include colors, font size, description, options, etc.
• settings/translations.ts - Describes translations for text labels used in the 'content.ts' and 'design.ts' files. Can contain one or several languages.
• showcases/{id}.ts - Describes section preview and default settings combination to showcase the section. You can add several such files to show different use cases for the section.
• showcases/translations.ts - Describes translations for labels used in showcases files.
• assets/{file} - Folder for section preview images, other images, or other files that need to be used as assets inside your section.
• ExampleSection.vue - Contains section code that loads on the storefront and in the Editor preview. Works on the Vue framework. Includes elements described in the 'content.ts' file, plus design settings and translations.

Generally, with files in the "settings" folder, you can declare, describe, and configure available settings that users will see in the Instant Site Editor. This way, you allow them to personalize the Instant Site section you develop for their business needs. With files in the "showcases" and "assets" folders, you can craft one or several previews for your section.

All the project files listed above are mandatory. However, you are not limited to them. If you want to split the Vue file into several or declare additional variables in separate TypeScript files, you are free to do so.

'content.ts'

This file declares the settings users see in the Instant Site Editor when they install the section. For example, if you need an input field where users enter a greeting text, don't develop it from scratch and use the INPUTBOX element from Ecwid. You only need to declare this element once, then you can add a set of design settings and text translations for it, and call it in the section code file with ease.

We refer to such elements with different functionality as types. Combined, these element types allow you to set up rich customization options for the section.

• INPUTBOX - Single-line input field.
• TEXTAREA - Multi-line input field.
• BUTTON - Configurable button with several available actions: Scroll to the section, Go to the link, Compose an email, Call phone, Go to the store, Go to the site page.
• IMAGE - Image uploader.
• TOGGLE - On/Off toggle.
• SELECTBOX - Drop-down list where users choose one of the available options.
• INFO - Pre-defined text with an optional button.

In the 'content.ts' file, you declare element ID, its type, text label, and placeholder with the following fields:

How it looks in the code:

export default {
	element_id: {
		type: 'INPUTBOX',
		label: '$label.section_description.label',
		placeholder: '$label.section_description.placeholder',
	},
} as const;

How it looks in the Editor:

You can declare multiple elements of the same type with different IDs. The element_id in the example above declares the element ID that will be referred to in other files.

Check out the example section code you get from crane tool. It declares several elements and uses them across the project.

'design.ts'

Once you declare user settings to the 'content.ts' file, define design settings for these elements. Design settings are also based on different types pre-defined by Ecwid. Each design type has its unique configuration. For example, when you add an INPUTBOX input text field that can be interacted with through the Editor, you can also give users the ability to change text color and size.

Configuration defined in the 'design.ts' file will appear in the IS Editor when users install the section. Find the full list of design types and their configs below.

How it looks in the Editor:

TEXT

Configuration for text elements.

Code example for 'design.ts':

element_id: {  
	type: 'TEXT',
	label: '$label.element_id.label', 
	colors: ['#FFFFFF66', '#0000004D', '#00000099', '#64C7FF66', '#F9947266', '#C794CD66', '#FFD17466'],
	sizes: [12, 13, 14, 15, 16, 17, 18, 20],
	defaults: {
		font: 'global.fontFamily.body',
		size: 16,
		bold: false,
		italic: true,
		color: '#333',
}

BUTTON

Configuration for button element.

Code example for 'design.ts':

element_id: {  
	type: 'BUTTON',
	label: '$label.element_id.label',
	colors: ['#FFFFFF66', '#0000004D', '#00000099', '#64C7FF66', '#F9947266', '#C794CD66', '#FFD17466'],
	defaults: { 
		font: 'global.fontFamily.body',
		size: 'MEDIUM',
		appearance: 'OUTLINE',
		shape: 'PILL',
		color: '#333',
	},  
}

IMAGE

Configuration for image uploader element.

Code example for 'design.ts':

element_id: {  
	type: 'IMAGE',
	label: '$label.element_id.label',
	colors: ['#FFFFFF66', '#0000004D', '#00000099', '#64C7FF66', '#F9947266', '#C794CD66', '#FFD17466'],
	defaults: { 
		overlay: 'COLOR',
		color: '#333',
	},  
}

TOGGLE

Configuration for toggle element.

Code example for 'design.ts':

element_id: {  
	type: 'TOGGLE', 
	label: '$label.element_id.label',
	description: '$label.toggle.description', 
	defaults: {
		enabled: true,
	},  
}

SELECTBOX

Configuration for the "selectbox" element that creates a drop-down list in the Editor.

Code example for 'design.ts':

element_id: {  
	type: 'SELECTBOX',
	label: '$label.element_id.label',
	placeholder: '$label.element_id.placeholder',
	description: '$label.element_id.description',
	options: [
		{  
			value: 'one',
			label: '$label.element_id.one.label',
		},  
		{  
			value: 'two',  
			label: '$label.element_id.two.label',  
		},  
	],  
	defaults: { 
		value: 'two',
	},  
}

BACKGROUND

Configuration for the section background which is not an element type defined in the 'content.ts' file.

Code example for 'design.ts':

element_id: {  
	type: 'BACKGROUND',
	label: '$label.element_id.label',
	colors: ['#FFFFFF66', '#0000004D', '#00000099', '#64C7FF66', '#F9947266', '#C794CD66', '#FFD17466'],
	defaults: {
		style: 'COLOR', 
		color: 'global.color.background',
	},  
}

COLOR_PICKER

Configuration for a color picker which is not an element type defined in the 'content.ts' file.

Code example for 'design.ts':

element_id: {  
	type: 'COLOR_PICKER',
	label: '$label.element_id.label',
	description: '$label.element_id.description',
	colors: ['#FFFFFF66', '#0000004D', '#00000099', '#64C7FF66', '#F9947266', '#C794CD66', '#FFD17466'],
	defaults: {
		color: 'global.color.background',
	},  
}

'translations.ts'

Once your section has text labels for elements inside the 'content.ts' and 'design.ts' files, you can add one or several translations for them in the 'translations.ts' file. The 'translations.ts' file in the "showcases" folder does the same, but only for text labels used in showcase files.

The 'translations.ts' file has a simple structure: declare an object named with a language code, for example, en: {} and put '$label': 'text' pairs inside. Labels in this file are referred to the same way as in other files. For example, if you added $label.inputbox_1_name in the 'content.ts' file, call it the same in 'translations.ts'.

Code example:

en: {
	'$label.inputbox_1_name': 'Title',
	'$label.inputbox_1_desc': 'Description',
	'$label.color_picker_name': 'Select color for the navigation arrows',
},
es: {
	...
},
nl: {
	...
}

If you add several translations, make sure that every language has the same set of text labels. Otherwise, you may face errors when deploying the section to Ecwid.

Check out the example section from the crane tool. It has working 'translations.ts' files for both "settings" and "showcases" folders.

'showcases/{id}.ts'

Showcase files allow you to set up a preview for the section browser and default settings for that preview. For example, an image gallery block can have two showcases, showing the "summer collection" in the first showcase and the "winter collection" in another.

Showcase configuration includes:

Showcase files don't have to cover all declared content and design settings. Additionally, you can add several images for one IMAGE element type depending on the user's device and screen size.

Code example for 'showcase/1.ts' file:

showcaseId: '1',
previewImage: {
	set: {
		ORIGINAL: {
			url: 'preview_image.jpg',
		},
	},
},
blockName: '$label.showcase_1_name',
content: {
	text_input_1: {
		type: 'INPUTBOX',
		text: '$label.showcase_1_input_1',
	},
	text_input_2: {
		type: 'TEXTAREA',
		text: '$label.showcase_1_input_2',
  },
  image_content_1: {
		type: 'IMAGE',
		imageData: {
			set: {
				ORIGINAL: {
					url: 'new_arrivals_pc_high.jpeg',
				},
				MOBILE_WEBP_LOW_RES: {
					url: 'new_arrivals_mobile_low.jpeg',
				},
				MOBILE_WEBP_HI_RES: {
					url: 'new_arrivals_mobile_high.jpeg',
				},
				WEBP_LOW_RES: {
					url: 'new_arrivals_pc_low.jpeg',
				},
				WEBP_HI_2X_RES: {
					url: 'new_arrivals_pc_high.jpeg',
				},
			},
			borderInfo: {},
		},
	},
design: {
	text_input_1: {
		type: 'TEXT',
		font: 'global.fontFamily.body',
		size: 44,
		bold: true,
		italic: false,
		color: '#333',
	},
	background: {
		type: 'BACKGROUND',
		style: 'COLOR',
		color: 'global.color.background',
	}
}

'server.ts', 'client.ts', 'type.ts'

These are internal files, but there is one thing you need to keep in mind. If you change the name of the main .vue file, update it in the 'server.ts' and 'client.ts' files.

Code example:

import ExampleSection from './ExampleSection.vue'; // default
import MySection from './MySection.vue'; // updated

The 'type.ts' should remain unchanged.

'section.vue'

This is the main building file for the section code, where you import settings added in the 'content.ts' and 'design.ts' files. Our crane tool provides you with an easy way of importing content to .vue files.

Code example:

import { useImageElementDesign, useSelectboxElementDesign, useTextElementDesign } from '@lightspeed/crane';
import { useImageElementContent, useInputboxElementContent, useTextareaElementContent } from '@lightspeed/crane';

const imageText1 = useTextareaElementContent<Content>('image_text_1');
const imageContent4 = useImageElementContent<Content>('image_content_4');
const imageLink1 = useInputboxElementContent<Content>('image_link_1');

const textDesign = useTextElementDesign<Design>('image_text');
const imageDesign = useImageElementDesign<Design>('image_content');
const positionDesign = useSelectboxElementDesign<Design>('image_text_position');

Your IDE should also highlight syntax and show fields available inside constants declared this way.

Summary

Let's combine what we've learned. With the crane tool you can start building custom sections for Instant Site with ease. The tool allows you to get an example section code to learn its structure and see how it works, to deploy built sections to Ecwid, and to effortlessly create a set of settings for the Instant Site editor, so users could tune the section to their own preferences and needs.

To create a fully working setting, first declare it in the 'content.ts' file:

export default {
  user_input_1: {
    type: 'INPUTBOX',
    label: '$label.user_input_1.label',
    placeholder: '$label.user_input_1.placeholder',
  },
} as const;

Then define what design settings should be available for it in the 'design.ts' file:

export default {
  user_input_1: {
    type: 'TEXT',
    label: '$label.user_input_1.label',
    colors: ['#FFF', '#000', '#333'],
    sizes: [18, 20, 22, 24, 26],
    defaults: {
      font: 'global.fontFamily.body',
      size: 20,
      bold: true,
      italic: false,
      color: '#333',
      visible: true,
    },
  } as const;

Then import the created setting into the .vue file:

import { useInputboxElementContent, useTextElementDesign } from '@lightspeed/crane';

const userInput1 = useInputboxElementContent<Content>('user_input_1');
const userInput1Design = useTextElementDesign<Design>('user_input_1');

Now you can add a set of user settings for your section and use these settings in the code. We are excited to see what you'll be able to build!