Boxen — A Kit of Parts Squarespace Developer SDK

System Blocks

By far the most useful thing you can customize in a sqs template are core system blocks. There is a design pattern to how you do this and it is NOT documented in the official sqs developer docs. So I’m documenting it here and talking through Kit of Parts examples coded into the Boxen SDK.

Not all system blocks can be customized at the template level, however the most useful blocks for the widest range of content are up for grabs. I’ll explain system block overrides by using my favorite one — Image. The ability to fully override the Image block alone is extremely useful.

This is because I have my own ImageLoader in ProperJS that I use on all my web projects. I don’t like the core SQS Imageloader implementation. This allows my ImageLoader to operate as the global, core ImageLoader for all my sqs sites. You see where system block overrides are going here?

To override a system block you need two files in your template. A config file and a block partial file ( this is the actual template markup ). In the case of Image we create image.block and image.block.conf. In the image.block.conf file we put a simple JSON schema:

  {
    “type”: “image”
  }

You can see what the SDK image.block file looks like for Boxen on Github. One trick I learned early while experimenting with system block overrides is how to view the context JSON available in each block file. This little bit of code in any system block file will log the JSON scheme in console:

  <script>console.log( {@|json-pretty} );<script>

One crucial caveat to system block overrides is their ability to take effect within the context of local development. That is, they won’t until you deploy the files to your remote sqs site. Sqs has many nuanced quirks such as this given the nature of its proprietary platform. Even the local development server renders system blocks and other core sections of templates from the remote service endpoints.

If you’ve been reading from the beginning then by now you know to see your system block changes locally you would need to run the following:

  npm run deploy
  npm start

Each block gets a specific localized context which includes any of the settings and options you can set for the block in the CMS as well as some other information depending on what block it is. There’s no real rhyme or reason to how the data is formatted and appropriated to each block. You just have to look at what you get and work with it. The following is a custom Image Block rendering via my ProperJS ImageLoader:

 

Notice the block is also rendering this caption with the image. You have to account for block level options configured in the CMS within your block override template. Logging the block JSON is how you see the data.

 

Next Level Ponies

Prints for sale

Get the print
 

Sickboy

A degenerate superhero trying to make it in this crime-ridden, dystopian cyberpunk future.

Get the print
 

Deku Stick

One of my favorite discoveries while playing Ocarina of Time on my N64 back in the day :)

Get the download
 

Lo-fi Boy

Inspired by a Pillows song.

Get the print
 

Lo-fi Boy, Fighter Girl

An illustration inspired by a Pillows song.
Get the print
 

Up next: Kit of Parts

Boxen — A Kit of Parts Squarespace Developer SDK

System Blocks

By far the most useful thing you can customize in a sqs template are core system blocks. There is a design pattern to how you do this and it is NOT documented in the official sqs developer docs. So I’m documenting it here and talking through Kit of Parts examples coded into the Boxen SDK.

Not all system blocks can be customized at the template level, however the most useful blocks for the widest range of content are up for grabs. I’ll explain system block overrides by using my favorite one — Image. The ability to fully override the Image block alone is extremely useful.

This is because I have my own ImageLoader in ProperJS that I use on all my web projects. I don’t like the core SQS Imageloader implementation. This allows my ImageLoader to operate as the global, core ImageLoader for all my sqs sites. You see where system block overrides are going here?

To override a system block you need two files in your template. A config file and a block partial file ( this is the actual template markup ). In the case of Image we create image.block and image.block.conf. In the image.block.conf file we put a simple JSON schema:

  {
    “type”: “image”
  }

You can see what the SDK image.block file looks like for Boxen on Github. One trick I learned early while experimenting with system block overrides is how to view the context JSON available in each block file. This little bit of code in any system block file will log the JSON scheme in console:

  <script>console.log( {@|json-pretty} );<script>

One crucial caveat to system block overrides is their ability to take effect within the context of local development. That is, they won’t until you deploy the files to your remote sqs site. Sqs has many nuanced quirks such as this given the nature of its proprietary platform. Even the local development server renders system blocks and other core sections of templates from the remote service endpoints.

If you’ve been reading from the beginning then by now you know to see your system block changes locally you would need to run the following:

  npm run deploy
  npm start

Each block gets a specific localized context which includes any of the settings and options you can set for the block in the CMS as well as some other information depending on what block it is. There’s no real rhyme or reason to how the data is formatted and appropriated to each block. You just have to look at what you get and work with it. The following is a custom Image Block rendering via my ProperJS ImageLoader:

 

Notice the block is also rendering this caption with the image. You have to account for block level options configured in the CMS within your block override template. Logging the block JSON is how you see the data.

 

Next Level Ponies

Prints for sale

Get the print
 

Sickboy

A degenerate superhero trying to make it in this crime-ridden, dystopian cyberpunk future.

Get the print
 

Deku Stick

One of my favorite discoveries while playing Ocarina of Time on my N64 back in the day :)

Get the download
 

Lo-fi Boy

Inspired by a Pillows song.

Get the print
 

Lo-fi Boy, Fighter Girl

An illustration inspired by a Pillows song.
Get the print
 

Up next: Kit of Parts