Skip to content
Shopware

shopware/frontends - helpers

shopware/frontends - helpers

Welcome to @shopware-pwa/helpers-next package.

For getting started documentation visit https://frontends.shopware.com/

Documentation specific for this package: helpers

Reusable classes

The helpersCssClasses variable, defined in the cms/layoutClasses.ts helper file, comprises an array of class names utilized within the CMS.

To enhance type support, a union type HelpersCssClasses is defined, which encompasses all class names present in the helpersCssClasses array.

ts
const visibilityMap: Record<CmsVisibility, HelpersCssClasses> = {
  mobile: "max-md:hidden",
  tablet: "md:max-lg:hidden",
  desktop: "lg:hidden",
};

These classes can be integrated into a custom template, thereby ensuring consistency across different packages. For example as a safelist classes in unocss configuration file

ts
import { helpersCssClasses } from "@shopware-pwa/helpers-next";

export default defineConfig({
  safelist: helpersCssClasses,
});

Changelog

Full changelog for stable version is available here

Latest changes: 1.1.0

Minor Changes

API

getTranslatedProperty

Get translated property from the given object.

ts
export function getTranslatedProperty<T>(
  element: T | undefined | null | never,
  property: keyof T,
): string

source code

getBiggestThumbnailUrl

Returns the biggest thumbnail url from the media object

ts
export function getBiggestThumbnailUrl<
  T extends {
    thumbnails?: Array<{
      width: number;
      url: string;
    }>;
  },
>(media?: T): string | undefined

source code

downloadFile

Download file

ts
export function downloadFile<T>(file: T, name: string)

source code

getMedia

Prepare media object

ts
export function getMedia<
  T extends {
    downloads?: Array<{
      id: string;
      accessGranted: boolean;
      media: {
        fileName: string;
        fileExtension: string;
      };
    }>;
  },
>(lineItem: T)

source code

getSmallestThumbnailUrl

Returns the smallest thumbnail url from the media object

ts
export function getSmallestThumbnailUrl<
  T extends {
    thumbnails?: Array<{
      width: number;
      url: string;
    }>;
  },
>(media?: T): string | undefined

source code

relativeUrlSlash

Add/remove slash from the relative path

ts
export function relativeUrlSlash(relativeUrl: string, slash = true)

source code

urlIsAbsolute

ts
export function urlIsAbsolute(url: string)

source code

canUseQuoteActions

ts
export function canUseQuoteActions<
  T extends {
    stateMachineState?: {
      technicalName: string;
    };
  },
>(quote: T)

source code

getSrcSetForMedia

Returns the srcset attribute for the image, for available breakpoints

ts
export function getSrcSetForMedia<
  T extends {
    thumbnails?: Array<{
      width: number;
      url: string;
    }>;
  },
>(media?: T): string | undefined

source code

getCmsLayoutConfiguration

Get layout configuration for CMS content

ts
export function getCmsLayoutConfiguration<
  T extends CmsBlock | CmsSection | CmsSlot,
>(content: T): LayoutConfiguration

source code

expand LayoutConfiguration
ts
export type LayoutConfiguration = {
  layoutStyles: {
    backgroundColor?: string | null;
    backgroundImage?: string | null;
    backgroundSize?: string | null;
    sizingMode?: string | null;
    marginBottom?: string | null | undefined;
    marginLeft?: string | null | undefined;
    marginRight?: string | null | undefined;
    marginTop?: string | null | undefined;
  };
  cssClasses: {
    [cssClass: string]: boolean;
  } | null;
};

LayoutConfiguration

ts
export type LayoutConfiguration = {
  layoutStyles: {
    backgroundColor?: string | null;
    backgroundImage?: string | null;
    backgroundSize?: string | null;
    sizingMode?: string | null;
    marginBottom?: string | null | undefined;
    marginLeft?: string | null | undefined;
    marginRight?: string | null | undefined;
    marginTop?: string | null | undefined;
  };
  cssClasses: {
    [cssClass: string]: boolean;
  } | null;
};

source code

getCmsEntityObject

Returns the main page object depending of the type of the CMS page.

ts
export function getCmsEntityObject(
  response: CmsPageResponse,
): Product | Category | LandingPage

source code

isProduct

Predicate function to check if the entity is a product.

ts
export function isProduct<T extends { apiAlias: string }>(
  entity: T | Product,
): entity is Product

source code

isCategory

ts
export function isCategory<T extends { apiAlias: string }>(
  entity: T | Category,
): entity is Category

source code

isLandingPage

ts
export function isLandingPage<T extends { apiAlias: string }>(
  entity: T | LandingPage,
): entity is LandingPage

source code

getListingFilters

biome-ignore lint/suspicious/noExplicitAny: Listing filters needs to be improved when schema types are ready

ts
export function getListingFilters<T extends Record<string, any>>(
  aggregations: T | undefined | null,
): ListingFilter[]

source code

getBackgroundImageUrl

ts
export function getBackgroundImageUrl<
  T extends {
    backgroundMedia?: {
      metaData?: {
        width?: number;
        height?: number;
      };
    };
  },
>(url: string, element: T): string

source code

getCmsBreadcrumbs

Build the breadcrumbs for the CMS page

ts
export function getCmsBreadcrumbs<
  T extends {
    translated: {
      name: string;
    };
  },
