Why Does Sitecore Have Its Own JSS Types?
Sitecore has the “ExperienceEditor” and XM Cloud now also has “Sitecore Pages” which both allow people to author (the act of building/constructing a page in Sitecore) custom pages. Sitecore provides the user the ability to edit the text directly inside Sitecore Pages, allowing them to edit all the information directly in the page builder.
Since JSS (Sitecore JavaScript Rendering SDKs) is JavaScript, we don't get the natural typing you get in strongly typed languages like C# (which is used for the older versions of sitecore). That's why we have Typescript and the JSS types.
Since we want to provide the author the ability to edit everything directly, all the Sitecore fields that you can
select from when building out the template return objects. The most standard object that you’ll see is a
simple {value: string}
, however some of the more unique types have multiple values. Because of this, we
can use our JSS types to get IntelliSense/Typescript to do all the hard work for us.
All Common Sitecore JSS Types
Type | Data Type | JSS Component | Example Sitecore Fields |
---|---|---|---|
Field<string> |
Object {value: string} |
<Text/> |
Integer, Number, Password, and Single-Line & Multi-Line Text fields |
RichTextField |
Object {value: string} |
<RichText/> |
Rich Text Field |
ImageField |
Object {value: ImageFieldValue} |
<Image/> |
Image |
ImageFieldValue |
Object {[attributeName: string]: |
- | - |
LinkField |
Object {value: LinkFieldValue} |
<Link/> |
General Link |
LinkFieldValue |
Object {[attributeName: string]: |
- | - |
FileField |
Object {value: FileFieldValue;} |
<File /> |
File |
FileFieldValue |
Object {[propName: string]: |
- | - |
Date |
Object {value: string} |
<DateField /> |
Date |
Differences Between Similar JSS Types
Some JSS types look very similar, but act differently. The biggest example would be a normal
<Text/>
field vs a <RichText/>
field. A <Text/>
field uses
a Field<string>
type, this provides a simple string that you would want to display inside a
single tag (ex: <p>
). A <RichText/>
on the other hand is targeted at putting
multiple content tags inside a larger wrapper (ex: <div>
).
Another example would be Field
vs FieldValue
(ex: LinkField
vs
LinkFieldValue
). When you are creating your typescript types, you might be confused on which one to
use, Field
or FieldValue
. Simply put: Field
will provide you with the type
for the entire Sitecore object, while FieldValue
will only give you the intractable object values.
It's important to not only understand the difference, but also understand when you are passing down only the
FieldValue
vs the entire Sitecore object. Here is an example using LinkField
, notice how
LinkFieldValue
is a child of LinkField
.
LinkField
{
value: LinkFieldValue; // Child of LinkField
editableFirstPart?: string;
editableLastPart?: string;
}
LinkFieldValue
{
[attributeName: string]: unknown;
href?: string;
className?: string;
class?: string;
title?: string;
target?: string;
text?: string;
anchor?: string;
querystring?: string;
linktype?: string;
}
How to Use Them With the Sitecore’s JSS Components
Text
Component Properties:
Name | Required | Default Value | Description |
---|---|---|---|
field |
Yes | - | The field you want to render. |
tag |
No | span |
Which HTML element you want to wrap text value |
editable |
No | true |
Indicates whether to use the editor or Sitecore-formatted HTML output |
encode |
No | true |
Enables or disables HTML encoding of the output value. A false value also implies editable: false.
|
Example Code:
import { Text } from '@sitecore-jss/sitecore-jss-react';
//Default Text Field
<Text field={props.fields.textValue} />
//Text field with a Tag
<Text field={props.fields.textValue} tag="p" />
//Non-editable text field with a custom tag, CSS classes, and custom attributes
<Text
field={props.fields.textValue}
tag="h2"
editable={false}
encode={false}
className="font-weight-bold"
data-sample="other-attributes-pass-through"
/>
RichText
Component Properties:
Name | Required | Default Value | Description |
---|---|---|---|
field |
Yes | - | The field you want to render. |
tag |
No | div |
Which HTML element you want to wrap text value |
editable |
No | true |
Indicates whether to use the editor or Sitecore-formatted HTML output |
Example Code:
import { RichText } from '@sitecore-jss/sitecore-jss-react';
//Default Rich Text Field
<RichText field={props.fields.richTextValue} />
//Non-editable text field with a custom tag, CSS classes, and custom attributes
<RichText
field={props.fields.richTextValue}
tag="section"
editable={false}
className="font-weight-bold"
data-sample="other-attributes-pass-through"
/>
Link
Component Properties:
Name | Required | Default Value | Description |
---|---|---|---|
field |
Yes | - | The Sitecore General Link you want to render |
editable |
No | true |
Indicates whether to use the editor or Sitecore-formatted HTML output. |
showLinkTextWithChildrenPresent |
No | - | A Boolean expression that enables or disables the display of a link description even when children exist. |
Example Code:
import { Link } from '@sitecore-jss/sitecore-jss-react';
//External links
<Link field={props.fields.externalLink} />
//Internal links, with HTML or other components
<Link field={props.fields.internalLink}>
<em>Lorem</em> ipsum dolor sit amet, consectetur adipiscing elit. Etiam elementum.
</Link>
//Additional properties & attributes.
<Link
field={props.fields.externalLink}
showLinkTextWithChildrenPresent={true}
className="font-weight-bold"
data-otherattributes="pass-through-to-anchor-tag"
/>
Image
Component Properties:
Name | Required | Default Value | Description |
---|---|---|---|
field |
Yes | - | The Sitecore route field you want to render |
editable |
No | true |
Enable/disable inline editing |
imageParams |
No | [] |
An array of ImageSizeParameters that converts into query string parameters added to the image URL
|
srcSet |
No | [] |
An array of ImageSizeParameters definitions for generating comma-separated strings |
mediaUrlPrefix |
No | - | A custom regular expression that finds media URL prefix to be replaced by /-/jssmedia or
/~/jssmedia . |
Example Code:
import { Image } from '@sitecore-jss/sitecore-jss-react';
//Simple Image Field
<Image media={props.fields.image} />
//Responsive Image Field
<Image
field={props.fields.image}
srcSet={[{ mw: 300 }, { mw: 100 }]}
sizes="(min-width: 960px) 300px, 100px"
className="img-fluid"
/>
//Server-side Image Resizing
<Image
field={props.fields.image}
editable={false}
imageParams={{ mw: 100, mh: 50 }} //Resized based on these values
height="50"
width="94"
data-sample="other-attributes-pass-through"
/>
File
Component Properties:
Name | Required | Default Value | Description |
---|---|---|---|
value |
Yes | - | The sitecore route field you want to render |
children |
No | itself |
A React Node, populating the rendered </a> tag. |
Example Code:
import { File } from '@sitecore-jss/sitecore-jss-react';
//Simple File Field
<File field={props.fields.file} />
//Open in a new tab
<File field={props.fields.file} target="_blank"/>
//Custom Anchor text Field
<File field={props.fields.file}>
View file
</File>
Date
Component Properties:
Name | Required | Default Value | Description |
---|---|---|---|
field |
Yes | - | The sitecore field you want to render |
tag |
No | span |
Which HTML element you want to wrap the date value |
editable |
No | true |
Enable/disable inline editing |
render |
No | - | A function that returns the value to render into the tag value |
Example Code:
import { DateField } from '@sitecore-jss/sitecore-jss-react';
//Date Field
<DateField field={props.fields.date} />
//Datetime Field
<DateField field={props.fields.dateTime} />
//Date formatting
<DateField
field={props.fields.dateTime}
render={(date) => <em>{date.toLocaleString()}</em>}
/>
Final Thoughts on JSS Types
Hopefully this beginner focused guide on Sitecore JSS Types has helped you better understand when and how to use not only each JSS Type, but also its corresponding component!