York


Happy to announce that a template, a long time in the making, is finally available to use in the Squarespace store. Introducing York:

http://york-demo.squarespace.com/

I'm announcing this here because I had a big hand in developing the template (writing most of the JavaScript), and I'm particularly excited about the AjaxLoader

This site will load all pages via AJAX to make for a snappy experience navigating between pages.  I plan on making this a plugin for others to use, at some point in the future.

Enjoy York!

No Comments

Use ES6 on your Squarespace site...Today!


Today I released a Gulp/Babel boilerplate to use on Squarespace sites.

The benefits of which are:

  • You can write ES6 on your Squarespace site using Babel
  • You can use modern versions of LESS instead of the Squarespace version of LESS
  • Upload your changes on save via SFTP to your developer site

Check it out here!

Couple points:

  1.  Make sure to add gulp-sftp-auth.js to your .gitignore!
  2.  Add main.css to the stylesheets array in template.conf
  3.  Include the main.js script in your site.region file

2/17/16: I have not tested this in full. I'm sure there are bugs. Please don't use this on your production site.  Make sure to do adequate testing on your developer site before pushing it to your live site.

 

No Comments

Helpful Cloning Command in Terminal


I often find myself writing the same line every time I clone a Squarespace site in terminal:

git clone https://site.squarespace.com/template.git site && cd site && subl .

This is annoying and violates all DRY principles.  So I lightly jumped into the world of bash scripting and came up with a terminal command that will do all of this in one go.

requirements:

You'll need a Mac, Sublime Text 2 (or 3) and Git installed, and a Squarespace site in Developer Mode.  If you're using Sublime Text 3, see the note underneath step 2 below.

instructions:

1.  Open up terminal

2.  Assuming Sublime Text is in your Applications folder, run this command (it lets you open up files/folders by typing subl {file} into terminal):

ln -s "/Applications/Sublime Text 2.app/Contents/SharedSupport/bin/subl" /usr/local/bin/subl

NOTE: If you're using Sublime Text 3, run this command instead:

ln -s "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" /usr/local/bin/subl

3.  Edit your .bash_profile by running this command:

nano .bash_profile

4.  Scroll to the bottom and paste this in on a new line:

function ssgit(){
git clone https://"$1".squarespace.com/template.git "$1";
cd "$1";
subl .;
}

5.  Hit control, hit Y, hit enter

6.  Open a new terminal window (command + n)

7.  Change to a directory where you normally clone sites and try it out:

ssgit your-site-name

And that's it! You'll clone your site, cd into it, and automatically open up the directory in Sublime Text.

No Comments

Chrome Extension: Squarespace Collection / Block Identifier


There are developers on Squarespace who take full advantage of the Developer Platform and build from scratch.  Then there are the more casual types (myself included) who only want to customize some CSS of a template without flipping on Dev Mode, downloading the repo, and pushing code.

Let's say you wanted to change the line height of an individual text block, or the background color of an individual page.  These are usually not options on Squarespace built templates.  Traditionally, the way to accomplish this would be to inspect the element of each page, and grab the Collection ID (the body ID) or the Block ID to write element specific CSS.  That's a pain.

So I've written a Chrome Extension that allows you to easily see and copy the Collection ID or the Block ID of the page you're viewing so you can forget about digging through the inspector.  Just turn on the extension, find the collection ID or the block ID, click the overlay button, and it's copied to your clipboard.

You can install it here

It should work when logged in or out. Feel free to email me if you find any bugs.

No Comments

Adirondack Style Header


Adirondack has a header/site title that shrinks on scroll.  It's a pretty simple effect to implement, but I figured I'd catalogue it here anyways.

Here's the CSS:

#header {
  width: 100%;
  position: fixed;
  text-align: center;
  top: 0;
  left: 0;
  background-color: red;
  z-index: 999;
}
.site-title {
  font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
  font-weight: 700;
  font-style: normal;
  font-size: 3em;
  letter-spacing: 0px;
  line-height: 1.6em;
  text-decoration: none;
  text-transform: uppercase;
  -webkit-transition: all 0.5s ease;
  -moz-transition: all 0.5s ease;
  -o-transition: all 0.5s ease;
  -ms-transition: all 0.5s ease;
}

Basically, you're just fixing the position of the header, and then applying some typography styles to the site title class (usually the h1).  The transition will allow for that 'grow' and 'shrink' effect

Here's the JS:

function animateSiteTitle () {
  var siteTitle = Y.one('#header .site-title a');

  if(window.pageYOffset > 80){
    siteTitle.setStyle('font-size', '1em');
  }

  if(window.pageYOffset < 80){
    siteTitle.setStyle('font-size', '3em');
  }  
}

Y.one(window).on('scroll', animateSiteTitle);

The '80' in the if statements is just a magic scroll number.  Change that number to whatever you like. Quick and dirty, but it should work!

