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.1.0
Minor Changes
- #1215
6ee2f90
Thanks @mdanilowicz! - AddedgetCmsTranslate
helper to replace text placeholder with param value
API
getTranslatedProperty
Get translated property from the given object.
export function getTranslatedProperty<T>(
element: T | undefined | null | never,
property: keyof T,
): string
downloadFile
Download file
export function downloadFile<T>(file: T, name: string)
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
getMedia
Prepare media object
export function getMedia<
T extends {
downloads?: Array<{
id: string;
accessGranted: boolean;
media: {
fileName: string;
fileExtension: string;
};
}>;
},
>(lineItem: T)
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 | undefined
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
relativeUrlSlash
Add/remove slash from the relative path
export function relativeUrlSlash(relativeUrl: string, slash = true)
urlIsAbsolute
export function urlIsAbsolute(url: string)
canUseQuoteActions
export function canUseQuoteActions<
T extends {
stateMachineState?: {
technicalName: string;
};
},
>(quote: T)
getCmsLayoutConfiguration
Get layout configuration for CMS content
export function getCmsLayoutConfiguration<
T extends CmsBlock | CmsSection | CmsSlot,
>(content: T): LayoutConfiguration
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;
};
getCmsEntityObject
Returns the main page object depending of the type of the CMS page.
export function getCmsEntityObject(
response: CmsPageResponse,
): Product | Category | LandingPage
isProduct
Predicate function to check if the entity is a product.
export function isProduct<T extends { apiAlias: string }>(
entity: T | Product,
): entity is Product
isCategory
export function isCategory<T extends { apiAlias: string }>(
entity: T | Category,
): entity is Category
isLandingPage
export function isLandingPage<T extends { apiAlias: string }>(
entity: T | LandingPage,
): entity is LandingPage
getProductFreeShipping
Get product free shipping property
export function getProductFreeShipping<
T extends {
shippingFree: boolean;
},
>(product?: T): boolean
getProductName
export function getProductName<
T extends {
name: string;
},
>({ product }: { product?: T } = {}): string | null
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
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[]
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[]
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
getProductRatingAverage
Get product rating average property
export function getProductRatingAverage<T extends { ratingAverage: number }>(
product: T,
): number | null
getProductCalculatedListingPrice
Get the calculated list price
export function getProductCalculatedListingPrice<
T extends {
calculatedPrice?: CalculatedPrice;
calculatedPrices?: CalculatedPrice[];
},
>(product?: T): number | undefined
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)
getProductFromPrice
export function getProductFromPrice<
T extends {
calculatedPrice?: CalculatedPrice;
calculatedPrices?: CalculatedPrice[];
},
>(product: T): number | undefined
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
getCategoryImageUrl
gets the cover image
export function getCategoryImageUrl<
T extends {
media?: { url: string };
type: string;
},
>(category: T): string
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;
},
)
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:
<RouterLink :to="getCategoryRoute(navigationElement)">
export function getCategoryRoute<
T extends {
type: string;
externalLink?: string;
seoUrls?: { seoPathInfo: string }[];
internalLink?: string;
id: string;
linkType?: string;
},
>(category: T)
getFormattedPrice
Get formatted price
export function getFormattedPrice(
value: string | number,
currency: string,
options: Options = {
direction: "ltr",
removeDecimals: false,
removeCurrency: false,
},
): string
getShippingMethodDeliveryTime
Get shipping delivery time
export function getShippingMethodDeliveryTime<
T extends {
deliveryTime?: {
translated: {
name: string;
};
};
},
>(shippingMethod: T)
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[]
getBackgroundImageUrl
export function getBackgroundImageUrl<
T extends {
backgroundMedia?: {
metaData?: {
width?: number;
height?: number;
};
};
},
>(url: string, element: T): string
buildUrlPrefix
export function buildUrlPrefix(
url: string | UrlRoute,
prefix: string,
): UrlRouteOutput
isMaintenanceMode
export function isMaintenanceMode<
T extends {
code?: string;
},
>(errors: [T]): boolean
getCmsBreadcrumbs
Build the breadcrumbs for the CMS page
export function getCmsBreadcrumbs<
T extends {
translated: {
name: string;
};
},
>(page: T): { name: string }[]
getCmsTranslate
Replace text placeholder with param value
export function getCmsTranslate(
key: string,
params?: { [key: string]: string | number | null | undefined } | null,
)
getLanguageName
Get translated language name
export function getLanguageName<
T extends {
translationCode?: { translated: { name: string } };
},
>(language: T): string