Fleeksite Templating Documentation

templating documentation version 1.0
Updated: December 1, 2018


Introduction


First of all, Thank you so much for supporting the fleeksite templating initiative, you're helping build something great. You are awesome!

This documentation is to help you regarding each step of customization. Please go through the documentation carefully to understand how the templates are made and how to edit this properly. Basic HTML and CSS knowledge is required to customize this template. You may learn basics at: w3 Schools, Mozilla Developers and Shayhowe.

Requirements

You will need the following to build and customize templates.

  1. Web Browser for testing (eg: Google Chrome )

Be careful while editing the template. If not edited properly, the design layout may break completely.
No free support is provided for faulty customization.

Getting Started #back to top

Lorem the It is a long established fact that a reader will be distracted by the readable content of a page when looking at its layout. The point of using Lorem Ipsum is that it has a more-or-less normal distribution of letters, as opposed to using 'Content here, content here', making it look like readable English.


How To Create A Site #back to top

There's going to be a lot of pictures here to make it easy getting started, so here we go:

  1. Head To The Sites Page by click Sites on the menu bar.
  2. Hit The New Site Button and fill the information properly to create the site:
  3. Upon successful submission, you'll be brought back to the sites page, click the name of the site you just created in order to sign into that site.
  4. When you see the big blue words at the top right hand corner change to the site name, it means you're logged into that site.


That's it! You're site is ready to be designed.

How To Install A Theme #back to top

  1. Login to the site you want to upload a template for, you'll know you are logged into the correct site when the sites name appears in big blue letters at the top left hand corner of the admin .
  2. Hover over the design option and go to all templates:
  3. On The Templates Page, click the upload template button:
  4. Next, click the choose files button and select your UNZIPPED* folder using GOOGLE CHROME*, then hit upload.

That's it!

That's all there is to adding a new template or uploading your site.

Creating A Post #back to top

  1. Hover over the content dropdown and click all
  2. Click the Curate button and fill the form, the image is optional, but if you do not upload the primary image here, you will need to set it inside in the post editing section.
  3. Click Create and you'll be directing to the post editing page.
  4. You'll find numerous different sections depending on the type of post, have a look through and fill the appropriate sections.
  5. At the bottom you will find the option to upload images, upon uploading an image, you can choose to set the image as primary by clicking the star or delete the image by clicking the trash can.

How To Use Liquid #back to top

Liquid is the templating engine that Fleeksite uses in order to render dynamic data into the templates. Eg. from the content section.

We'll be going through all the basics you'll need to know to build a full fledged website.


There are two main types of operators in liquid:

  1. Tags
  2. Filters


Tags

These are denoted by a curly brace and a percentage sign, eg.

{% collection blogs %}


In the example above, a request is being made to MMS (the platform fleeksite runs on) to get blog posts for the current site, the tag is called collection, so the format is {% valid_tag options %}.

We can add a little more detail to this as well:

{% collection blogs, limit: 7, order: desc title, tag: featured %}

In this example, we are filtering the blogs by only getting blogs with the tag featured, then we are ordering the blogs by title, then finally limiting the number of blogs we get to 7.

Pretty useful and simple right?

great!


There are a number of tags, if you enter an invalid tag, then nothing will happen.


Filters

These are denoted by a pipe or vertical bar |. eg.

{{ apple pie | split: }}


This little piece of code takes apple pie and splits it at the spaces, what you'd be left with is a list of two words, apple and pie.


Custom Tags


We have just two custom tags here at Fleeksite:

  1. Collections
  2. Partials


See the Liquid Documentation at the links below for further guidance:

  1. https://shopify.github.io/liquid/
  2. Liquid for Designers · Shopify/liquid Wiki · GitHub
  3. https://github.com/bettyblocks/liquid-elixir/tree/master/test/templates

Templates #back to top

Posts #back to top

We'll be looking at all the fields available for posts as well as the use of extra fields.

tags - a list of strings - separated by comma's,
title - a string,
user_id - the user who created the post ,
sold - if the product is already sold,
published_at - date the post was published to the site/ made public,
cover_image - the url of the primary image of the post,
uid - a unique identifier of the post,
file_id - the primary attachment's id,
permalink - the slug of the post,
meta - a map of the meta information of the post eg. meta[title] = Great Post,
body - the main content of the post,
price - the price of the product,
quantity - the remaining quantity of the product,
unit - the unit the product is measured in,
updated_at - the date the post was last updated,
label - an arbitrary label for the post,
expires_at - the date the post will expire/be removed from the site,
external_link - a link to an external resource,
status - published/draft,
user_sub - to identify posts submitted by users - true/false,
inserted_at - date the post was created,
teaser - the preview/summary/teaser for the post

We'll be taking a look at the cool uses of bits in your code.

Bits are cool snippets of text or html that you can inject into your site, they allows users to be able to change more elements of their site without having to know how to code, there are two (and perhaps another is on its way), ways of using bits in the code.