No Comments

Products Pages


Everyone's always wondering about where they can get their hands on products.list, products.item, and products.conf.  I've written some bare-bones markup for each, so that you have a place to start each time you want to build a custom products page.  There are a few notes at the bottom for reference.


products.list

<div id="productList">
  {.repeated section items}
    <a href="{fullUrl}" class="product">
      <div>
        <!-- Display product image -->
          {.main-image?}
            <div class="product-image">
              <img {@|image-meta} />
            </div>
          {.end}

        <!-- product information, like price and title -->
        <div class="product-meta">
          {.section title}
            <p class="product-title">{@}</p>
          {.end}
          <p class="product-price">{@|product-price}</p> 
        </div>

        <!-- this will place the 'SOLD OUT' or 'SALE' flag on the product appropriately -->
        {@|product-status}

      </div>
    </a>
  {.end}
</div>

products.item

{.section item}
  <div id="productWrapper">
    
    <!-- This displays all images/videos associated with the product. Style this accordingly. -->
    <div id="productSlideshow">
      {.repeated section items}
        {.image?}
          <img {@|image-meta} />
        {.end}
        {.video?}
          {@|video}
        {.end}
      {.end}
    </div>

    <!-- This shows the status (sold out/on sale), price, and description (excerpt) text -->
    <div id="productDetails">
      {@|product-status}

      <h1 class="product-title">{title}</h1>

      {@|product-price}

      {.excerpt?}
        <div class="product-excerpt">
          {excerpt}
        </div>
      {.end}

      {@|product-checkout}
    </div>

    <!-- This displays any text/blocks added to the Additional Info tab -->
    {.section body}
    <div class="product-description">
      {@}
    </div>

  </div>
{.end}

products.conf

{
  "title" : "Products",
  "ordering" : "chronological",
  "icon" : "products",
  "pageSize" : 999,
  "addText" : "Add Product",
  "view" : "product-table",
  "acceptTypes" : ["store_item"]
}

notes

You can name these files whatever you want, as long as they all match.  For example, custom-products.list, custom-products.item, custom-products.conf.  That way they're all synced up to each other.

If you choose to name them products.*, you'll overwrite the system collection.  This means that Squarespace automatically provides you with a Products page type, but you'll end up using your own markup. For this reason, I advocate a custom naming convention in case you need to use the system collection later.

Finally, here's a list of helpers and formatters specific to the products page:

  • {@|product-price} - displays price of the product
  • {@|product-status} - displays status text if the product is marked as on sale or sold out
  • {@|product-checkout} - displays the Add to Cart button (includes Variant drop down and Quantity input)
No Comments

All about the Equal Predicate


I came across this interesting question on Answers today and I thought I'd write a brief overview of the Equal Predicate as well as share a quirky discovery here.

In JSONT, the Equal Predicate tests if one argument equals another argument, and returns true or false.  If true, the markup (or code) inside the JSONT is rendered.  

There are three parts to the Equal Predicate:

  1. The predicate itself ".equal?"
  2. The first argument
  3. The second argument

Here's some pseudo code:

{.equal? argument1 argument2}
  <!-- HTML or whatever -->
{.end}

If argument one equals argument two, then the test condition is true and anything inside will be outputted. Here's a quick example:

{.equal? collection.typeName "blog"}
  <h1>Welcome to my Blog page.</h1>
{.end}

 If you check out the JSONT of this page and do a search for typeName, you'll see that its associated value is "blog."  This is a Squarespace thing.  There are different types of pages (collections as they are known) in Squarespace - things like blog, gallery, page, products, events, and album are several examples.

So in the above test, I'm basically asking "is this a blog page? If yes, render an <h1> that says Welcome to my Blog page.  If no, ignore everything in the condition and don't render any code."

Pretty powerful stuff!

Now, there's a catch with this nifty little Equal Predicate.  That catch is:

The first character after the predicate (.equal?) signifies the delimiter for the arguments.

What does that mean in plain english? Take a look at the following example with a test for a specific category.  In this example, we're assuming you're wanting to output some HTML on a specific category filter page. (Example: http://www.bcarroll.us/?category=JSONT )

{.section categoryFilter}
  {.equal? categoryFilter "My Awesome Category"}
    <h2>You're looking at the category "My Awesome Category"</h2>
  {.end}
{.end}

The above code will break!  But why?? Well, because the first character after .equal? is a space. And so, JSONT is saying "okay, all spaces from here on out will tell me that a new argument is next."  And since "My Awesome Category" has two spaces in the whole string, it will treat that one argument as three separate arguments! Oh nooooooo

Well, it's not that big of a deal, because you can use any character to signify the argument delimiter! Here's the above code, written using a new character as the delimiter - namely, the colon! : : : : : : : ) : ) :)

Check it:

