Firstly we will need to initialise a Git repository for your theme on our platform and provide it with an API key so it can query Hestia and get the information it needs. You don’t need to do anything here and it’s a stage we will automate in the future.
An account on our internal Git platform is required and a valid SSH key will need to be uploaded for you to use our platform. If we have not already created and supplied an account to you, you can obtain this by contacting support@homeflow.co.uk.
Before you start developing for the Homeflow platform we recommend you read our best practices guide.
For information on how to fetch or generate your SSH key, visit this link.
If you are using Windows then the easiest way to use Git is to download Git’s native app. Visit this link for more information.
Once you have generated your keys, navigate to where they are saved and copy the contents of the public key. Next, log in here and paste in your key.
To clone your repository, open up a command prompt and cd to directory of your choice (but one that you won’t forget and is easy to get to!) and run the following:
git clone <link>
Your Git clone URL will look something like: git@hades.homeflow.co.uk:fdesign/pantani.git.
By this point we should have provided you with a staging link so you/your team/your customer can view the development progress of the site. Once you have added your public key and you have successfully cloned your repository, we can now start to put your theme’s folder structure together.
Ctesius themes use the standard Rails conventions for folder layouts. Don’t worry if you’re not familiar with Rails or this structure as an example theme folder structure can be seen below or found on the demo Stabilisers theme.
- theme_name
- agencies
- index.liquid
- show.liquid
- articles
- index.liquid
- show.liquid
- assets
- images
- javascripts
- stylesheets
- theme_styles.lcss - our LCSS file holds our CSS styles
- branches
- _branches_list.ljson - a JSON view to list an array of branches
- index.liquid
- show.liquid
- home
- home.liquid - the main homepage
- layouts
- application.liquid - the main layout file
- pages
- show.liquid
- properties
- _properties_list.ljson - a JSON view to list an array of properties
- index.liquid
- show.liquid
- staff
- index.liquid
- show.liquid
- user
- new.liquidIf your repository doesn’t have these files and folders yet, add them in. Once done, make your first commit and push to your repository. We would recommend a Git GUI such as Tower for OSx or one of the freebies available for Linux such as Git Cola. If you’re using Git via the command line, bring up a terminal, cd to you theme’s root directory and run:
git commit -a -m 'Theme folders and files'Then run: git push origin master
This will add all of your modified files, commit them as well as push them to the remote repository. We can’t view the site online just yet as there’s nothing to render. Time to add some structure and content to our application.liquid file.
Every page render starts at the layout, which is always found in /layouts/application.liquid. This file will contain the html, head, and body tags and will define the overall ‘makeup’ of your site.
Take a look at the source in the Stabilisers theme and you will see there’s a few things to note. Firstly we link to the default styles and JavaScripts using our first bit of Liquid syntax:
{{ "application" | javascript_include_tag }}
{{ "application" | stylesheet_link_tag }}This will bring in all the default styles and some JavaScript libraries which form the basis of every Ctesius theme.
You’ll also notice that we make another call:
{{ "stabilisers" | theme_stylesheet_link_tag }}There is a subtle different between the two Liquid directives in that the latter has a theme_ directive and the other does not. When you add a theme stylesheet or theme JavaScript directive, the theme will expect the quoted LCSS file to reside in /assets/stylesheets (/assets/javascripts for JavaScript files). LCSS files are pretty much CSS files run through a Liquid filter. This enables us to customise the CSS easily for different sites. The directive without the theme pointer will load something from the core app.
Continuing with the layout file the next command you’ll see is:
{% include 'layouts/js_templates' %}This is the first include that we’ve seen. A bit like PHP includes, Liquid includes allow you include a partial template. This is excellent for including blocks that occur on several pages, or, as we’ll see later, in Liquid for loops. Important point: partial names must be preceeded by an underscore _. When you call the partial however, no underscore is required though you must put the path in quotes.
The directive here pulls in the default JavaScript templates for the dynamically drawn user sections of the site. They are all overridable so you can design them as you need to. We’ll expand more on these templates later.
Perhaps the most important section for the layout is the helper content_for_layout. This outputs the rendered results of the rest of the template.
{{ content_for_layout }}In other words, all other template parts are like partials that get evaluated and loaded into this section.
Finally we need to boot the Ctesius system to handle searches, user profiles and so on. To do that we add the following function:
<script type="text/javascript">
$(document).ready(function(){
Ctesius.init()
});
</script>This needs to be used after any Ctesius events or config options are set. Some theme developers choose to add this function at the foot of application.liquid whereas others will add it to a theme JavaScripts file, include the directive at the bottom of it, then include the partial.
Asset packs are required for all the assets on the site to run properly. These include both theme specific and Homeflow template assets.
You can find more information about asset packs here.
Other than the Liquid directives in the head section, the content_for_layout we saw earlier and the Ctesius boot, the application.liquid file is constructed just the same as a regular web page - add your classes and IDs, divs and CSS in the normal way and style them up using your theme CSS. Be sure to to put it in the stylesheets directive and make sure the names match up:
{{ "your_theme_css" | theme_stylesheet_link_tag }}We talk more about images later but for now, add your agency’s/portal’s logo into the /assets/images folder and reference it in your application markup as follows:
<img src="{{'your_image.png' | theme_image_url : "70x70" }}" />You will notice that we have added a Liquid directive straight into the source of the image. Liquid will expect there to be an image of the name and extension quoted in your theme images folder (/assets/images). Also note that we’ve added an arguement on the end to ask Liquid to resize the image on the server, then send it to the browser - neat.
Now that you have hopefully added your HTML, some CSS and some images, it’s time to see the results. Commit and push your changes and observe the staging URL we sent to you. It will look something like:
Agencies: http://agency_homeflow_domain.agent.staging.homeflow.co.uk
Portals: http://portal_homeflow_domain.search.staging.homeflow.co.uk
Hopefully you will see the result in the browser.
You will have the access to push any code to the staging server. Homeflow developers will primarily be using a different branch and server to push their changes so as not to conflict with the staging box. This box will run off the following URL:
http://agency_homeflow_domain.dev.staging.homeflow.co.uk
At suitable times during the build process it might be necessary to push the theme live to the production server. This is something that Homeflow will have to do manually due to the potential implications on other live sites.
It is important to note that the staging server has minimal caching on it and therefore it will run at noticeably slower speed than the production box.