Constants

Once the technical aspect, which is detailed in the getting started guide, is wrapped up, it's time to tackle some configuration options that shophub offers. This part will cover editing the constant files of shophub.

Frontend path

 src/constants

Backend path

 src/util/constants.ts

Frontend constants

BlurPlaceholderB64

A base64 image string that is used as blur placeholder image, when images are loaded and they don't provide their own blur base64 string. The original image should be around 10x10 pixels in size.

export const BlurPlaceholderB64 =
  'data:image/png;base64,abcdefgh=';

ComponentSizeOptions

Component size options are used for rendering CMS banners. Those settings define the sizes, the banners orientate themselves on. small, base, medium and large size options are set on banner creation.

The size option is currently available for the AnnouncementBanner, FunnelBlock and SmallFunnelBlock.

const ComponentSizeOptions = {
  AnnouncementBanner: {
    small: '2.75rem',
    base: '3.5rem',
    medium: '4.8rem',
    large: '10rem',
  },
  FunnelBlock: {
    small: '300px',
    base: '400px',
    medium: '650px',
    large: '900px',
  },
  SmallFunnelBlock: {
    small: '150px',
    base: '250px',
    medium: '350px',
    large: '600px',
  },
};

DeliveryDatePicker

Attributes related to the configuration of the delivery date picker, that is used in the cart. As on the current version of shophub, this config object also needs to exist in as constant in the backend. There it is used as validation of the incoming data.

DeliveryDatePickerConfig type & example

type DeliveryDatePickerConfig = {
  /** Key value that is displayed in the admin UI as additional information. */
  attributeName: string;
  /** Format of the date that is displayed in the shopify admin UI. This should ideally be standardized. */
  displayLocale: string;
  /** Amount of days that need to be between the order date and the selected delivery date.
   * If next day delivery is enabled, this option is ignored.
   * */
  earliestDeliveryDate: number;
  /** Defines the number of days up to which a customer can select the day for delivery.
   * The range starts counting from the moment/day the user wants to select a delivery date.
   * */
  latestDeliveryDate: number;
  nextDayDelivery: {
    /** The timezone from which the current time is calculated to check if the hour is before the given until value. */
    originTimezone: Timezones;
    enabled: boolean;
    /** Defines the hour of the day until next day delivery is selectable. */
    until: number;
  };
  /** A list of weekdays days that are always disabled. Then range goes from 0-6, with 0 being sunday and 6 being saturday.
   * [0,1,6] For example would equal Sunday, Monday and Saturday being always blocked.
   * To allow all days, set to empty array.
   * */
  disabledWeekdays: Array<number>;
  /** If enabled, block all holidays in (currently) germany from being selectable. */
  disableHolidays: {
    enabled: boolean;
    /** For each or all german states can be configured to be blocked on that day and a flexible amount of days after.
     * The higher amount of block days will always override rules with a smaller amount of days blocked.
     * */
    states: Array<{
      state: Region;
      daysBlockedAfter: number;
    }>;
  };
};
 
/* Example */
const DeliveryDatePicker: DeliveryDatePickerConfig = {
  attributeName: 'DESIRED_DELIVERY_DATE',
  displayLocale: 'de-DE',
  earliestDeliveryDate: 0,
  latestDeliveryDate: 180,
  nextDayDelivery: {
    originTimezone: Timezones.CET,
    enabled: true,
    until: 14,
  },
  disabledWeekdays: [0, 1, 6],
  disableHolidays: {
    enabled: true,
    states: [
      {
        state: 'ALL',
        daysBlockedAfter: 0,
      },
      {
        state: 'BE',
        daysBlockedAfter: 1,
      },
    ],
  },
};

Product pagination defaults

The product pagination defaults are considered the 'default' values when navigating through a collection page. Default values are not displayed in the url as UrlParams only 'non-default' values, to keep the initial url clean. So if a collection page is navigated on and has no further url params, shophub assumes that the page uses the default params.

The filter options are:

page The default page the user starts on.
sort The way the products are sorted (by name, by price...).
order The way the products are ordered (ASC, DESC).

const PRODUCT_PAGINATION_DEFAULTS: Shophub.FilterOptions = {
  page: '1',
  sort: SortOption.name,
  order: OrderOption.asc,
};

ShopData

Simple shopdata that is used for SEO information and displayed in the urr title.

const Shopdata = {
  name: 'Shophub',
  slogan: 'What else?',
};

SortFilterOptions

Represents all filter combination options to properly use localization.

⚠️

This constant should not be edited!