{.section categoryFilter}
  {.equal?:categoryFilter:"My Awesome Category"}
    <h2>You're looking at the category "My Awesome Category"</h2>
  {.end}
{.end}

This code will work because the delimiter is set to be a : instead of a space, and the spaces in the string "My Awesome Category" will render as space characters correctly. So now, if you're on the blog list view of the category My Awesome Category, you'll see a super awesome <h2> waiting to tell you which category you're looking at.

Woohoo, good fun. Until next time...

No Comments

Using Git


This post is for those who have never used Git and are afraid of the command line.  By the end of this post, you'll sort of know how to use Git and be only moderately scared of the command line.

What is Git anyways? Git is a version control system.  Let's say you push a bunch of code to your Squarespace site with Git, only to realize you need to revert back to the previous state of the site before the push because you've discovered a bug.  Well, this is what Git is for.  You can easily 'roll back' to the previous version while you figure out what went wrong.

1. Install Git

You can download Git here - if you're on Windows you'll need to take a few extra steps (which are outlined on Git's website).  Going forward, this tutorial assumes you are using a Bash-like Terminal application (this is standard on Mac and Linux machines).  Windows users will need to download a Bash client for the following commands to work.

Once Git is installed, open up your Terminal application (also known as a Command Line Interface, or CLI).  Type in the following:

git --version

This will return the current installed version of Git.  Anything you want to do in the CLI with Git must be preceded with the word 'git.'  So for example:

git --help

or

git add styles/styles.less

Now, let's go over a few useful CLI commands (not specific to Git, but for navigating through folders and filepaths on your computer).

  • ls - short for 'list' - when you type ls and hit enter, a list of files and folders in your current directory will appear.
  • cd [directory-name] - means 'change directory'.  This is how you move inside a folder in the CLI (similar to double clicking a folder if you were doing it the way you normally would on the desktop).  Don't put the actual directory name in square brackets.
  • cd .. - this goes up one level, or back (as if you hit the back button to go back to the previous files and folders).  
  • mkdir [directory-name] - means 'make directory', this creates a new folder at the current file path.
  • pwd - means 'print working directory', which just tells you the current filepath or folder you're in

Okay - that should be enough to move around your computer through the CLI and create files and folders where you need to.  Now let's mix in some Git.


2. Clone your Template Repository

A repository, or repo for short, is just a folder where all your template code and version history lives.  All Squarespace sites are a Git repository by default, which means you can easily clone the repo, make some changes, and push it back to Squarespace.  Ready for your first Git command?

In your Terminal, make a new directory somewhere (remember, mkdir [directory-name] and then move into it (remember, cd [directory-name]). On my own computer, the folder with all my Squarespace sites is in a directory called Squarespace. So here's what that would look like in my CLI:

mkdir Squarespace
cd Squarespace

Now you're inside the Squarespace directory.  Type pwd to be sure of your current path.  Now, type ls in the CLI.  Nothing appears?? That's normal - we just created the directory and there's nothing inside yet.  Let's clone your Squarespace site! Type this:

git clone https://[your-site-name].squarespace.com/template.git [your-site-name]

What just happened? You told Git (by starting with 'git') to 'clone' (or download/copy) the repository hosted at https://[your-site-name].squarespace.com/template.git and put it in a new directory called [your-site-name].  Remember to replace [your-site-name] with whatever your Squarespace URL is (and don't put it in square brackets).  

If you now type ls - you should see one new folder in your Squarespace directory, and that's where your Squarespace template repository lives!

Now, let's move into that new directory.  Type cd [your-site-name] and pwd to be sure of where you are.  Then enter ls to see what this repository has to offer.  It should look something like this:

Awesome.  Leave the Terminal app open for now, but let's open the repo in a text editor so we can make some changes.  You can do this through your Finder.  I don't have to explain this part.  Just open the folder in Sublime Text, or Coda, or whatever you have installed.

Once you've opened it, open your /styles folder and the base.less file.  Make any change at all to the CSS.  Change the background-color of the body element, for example.  Then save it.

Go back to to your Terminal app (CLI), and type in the following command:

git add styles/base.less 

What you're doing is telling git to 'add' the base.less file for git to track changes.  Now, you'll tell git to 'commit' the change to the repository, using the following command:

git commit -m "changed something in base.less"

The flag -m followed by the comment in quotes adds a commit message, so that you can remember what this commit was for.

Finally, push the commit to your Squarespace site using this command:

git push

And those are the basic commands you need to know to clone your repo, track changes, and push commits to your Squarespace site via Git and the CLI!

There are some other useful commands as well, such as git pull (and git pull --rebase origin master) - which pulls the latest code from the repository (in case you are working on the site from two different computers).  Be sure to read the Git documentation to know what you can really do with Git, as it's super powerful.

No Comments

Getting Started with the Squarespace Developer Platform


1. Sign up for Squarespace

When starting your adventure into the Developer Platform, you'll (obviously) first need a Squarespace site.  You can choose to start with one of the consumer Squarespace templates (and you'll have full access to the template code), or you can start with the Base template, which is a bare-bones site that allows you to start from scratch.

Start with a Squarespace Template

Start with the Base Template

Note: Developer sites exist as an unlimited free trial. This means your site will not expire until you are completely ready to launch. So don't worry about paying immediately when you sign up for the trial.

2. Register as a Developer

After you sign up for your Squarespace site, you'll need to register as a developer to gain access to the template code.  Take a look at the left hand side of your site - this is the Squarespace 7 UI and where all the relevant information resides.

Click the default gravatar image above your name in the left corner:

Click 'edit profile' on the dialogue box that appears:

Click the 'Developer' tab and fill out the registration form:

Sweet! Now you're a Developer. Congrats, noob.  Let's get you to post-noob status.


3. Flip on the Developer Toggle

Now that you're registered as a Developer on Squarespace, you'll have access to Developer Mode, which will allow you to Git clone your template repository, or upload/download files via SFTP (more on both later).

Note: If you did not register as a Developer, you will not have access to the Developer Toggle (you'll see a blank section).  Refer to step 2 and don't mess up this time.

Navigate to Settings > Advanced > Developer Mode:

Flip the toggle on!

Flip the toggle on!

Note: You'll see a warning appear when you flip the toggle on.  It's basically saying "you're responsible for your own code" - just be aware that if you create syntax errors when writing code and your site breaks, it's on you to figure out what went wrong.  Although it's not impossible that it's an issue with the Squarespace system, try to determine that for yourself before sending the customer care team an email.

4. Download your Template Files

Alright, here's where you'll see a whole bunch of information that will allow you to connect to your site.  I'll separate this out into SFTP and Git information.  First, here's what the Connectivity Details section looks like:

connectivity.png

SFTP Connection Details:

SFTP Hostname: dev.squarespace.com
SFTP Port: 2030
Username: The email address you used to sign up for Squarespace
Password: Password you chose when signing up for Squarespace

Use the above information in your SFTP client of choice to upload/download template files directly from/to the server.

Git Details:

git clone https://[your-site-url].squarespace.com/template.git

Type the above into your Terminal application to clone your Squarespace template repository.

Note: If you're new to both Git and SFTP, refer to this tutorial which will get you up and running on both

Once you've either cloned your repository or downloaded the template files via SFTP, you should see a file structure that looks like this:

Note: You might see a different file structure depending on the template you started with.  If you started with Base Template, you'll see the above architecture.  If you started with a Squarespace consumer template, you might see varied files inside each folder.

I go into greater detail of each file and folder in this tutorial.  But for now, let's tackle the absolute necessities to get up and running.

  • /assets - Folder where your template assets (static images, font families, etc) live.
  • /blocks - Folder where partials live.  Partials are reusable bits of code (such as a Navigation section).
  • /collections - Folder where 'collection types' live. Collections are Pages, so think the markup for your Blog page, or your Gallery page, or your Products page.
  • /pages - Not to be confused with collections, the /pages folder is for Static page types that can't be changed in the content editor.  Basically, a non-CMS HTML page.
  • /scripts - Where your JavaScript files live
  • /styles - Where your LESS and CSS files live
  • site.region - Your markup - formatted in HTML and JSONT (like a standard .html file).  You can write and combine multiple region files to create dynamic layouts and pages
  • template.conf - Formatted in JSON, this file puts each individual file together into a cohesive site

5. Make Some Changes

To see how this all plays out, create a new file called styles.less in your /styles folder.  Let's add some CSS to change the body background color.  Try this:

body {
  background-color: green;
}

Save that file.  Now, open up your template.conf file and add "styles.less" to the "stylesheets" key's array.  Like this:

"stylesheets" : [ "base.less", "styles.less" ],
Note: You do not need to keep base.less if you don't want to use the basic styles.  Simply remove it from the array.  Always be sure to comma separate any stylesheets you add into the array, and wrap them in quotes.

Your entire template.conf file should now look like this:

{
  "name" : "Base Template",
  "author" : "Squarespace",
  
  "layouts" : {
    "default" : {
      "name" : "Default",
      "regions" : [ "site" ]
    }
  },
  
  "navigations" : [ {
      "title" : "Main Navigation",
      "name" : "mainNav"
  } ],

  "stylesheets" : [ "base.less", "styles.less" ],

  "systemCollections" : [ "products" ]
}

Now save this file.  SFTP or Git add, commit and push your changes (style.less and template.conf) to your site.  Navigate to your site in your browser or refresh the page, and you should now see that your Body's background color is green.  Hooray!

Be sure to check out the Developer Platform Documentation for additional information.  Now go forth and break stuff.

No Comments