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.

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

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

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

Changelog

Full changelog for stable version is available here

Latest changes: 1.0.0

Major Changes

#871 1566f7a Thanks @patzick! - Read more about new major release: https://github.com/shopware/frontends/discussions/965
#1056 c729e70 Thanks @patzick! - Removed deprecations from the package:
- getProductThumbnailUrl is removed. Use getSmallestThumbnailUrl instead.
- internal method _debounce is removed.
- internal method _parseUrlQuery is removed.

Minor Changes

#857 864616f Thanks @mdanilowicz! - Add isMaintenanceMode to check if backend is available
#508 a92941e Thanks @mdanilowicz! - Add accessGranted property for the getMedia helper
#477 487d991 Thanks @mdanilowicz! - Remove "@shopware-pwa/types" dependency and replace it with generic types
#582 97b5949 Thanks @mdanilowicz! - Export css classes as a separate file
#545 6664aa2 Thanks @itscark! - Fix visibility classes

Patch Changes

#524 6b54268 Thanks @BrocksiNet! - added buildUrlPrefix, which perviously was internal helper of the @shopware/cms-base package

API

`getTranslatedProperty`

Get translated property from the given object.

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

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

source code

`downloadFile`

Download file

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

source code

`relativeUrlSlash`

Add/remove slash from the relative path

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

source code

`getSrcSetForMedia`

Returns the srcset attribute for the image, for available breakpoints

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

source code

`getMedia`

Prepare media object

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

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

source code

`canUseQuoteActions`

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

source code

`urlIsAbsolute`

export function urlIsAbsolute(url: string)

source code

`getCmsLayoutConfiguration`

Get layout configuration for CMS content

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

source code

expand LayoutConfiguration

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`

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.

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

source code

`isProduct`

Predicate function to check if the entity is a product.

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

source code

`isCategory`

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

source code

`isLandingPage`

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

source code

`getProductName`

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

source code

`getProductFreeShipping`

Get product free shipping property

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

source code

`getMainImageUrl`

gets the cover image

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

source code

`getListingFilters`

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

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

source code

`getProductReviews`

Format product reviews to ui-interfaces

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

`getProductTierPrices`

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

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

source code

`getProductUrl`

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

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

source code

`getProductCalculatedListingPrice`

Get the calculated list price

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

source code

`getProductRatingAverage`

Get product rating average property

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

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.

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

source code

`getProductFromPrice`

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

source code

`getLanguageName`

Get translated language name

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

source code

`buildUrlPrefix`

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

source code

`getBackgroundImageUrl`

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

source code

`isMaintenanceMode`

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

source code

`getShippingMethodDeliveryTime`

Get shipping delivery time

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

source code

`getCategoryUrl`

Get URL for category. Some link

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

source code

`getFormattedPrice`

Get formatted price

export function getFormattedPrice(
  value: string | number,
  currency: string,
  options: Options = {
    direction: "ltr",
    removeDecimals: false,
    removeCurrency: false,
  },
): 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)">

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

source code

`getCategoryBreadcrumbs`

Gather breadcrumbs from category

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

`getCategoryImageUrl`

gets the cover image

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

source code

shopware/frontends - helpers ​

Reusable classes ​

Changelog ​

Latest changes: 1.0.0 ​

Major Changes ​

Minor Changes ​

Patch Changes ​

API ​

getTranslatedProperty ​

getBiggestThumbnailUrl ​

downloadFile ​

relativeUrlSlash ​

getSrcSetForMedia ​

getMedia ​

getSmallestThumbnailUrl ​

canUseQuoteActions ​

urlIsAbsolute ​

getCmsLayoutConfiguration ​

LayoutConfiguration ​

getCmsEntityObject ​

isProduct ​

isCategory ​

isLandingPage ​

getProductName ​

getProductFreeShipping ​

getMainImageUrl ​

getListingFilters ​

getProductReviews ​

getProductTierPrices ​

getProductUrl ​

getProductCalculatedListingPrice ​

getProductRatingAverage ​

getProductRoute ​

getProductFromPrice ​

getLanguageName ​

buildUrlPrefix ​

getBackgroundImageUrl ​

isMaintenanceMode ​

getShippingMethodDeliveryTime ​

getCategoryUrl ​

getFormattedPrice ​

getCategoryRoute ​

getCategoryBreadcrumbs ​

getCategoryImageUrl ​

shopware/frontends - helpers

Reusable classes

Changelog

Latest changes: 1.0.0

Major Changes

Minor Changes

Patch Changes

API

`getTranslatedProperty`

`getBiggestThumbnailUrl`

`downloadFile`

`relativeUrlSlash`

`getSrcSetForMedia`

`getMedia`

`getSmallestThumbnailUrl`

`canUseQuoteActions`

`urlIsAbsolute`

`getCmsLayoutConfiguration`

`LayoutConfiguration`

`getCmsEntityObject`

`isProduct`

`isCategory`

`isLandingPage`

`getProductName`

`getProductFreeShipping`

`getMainImageUrl`

`getListingFilters`

`getProductReviews`

`getProductTierPrices`

`getProductUrl`

`getProductCalculatedListingPrice`

`getProductRatingAverage`

`getProductRoute`

`getProductFromPrice`

`getLanguageName`

`buildUrlPrefix`

`getBackgroundImageUrl`

`isMaintenanceMode`

`getShippingMethodDeliveryTime`

`getCategoryUrl`

`getFormattedPrice`

`getCategoryRoute`

`getCategoryBreadcrumbs`

`getCategoryImageUrl`