>(page: T): { name: string }[]

source code

buildUrlPrefix

ts
export function buildUrlPrefix(
  url: string | UrlRoute,
  prefix: string,
): UrlRouteOutput

source code

getCmsTranslate

Replace text placeholder with param value

ts
export function getCmsTranslate(
  key: string,
  params?: { [key: string]: string | number | null | undefined } | null,
)

source code

isMaintenanceMode

ts
export function isMaintenanceMode<
  T extends {
    code?: string;
  },
>(errors: [T]): boolean

source code

getProductName

ts
export function getProductName<
  T extends {
    name: string;
  },
>({ product }: { product?: T } = {}): string | null

source code

getProductFreeShipping

Get product free shipping property

ts
export function getProductFreeShipping<
  T extends {
    shippingFree: boolean;
  },
>(product?: T): boolean

source code

getProductReviews

Format product reviews to ui-interfaces

ts
export function getProductReviews<
  T extends {
    id: string;
    productReviews?: Array<{
      id: string;
      externalUser?: string;
      customerId?: string;
      createdAt: string;
      content: string;
      points?: number;
    }>;
  },
>({ product }: { product?: T } = {}): UiProductReview[]

source code

getProductUrl

Get product url. The priority is SEO url and then technical url.

ts
export function getProductUrl<
  T extends {
    id: string;
    seoUrls?: Array<{
      seoPathInfo?: string;
    }>;
  },
>(product?: T): string

source code

getProductRatingAverage

Get product rating average property

ts
export function getProductRatingAverage<T extends { ratingAverage: number }>(
  product: T,
): number | null

source code

getMainImageUrl

gets the cover image

ts
export function getMainImageUrl<
  T extends
    | {
        cover?: {
          media?: {
            url: string;
          };
        };
      }
    | {
        media?: Array<{
          media?: {
            url?: string;
          };
        }>;
      }
    | {
        cover?: {
          url: string;
        };
      },
>(object: T): string

source code

getProductTierPrices

Get the prices depending on quantity added to cart. Tier prices can be set in Advanced pricing tab in Product view (admin panel)

ts
export function getProductTierPrices<
  T extends {
    calculatedPrices?: Array<{
      unitPrice: number;
      quantity: number;
    }>;
  },
>(product?: T): TierPrice[]

source code

getShippingMethodDeliveryTime

Get shipping delivery time

ts
export function getShippingMethodDeliveryTime<
  T extends {
    deliveryTime?: {
      translated: {
        name: string;
      };
    };
  },
>(shippingMethod: T)

source code

getProductCalculatedListingPrice

Get the calculated list price

ts
export function getProductCalculatedListingPrice<
  T extends {
    calculatedPrice?: CalculatedPrice;
    calculatedPrices?: CalculatedPrice[];
  },
>(product?: T): number | undefined

source code

getProductFromPrice

ts
export function getProductFromPrice<
  T extends {
    calculatedPrice?: CalculatedPrice;
    calculatedPrices?: CalculatedPrice[];
  },
>(product: T): number | undefined

source code

getProductRoute

Get product route information for Vue router.

Returns product URL and route informations for resolving SEO url. Use it with combination of <RouterLink> or <NuxtLink> in Vue.js or Nuxt.js projects.

ts
export function getProductRoute<
  T extends {
    id: string;
    seoUrls?: Array<{
      seoPathInfo?: string;
    }>;
  },
>(product?: T)

source code

getCategoryImageUrl

gets the cover image

ts
export function getCategoryImageUrl<
  T extends {
    media?: { url: string };
    type: string;
  },
>(category: T): string

source code

getCategoryBreadcrumbs

Gather breadcrumbs from category

ts
export function getCategoryBreadcrumbs<
  T extends {
    translated?: {
      breadcrumb?: string[];
    };
    breadcrumb?: string[];
  },
>(
  category: T,
  options?: {
    /**
     * Start at specific index if your navigation
     * contains root names which should not be visible.
     */
    startIndex?: number;
  },
)

source code

getCategoryUrl

Get URL for category. Some link

ts
export function getCategoryUrl<
  T extends {
    type: string;
    externalLink?: string;
    seoUrls?: { seoPathInfo: string }[];
    internalLink?: string;
    id: string;
    linkType?: string;
  },
>(category: T): string

source code

getCategoryRoute

Get category/navigation route information for Vue Router.

Returns category or navigation URL and route informations for resolving SEO url. Use it with combination of <RouterLink> or <NuxtLink> in Vue.js or Nuxt.js projects.

Example:

html
<RouterLink :to="getCategoryRoute(navigationElement)">
ts
export function getCategoryRoute<
  T extends {
    type: string;
    externalLink?: string;
    seoUrls?: { seoPathInfo: string }[];
    internalLink?: string;
    id: string;
    linkType?: string;
  },
>(category: T)

source code

getFormattedPrice

Get formatted price

ts
export function getFormattedPrice(
  value: string | number,
  currency: string,
  options: Options = {
    direction: "ltr",
    removeDecimals: false,
    removeCurrency: false,
  },
): string

source code

getLanguageName

Get translated language name

ts
export function getLanguageName<
  T extends {
    translationCode?: { translated: { name: string } };
  },
>(language: T): string

source code