lets, say we create a bit named facebook.

_________________________DEPRECATED________________________________________
We'll add into our code {{bits.facebook}}. and whatever value is in that bit, will appear in that spot.

Next we have the bit_lists, lets say we have a category of bits called social, we can do this:
{% for bit in bit_list %}
 {% if bit.category == social %}
  {{bit.name}}: {{bit.value}}
 {% endif %}
{% endfor %}

_________________________UPDATED SEPTEMBER 10 2018________________________________________

Now Our New Bit Model:

{{bits.social.facekook}}

{% for bit in bit_list.social %}
 {{bit.name}}: {{bit.value}}
{% endfor %}

This will allow more flexibility in the bits, bits across categories can have similar names and for loops are much shorter and they'll involve less code.
Share your input with us @ support@fleeksite.com



Sites #back to top

A list of the fields available when templating for the site.

logo - The URL of the logo of the site,
meta_description - the meta description of the site,
language - the language the site uses,
mobile - the phone number of the site,
meta_keywords - the meta key words of the site,
favicon - the sites favicon,
timezone - the timezone of the site (affects publish and expiration dates),
name - the name of the site ,
fax - the fax of the site,
postal_code - the sites postal code ,
address - the address of the site,
about - the about/description of the site,
email - the sites email,
country - the sites country,
region - the sites region,
city - the sites city,
meta_title - the sites meta title,
domain - the sites domain

Single Posts #back to top

How To Make Single Page Templates

When you want to create a template for a single blog or product you'll have to use a special notation for the permalink, this lets MMS know what type of template you are creating ;

A Blog Template Example:

permlink - :blog

The permalink starts with a colon - letting the system know that this is a template page for a single post,
After the colon comes the type of post that the template is for - blogs.

The same patter matches up with all the other post types, :product, :testimonial, :location, :landing, :page... etc

The attributes of that post can be accessed directly like so:

{{title}}
{{body}}
{{updated_at}}

instead of the forloop notation {{blog.title}}, {{blog.body}} ..etc

adding multiple templates for blogs or any other post type will make that template show in the themes dropdown inside the content editor, the default theme is set to the first theme that was made

What about if you put multiple pictures inside a piece of content? how do you get to them?
Like this:
{% for image in media %}
 {{image.url}}
{% endfor %}







Auto Resizing Images #back to top

An Image Resizer Comes Built In With The Fleeksite Templating Solution, Here's How It's Used

While our image server implements;
Blurring
Cropping
Resizing

We'll only be implementing resizing until further notice, you can however use the other methods by making a request for permissions to support@fleeksite.com

To resize an image, use the liquid resize filter like so:
{{ cover_image | resize: '500x500' }}

The first dimension is the width and the second is the height.

This resizing process resizes the image on the first request, then compresses the image by 5% and caches that image for all requests afterwards.


Forms #back to top

How To Use Forms and the various options you can pass in.

Forms are in integral part of your website, it's how people will contact you and submit leads.

Here are some common parameters to pass into your forms:

  1. success_url - this tells the server where to send the user next, after the form has been successfully submitted and processed. - Maybe a thank you page?
  2. failure_url - this does the opposite, it's where the user will be sent if the form is not processed successfully.

What are the endpoints that a form should go to?
  1. /api/lead - leads are submitted to the endpoint via a post request
  2. /ap/post - users can create posts on your website and they will be marked as user submitted, they will not be published by default.


Javascript Calls #back to top

How To Load Your Posts and Comments Using Javascript

Sometimes, you want to use javascript to load your assets - and we've got you covered.


We have a few endpoints:

/api/v1

GET REQUESTS


/POSTS

/ - to load your posts, pass the same parameters you would in the liquid tags.
/{{uid}} - to load a specific post


/USERS

/ - to load your user, pass the same parameters you would in the liquid tags.
/{{uid}} - to load a specific user

/COMMENTS

/comments/{{parent_id}} - to load the comments of a post where the parent_id is the id of the post.


POST REQUESTS


/COMMENTS
/ - creates a comment, requires the parent_id, which is the post_id and the body of the comment
/like - likes a comment, requires only the id of the comment
/delete - deletes a comment, requires only the id of the comment



Pagination #back to top

A Shell To Implement A Custom Styled Pagination

   {% if blogs.pagination.page > 1 %}
     {% for page in blogs.pagination.last_pages %}
       {% if page != blogs.pagination.page %}
           {{page}}                  
       {% endif %}
     {% endfor %}
     {% if blogs.pagination.more %} 
          {{blogs.pagination.page}}
         {% for page in blogs.pagination.next_pages %}
            {% if page != blogs.pagination.page and page > blogs.pagination.page %}
               {{page}}                    
            {% endif %}
         {% endfor %}
     {% endif %}     
   {% else %}
     {% if blogs.pagination.total_entries > blogs.pagination.page_size %}
          {% if blogs.pagination.more %}  
             {{blogs.pagination.page}}                    
          {% endif %}
          {% for page in blogs.pagination.next_pages %}
             {% if page != blogs.pagination.page and page > blogs.pagination.page %}
                {{page}}                    
             {% endif %}
          {% endfor %}
     {% endif %}
  {% endif %}