const sortFilterOptions: Array<SortFilterOption> = [
  {
    title: 'components_product_product-archive:filter_menu_latest.title',
    sortOption: SortOption.createdAt,
    orderOption: OrderOption.asc,
  },
  {
    title: 'components_product_product-archive:filter_menu_oldest.title',
    sortOption: SortOption.createdAt,
    orderOption: OrderOption.desc,
  },
  {
    title: 'components_product_product-archive:filter_menu_price-za.title',
    sortOption: SortOption.price,
    orderOption: OrderOption.desc,
  },
  {
    title: 'components_product_product-archive:filter_menu_price-az.title',
    sortOption: SortOption.price,
    orderOption: OrderOption.asc,
  },
  {
    title: 'components_product_product-archive:filter_menu_name-az.title',
    sortOption: SortOption.name,
    orderOption: OrderOption.asc,
  },
  {
    title: 'components_product_product-archive:filter_menu_name-za.title',
    sortOption: SortOption.name,
    orderOption: OrderOption.desc,
  },
];

SupportedCookies

Represents all valid cookie keys.

⚠️

This constant should not be edited!

enum SupportedCookies {
  accessToken = 'x-shophub-access-token',
  urlDiscountCode = 'shophub-url-discount'
}

SupportedProductPaginationParams

Represents all support product pagination parameters, that can be found in the url as url params on collection pages.

⚠️

This constant should not be edited!

enum SupportedProductPaginationParams {
  page = 'page',
  sort = 'sort',
  order = 'order',
}

SupportedURLSearchParams

Represents all url search params beyond params that are related to product filtering.

⚠️

This constant should not be edited!

enum SupportedURLSearchParams {
  discount = 'discount'
}

Simple

The simple.ts file in the constant folder in the frontend, contains mutiple constants.

/** The log level, determing what logs are logged. */
export const LOG_LEVEL: LogLevel = 'log';
/** Value until data cached by next is not considered fresh anymore. */
export const CACHE_CONSIDERED_FRESH = 600;
/** Value until data cached by next is not considered stale anymore. */
export const CACHE_CONSIDERED_STALE = 1800;
export const SHOPIFY_CART_ID_TOKEN = 'shophub-cart-id-token';
/** Amount of skeleton products that are shown on product collection page loading. */
export const PRODUCT_PAGINATION_PREVIEW_AMOUNT = 3;
export const IMAGE_PLACEHOLDER_URL = '/assets/util/placeholder.png';
/** Delay in ms, defining when a popups visibility decays by itself. Used for popups that convey important information. */
export const POPUP_DECAY_IMPORTANT = 5000;
/** Delay in ms, defining when a popups visibility decays by itself. Used for popups that convey semi important information. */
export const POPUP_DECAY = 3500;
/** Height in pixel that determines if content inside the truncateContent component is getting truncated.
WARNING: If you change this, look at the calculations for expectOverflowing to make sure flicker-reducing approximates are adapted. */
export const TRUNCATE_AT = 63;
/** This should be synced with the Frontend/Backend/Shop default locale settings to fallback to a consistent value */
export const LOCALE_FALLBACK = 'de';
/** Defines the amount of items that are preloaded on an archive page.  */
export const ARCHIVE_PAGE_PRELOAD_AMOUNT_LIMIT = 10;
/** Defines the maximum amount a product can be selected at once, before it's being added to the cart. */
export const QUANTITY_SELECT_HARD_CEILING = 100;
/** Text element that is used as seperator when applicable. Is used on the product page to split collections of one product for example. */
export const SEPERATOR = '|';
/** Sets the default amount for the selectable product quantity. */
export const PRODUCT_QUANTITY_SELECT_AMOUNT = 10;
/** Key for the product metafield that lets shophub determine if the line item is a bundled product. If you change this, you must also change CART_FRAGMENT gql queries */
export const IS_BUNDLED_PRODUCT_METAFIELD_KEY = 'is_bundled_product';
/** Defines the color of the progress bar. The progress bar is hidden if the value of the color is set to null. */
export const PROGRESS_BAR_COLOR = '#f79c51';

Backend constants

The constants in the backend are not split up into different files, like it's done in the frontend, but kept grouped in one file.

Log level

The log level, determing what logs are logged.

const LOG_LEVEL: LogLevel = 'log';

Supported countries

The countries that the shop ships to.

const SUPPORTED_COUNTRIES: Array<CountryCode> = [
  CountryCode.De,
  CountryCode.Ar,
  CountryCode.Ch,
];

Access token cookie

The cookie key of the access token. It's important that this value for the token key, matches the value on the frontends SupportedCookies file.

⚠️

This constant should not be edited!

const ACCESS_TOKEN_COOKIE = 'x-shophub-access-token';

Internal API token cookie

The cookie key of the access token.

⚠️

This constant should not be edited!

const INTERNAL_API_TOKEN_COOKIE = 'x-shophub-internal-api-token';

Image fallback values

A base64 image string that is used as blur placeholder image, when images are loaded and they don't provide their own blur base64 string. The original image should be around 10x10 pixels in size.

const IMAGE_FALLBACK_VALUES = {
  base64:
    'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mO8Wg8AAi8BVvC05AcAAAAASUVORK5CYII=',
};

Db config ID

Simple integer id that is defined to the config once it's created.

DeliveryDatePicker

As mentioned in the frontend constant, the cart delivery date object needs to be mirrored in the front- and backend at the moment. Check the documentation of the object further up here

Cart attribute whitelist

All attributes that are whitelisted and therefor allowed as key value in a carts parameter list.

const CART_ATTRIBUTE_WHITELIST: Array<string> = [
  DeliveryDatePicker.attributeName,
];

Required webhook topics

An array of webhook topics. Each topic entity represents one webhook subscription that should be connected to shopify and shophub. Shophub automatically connects those webhook topics once, when running a request against the webhook init endpoint of shophhub. You can read more about webhooks here. This array should not be changed.

const REQUIRED_WEBHOOK_TOPICS: Array<WebhookSubscriptionTopic> = []

Pagination

Determines the amount of products shown on one collection page at once.

const PAGINATION: PageResultAmount = {
  products: 20,
};

Font Style

The default values to style text in CMS banners.

const FONT_STYLE = {
  classification: FontTypeClassification.Sans,
  size: TwFontSize.Base,
  weight: TwFontWeight.Normal,
};

Any page defaults

The default values that determine if per default the header and or footer should be rendered, if not further specified. The default locale for returning pages. This should be synced with the frontend settings (currently hardcoded in next-i18next.config.js).

const ANY_PAGE_DEFAULTS = {
    showHeader: true,
    showFooter: true,
    locale: Locale.de,
};

Header defaults

Default values for parts that are included into the header and are optional.

export const HEADER_DEFAULTS = {
  navItem: {
    styleOptions: {
      enableMegaMenu: true,
    },
  },
};

Product page options defaults

The optional settings for a product page.

ShowBreadcrumbs: Determine if breadcrumbs should be shown on the product page.
useCompactVariantDisplay Defines which type of variant selector is displayed on the product page. Per default the slider variant selector is used.
default use the compact version for all device sizes that are not mobile.
mobile use the compact version for mobile device sizes. If mobile is not set during the creation, the value of the default attribute is applied to it.

export const PRODUCT_PAGE_OPTIONS_DEFAULTS: Shophub.ProductPageOptions = {
  showBreadcrumbs: true,
  useCompactVariantDisplay: {
    default: false,
    mobile: false,
  },
};

CMS Banner default values

Default values that are used for CMS banners, if not further specified on creation by the user.

Funnel block banner

const ANNOUNCEMENT_BANNER_DEFAULTS = {
  /** Duration per slide in ms */
  slideDuration: 10000,
  /** Defines general height of the banner */
  size: SizeOption.Medium,
  isSticky: false,
};

Funnel block

const FUNNEL_BLOCK_DEFAULTS = {
  alignment: AlignmentOption.Center,
  minHeight: '600px',
  isScreenHeight: false,
};

Product preview Block

const PRODUCT_PREVIEW_BLOCK_DEFAULTS = {
  showQuantitySelector: true,
};

Small funnel wrapper

const PRODUCT_PREVIEW_BLOCK_DEFAULTS = {
  showQuantitySelector: true,
};

Text block

const TEXT_BLOCK_DEFAULTS = {
  alignment: AlignmentOption.Left,
  isHeader: false,
};

Image block

const IMAGE_BLOCK_DEFAULTS = {
  baseWidth: null,
  isScreenWidth: false,
  isScreenHeight: false,
  minHeight: null,
  position: AlignmentOption.Center,
  maxHeight: '400px',
  isFullWidth: false,
};

Video block

import { AlignmentOption } from '@shophub/types';
const VIDEO_BLOCK_DEFAULTS = {
  aspectRatio: TwAspectRatio.Video,
  alignment: AlignmentOption.Center,
  height: '500px',
  isScreenHeight: false,
  isScreenWidth: false,
  maxHeight: null,
};

Button block

const BUTTON_BLOCK_DEFAULTS = {
  alignment: AlignmentOption.Left,
  buttonType: ButtonType.Primary,
  minWidth: '10%',
  maxWidth: '80%',
  width: '350px',
};

Upsell block

const UPSELL_BLOCK_DEFAULTS = {
  showSliderNavigation: true,
  sort: null,
  order: OrderOption.asc,
};

Upsell funnel block

const UPSELL_FUNNEL_BLOCK_DEFAULTS = {
  widthEqualsSlidesAmount: 1,
  alignmentY: AlignmentOption.Center,
};

Newsletter banner

The newsletter banner uses i18n strings to be able to localize the defaults in different languages. When providing custom values to a banner, it's recommend to use i18n strings as well to still be able to utilize the localization feature.

export const NEWSLETTER_BANNER_DEFAULTS = {
  subscribeButtonText: {
    content: 'newsletter_banner_subscribe_default.btn:text',
  },
  consentDescription: {
    content: 'newsletter_banner_consent_default.text',
  },
  alignment: AlignmentOption.Left,
};

Miscellaneous

Background image

const BACKGROUND_IMAGE_DEFAULTS = {
  position: 'center center',
  size: 'cover',
  repeat: 'no-repeat',
};

Next steps

After wrapping up the configuration part, learn more about synchronizing your database with your shopify products here.

Getting started Shopify database sync