Bypass Liquid Parsing #back to top

How To Stop A Page From Being Rendered By Liquid

To do this simply start the page with

<%= no_render %>

Adaptive Images #back to top

The host of content distribution methods available on the FleekSite Website Development Platform

We take asset delivery pretty seriously, so we've tried various different companies for our image storage and even built our own custom solutions.


Right now we deliver images using:


Amazon Simple Storage Service

Amazon CloudFront CDN

FleekSite Image Server (Resize)

FleekSite Root Image API

FleekSite Imgix CDN



So there's no shortage of methods for getting your images delivery as fast as possible. So how do we use these images dynamically in liquid ?


You use the {{image_url}} variable, this will automatically fill in with FleekSites current preferred image delivery method to ensure you have the fastest loading images.


The plan is to allow users to choose their delivery methods eventually, but for now FleekSite will automatically choose it for you, saving you the thought.

Collections #back to top

The collection tag is denoted by
{% collection %}

A collection tag is used to pull data to be displayed on a page from the content section of a site.

These are the valid collections:
blogs,products,videos,landings,pictures,audio,videos,pages,testimonials,locations

There are a number of options when using a collection tag, they are:

name - this tells mms the variable name you want to reference the collection as while you are doing your templating eg.
{% collection blogs, name: featured_blogs %}

tag - this tells mms to filter by posts only with this specific tag, eg.
{% collection products, tag: special %}
{% for product in products.entries %}
  {{product.title}}
{% endfor %}

{% collection users, limit: 4 %}
{% for user in users.entries %}
  Hi! {{user.first_name}} {{user.last_name}}
  {{user.tags}} : {{ user.tags | contains: 'tag' }}
  {% assign random_tag = user.tags | random %}
  {{random_tag}}
{% endfor %}


order - this tells mms the order in which the posts should be ordered, eg.
{% collection landings, order: inserted_at desc %}

limit - this tells mms how many posts you want, eg.
{% collection pages, limit: 5 %}

override_page - this tells mms that you'd like to use the page_size parameter from the url of the page instead of a hard limit set in liquid, eg.
{% collection pictures, override_page: true %}

starred - this tells mms to only get posts that have been favourited, eg.
{% collection blogs, starred: true %}

user_sub - this tells mms to only get posts that have been submitted by users, eg.
{% collection blogs, user_sub: true %}

label - this tells mms to only get posts that have a specific label, eg.
{% collection blogs, label: tech %}

status - this tells mms to only get posts with a specific status, eg.
{% collection blogs, status: Draft %}

starred - this tells mms to only get posts that have been favourited, eg.
{% collection blogs, starred: true %}

user - this tells mms to only get posts that have been made by a specific user, eg. (where the users id is 230)
{% collection blogs, user: 230 %}




Conditionals #back to top

A Quick Look At Conditional Tags

The if tag is a basic conditional operator, eg.
{% if 4 > 5 %}
 less is greater
{% elsif 3 == 2 %}
 3 is 2
{% else %}
 neither
{% endif %}

{% if 'apples' like 'apple' %}
  true
{% else %}
  false
{% endif %}

{% if 'apples' contains 'apple' %} 
  true 
{% else %} 
  false 
{% endif %}
        

The if tag must be closed with an endif tag.


The Unless Tag
{% unless name == PearOrAvacado %}
 {{role}}
{% else %}
 {{other_role}}
{% endunless %}


The Case Tag

{% case a.size %}
 {% when 1 %}
  Small
 {% when 2 %}
  Big
{% endcase %}


Partials #back to top

The partial tag is denoted by

{% partial %}


A partial tag is used to put one page or partial into another page, the name of the partial is the name of the page that you want to pull. eg.

{% partial menu %}


This example would look for the template with the title menu and replace the partial block on the page, with whatever is in the menu template.


For Loops #back to top

We'll take a quick look at the functionalities of the for loop

{% collection pages, limit: 10, tag: fun, name: things %}
{% for thing in things %} 
 {% if forloop.first %}
  {{thing.name}}
 {% elsif forloop.last %}
  {{forloop.index}}
 {% endif %}
{% endfor %}



{%for i in array.items limit: 3 %}
  {{i}}
{%endfor%}
next
{%for i in array.items offset:continue limit: 3 %}
  {{i}}
{%endfor%}
next
{%for i in array.items offset:continue limit: 3 %}
  {{i}}
{%endfor%}



{%for i in array.items offset:continue limit:3 %}
  {{i}}
{%endfor%}