{"name":"Homeflow api","tagline":"","body":"- [Home](/homeflow/homeflow_api/wiki)\r\n- [Getting started](/homeflow/homeflow_api/wiki/ctesius#getting-started)\r\n\t- [Theme folder structure](/homeflow/homeflow_api/wiki/ctesius#theme-folder-structure)\r\n\t- [The layout file](/homeflow/homeflow_api/wiki/ctesius#the-layout-file)\r\n\t- [Building up the layout](/homeflow/homeflow_api/wiki/ctesius#building-up-the-layout)\r\n\t- [Running your theme](/homeflow/homeflow_api/wiki/ctesius#running-your-theme)\r\n- [Application & home page](/homeflow/homeflow_api/wiki/ctesius#building-up-the-application-and-home-page)\r\n\t- [The header](/homeflow/homeflow_api/wiki/ctesius#the-header-with-an-agency-or-portal-logo)\r\n\t- [The navigation menu](/homeflow/homeflow_api/wiki/ctesius#the-navigation-menu)\r\n\t- [The carousel](/homeflow/homeflow_api/wiki/ctesius#the-carousel)\r\n\t- [The footer](/homeflow/homeflow_api/wiki/ctesius#the-footer)\r\n- [Property Searching](/homeflow/homeflow_api/wiki/ctesius#working-with-property-searches)\r\n\t- [Property search form](/homeflow/homeflow_api/wiki/ctesius/working-with-property-searches#constructing-a-property-search-form)\r\n\t- [Displaying search results](/homeflow/homeflow_api/wiki/ctesius#displaying-search-results)\r\n\t- [The properties loop](/homeflow/homeflow_api/wiki/ctesius#the-properties-loop)\r\n\t- [Locations and postcodes](/homeflow/homeflow_api/wiki/ctesius#handling-with-locations-and-postcodes)\r\n\t- [Headings and pagination](/homeflow/homeflow_api/wiki/ctesius#headings-and-pagination)\r\n\t- [More on pagination](/homeflow/homeflow_api/wiki/ctesius#more-on-pagination)\r\n\t- [Togglable areas](/homeflow/homeflow_api/wiki/ctesius#togglable-areas)\r\n\t- [Working with map views](/homeflow/homeflow_api/wiki/ctesius#working-with-the-map-view)\r\n\t- [Working with grid views](/homeflow/homeflow_api/wiki/ctesius#working-with-grid-views)\r\n\t- [Saving to shortlist](/homeflow/homeflow_api/wiki/ctesius#saving-properties-to-a-shortlist)\r\n\t- [Saving searches](/homeflow/homeflow_api/wiki/ctesius#saving-searches)\r\n- [Draw a Map](/homeflow/homeflow_api/wiki/ctesius#draw-a-map)\r\n- [The property show page](/homeflow/homeflow_api/wiki/ctesius#the-property-show-page)\r\n\t- [Outputting basic information](/homeflow/homeflow_api/wiki/ctesius#outputting-basic-information)\r\n\t- [Other property drops](/homeflow/homeflow_api/wiki/ctesius#other-property-drops)\r\n\t- [Working with maps](/homeflow/homeflow_api/wiki/ctesius#working-with-maps)\r\n\t- [Submitting a lead](/homeflow/homeflow_api/wiki/ctesius#submitting-a-lead)\r\n- [Working with agencies](/homeflow/homeflow_api/wiki/ctesius#working-with-agencies)\r\n\t- [Agency show page](/homeflow/homeflow_api/wiki/ctesius#the-agency-show-page)\r\n- [Working with branches](/homeflow/homeflow_api/wiki/ctesius#working-with-branches)\r\n\t- [The branches index](/homeflow/homeflow_api/wiki/ctesius#the-branches-index)\r\n\t- [Branch maps](/homeflow/homeflow_api/wiki/ctesius#working-with-branch-maps)\r\n\t- [Branch searching](/homeflow/homeflow_api/wiki/ctesius#branch-searching)\r\n\t- [Titles and pagination](/homeflow/homeflow_api/wiki/ctesius#branch-titles-and-pagination)\r\n\t- [The branch show](/homeflow/homeflow_api/wiki/ctesius#the-branch-show)\r\n\t- [Branch properties](/homeflow/homeflow_api/wiki/ctesius#displaying-branch-properties)\r\n\t\t- [Recent sales and lettings](/homeflow/homeflow_api/wiki/ctesius#displaying-branch-properties)\r\n\t\t- [All branch properties](/homeflow/homeflow_api/wiki/ctesius#all-branch-properties)\r\n\r\n#The Homeflow API\r\n\r\nHi there and welcome to the Homeflow wiki.\r\n\r\nHomeflow provides developers with everything they need to build exceptional property based websites. Within this Wiki we hope you will find all the information you need to get your agency or portal theme up and running.\r\n\r\nYou'll use the IDE you're familiar with plus all the developer tools you know and love such as: HTML, CSS, JavaScript and jQuery. You will make your own decisions on the plugins you or your customer requires and have complete design control over your new website from the word go.\r\n\r\nAs alluded to above, we're making the assumption that you're familiar with HTML, CSS etc. You will also need a basic working knowledge of Git and Liquid, though both are relatively simple to pick up as you go along.\r\n\r\nBefore we get started, there are three areas of the Homeflow API to be aware of as they will be mentioned throughout this documentation:\r\n\r\n1) The Agency/Portal Admin
\r\n2) Hestia
\r\n3) Ctesius\r\n\r\nYou can consider The Agency and Portal Admin as the repository of all the information related to an agency or portal (essentially a CMS) - think properties, pages, content, images and more. Hestia (The Greek Goddess of the Heart) allows the querying of this information at lightning fast speeds. Finally Ctesius (The Greek God of Property) is our frontend application that is powered by Hestia. It includes an event management system, supports advanced property searching, user profiling and will support and augment the theme you will build. \r\n\r\nAll themes are developed using mostly HTML, CSS and JavaScript, but they also make use of the Liquid templating system, made popular by Shopify. Liquid sits in places of your code where dynamic content is required, such as property, agency, staff or user information.\r\n\r\nWe will explore all of the technologies mentioned above in much more detail later in the Wiki. In the meantime you can head straight over to the section you require using the menu on the right or move on to [Getting started](/homeflow/homeflow_api/wiki/ctesius#getting-started).\r\n\r\n#Getting started\r\n\r\nFirstly 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. \r\n\r\nOnce we have done this we will create you an account on ``Gitlab`` (our internal Git platform) and you will receive an automatic email containing your login information. Before you can get to work on your theme, your will need to supply Gitlab with your ``Public SSH key``. This is so you can clone and push/pull to and from your theme's repository. For information on how to fetch or generate your SSH key, visit [this link](https://help.github.com/articles/generating-ssh-keys#platform-mac). \r\n\r\nThis link will take you to the SSH section on Homeflow where you can paste in your key: ``http://hades.homeflow.co.uk/keys``.\r\n\r\nTo 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:\r\n\r\n``git clone ``\r\n\r\nYour Git clone URL will look something like: ``git@hades.homeflow.co.uk:fdesign/pantani.git``.\r\n\r\nBy 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. \r\n\r\n##Theme folder structure\r\n\r\nCtesius 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](https://github.com/homeflow/stabilisers).\r\n\r\n- theme_name\t\t\r\n\t- agencies\r\n\t\t- index.liquid\r\n\t\t- show.liquid\r\n\t- articles\r\n\t\t- index.liquid\r\n\t\t- show.liquid\r\n\t- assets\r\n\t\t- images\r\n\t\t- javascripts\r\n\t\t- stylesheets\r\n\t\t\t- theme_styles.lcss - our LCSS file holds our styles just as a CSS file would\r\n\t- branches\r\n\t\t- _branches_list.ljson - a JSON view to list an array of branches\r\n\t\t- index.liquid\r\n\t\t- show.liquid\r\n\t- home\r\n\t\t- home.liquid - the main homepage\r\n\t- layouts\r\n \t\t- application.liquid - the main layout file which renders the other pages\r\n\t- pages\r\n\t\t- show.liquid\r\n\t- properties\r\n\t\t- _properties_list.ljson - a JSON view to list an array of properties\r\n\t\t- index.liquid\r\n\t\t- show.liquid\r\n\t- staff\r\n\t\t- index.liquid\r\n\t\t- show.liquid\r\n\t- user\r\n\t\t- new.liquid\r\n\r\nIf 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:\r\n\r\n``git commit -a -m 'Theme folders and files'``\r\n\r\nThen run:\r\n\r\n``git push origin master``\r\n\r\nThis 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.\r\n\r\n##The layout File\r\n\r\nEvery 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.\r\n\r\nTake 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:\r\n\r\n```\r\n {{ \"application\" | javascript_include_tag }}\r\n {{ \"application\" | stylesheet_link_tag }}\r\n```\r\n\r\nThis will bring in all the default styles and some JavaScript libraries which form the basis of every Ctesius theme. As of the latest revision to this Wiki, they are:\r\n\r\n- Bootstrap\r\n- jQuery - v1.9\r\n- jQuery Cycle - 3.0.3 (11-JUL-2013)\r\n- jQuery Nivo Slider\r\n- Backbone.js - 1.0.0\r\n- Underscore.js - 1.4.3\r\n- leaflet.js\r\n- Font Awesome\r\n- the Homeflow search and profile system\r\n\r\nYou'll also notice that we make another call:\r\n\r\n``{{ \"stabilisers\" | theme_stylesheet_link_tag }}``\r\n\r\nThere 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.\r\n\r\nContinuing with the layout file the next command you'll see is:\r\n\r\n``{% include 'layouts/js_templates' %}``\r\n\r\nThis 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.\r\n\r\nThe 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.\r\n\r\nPerhaps the most important section for the layout is the helper ``content_for_layout``. This outputs the rendered results of the rest of the template.\r\n\r\n``{{ content_for_layout }}``\r\n\r\nIn other words, all other template parts are like partials that get evaluated and loaded into this section.\r\n\r\nFinally we need to boot the Ctesius system to handle searches, user profiles and so on. To do that we add the following function: \r\n\r\n``` \r\n \r\n```\r\n\r\nThis 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.\r\n\r\n##Building up the layout\r\n\r\nOther 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:\r\n\r\n``{{ \"your_theme_css\" | theme_stylesheet_link_tag }}``\r\n\r\nWe talk more about images in the [Working with images and assets](./assets) section, but for now add your agency's/portal's logo into the ``/assets/images`` folder and reference it in your application markup as follows:\r\n\r\n````\r\n\r\nYou 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.\r\n\r\n##Running your theme\r\n\r\nNow 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:\r\n\r\nAgencies: ``http://agency_homeflow_domain.agent.staging.homeflow.co.uk``
\r\nPortals: ``http://portal_homeflow_domain.search.staging.homeflow.co.uk``\r\n\r\nHopefully you will see the result in the browser.\r\n \r\n##Building up the application and home page\r\n\r\nAt this point we can start to think about the elements that will be consistent to every page and those that will just reside on the home page. Those that are consistent to every page need to reside in the application.liquid file and would probably include:\r\n\r\n- The header\r\n- The navigation menu\r\n- The footer\r\n\r\n##The header with an agency or portal logo\r\n\r\nA header would probably consist of the agency or portal logo, so let's take a first foray into the Agency or Portal admin, add the logo, then pull it out and plug it into the source using Liquid. Note that if you'd rather just add or keep your logo in ``/assets/images`` that's absolutely fine.\r\n\r\nTo get to your admin, you use a link similar to the two links outlined before:\r\n\r\nAgencies: ``http://agency_homeflow_domain.homeflow.co.uk/admin``
\r\nPortals: ``http://portal_homeflow_domain.portal.homeflow.co.uk/admin``\r\n\r\nWe'll assume you have been provided with your login.\r\n\r\nIn the agency admin, go to ``Website/Appearance/Logos`` and upload your logo
\r\nIn the portal admin, go to ``Configure/Appearance/Logos`` and upload your portal logo.\r\n\r\nNow in your source, within your header tags or header div tags, add:\r\n\r\nAgency:
\r\n````\r\n\r\nPortal:
\r\n````\r\n\r\nThere's a couple of new things here - the first is we need a ``key`` when referencing an agency or portal logo (and many other things as we'll see) and we're using the agency and portal Liquid name tag to fill in the alt attribute of the image. As you become more experienced with your template(s) you will find there's some useful and sometimes innovative ways you can use tags.\r\n\r\n##The navigation menu\r\n\r\nThe navigation is another area where you have complete freedom of development - if you wanted to hardcode your menu and add/remove new or old items as they come along, that's absolutely fine. If however, you'd prefer to add the navigation tree to the agency admin and extract them using Liquid, that's fine too. Generally speaking portals add their menu to their source whereas theme designers or agency sites will tend to code the menu using Liquid, as their theme can then be deployed for multiple agencies.\r\n\r\nLet's assume for now you would like to query the agency admin and therefore Hestia for the menu and, if it has been added, its sub-menu counterpart.\r\n\r\nTo start head over to your agency admin. Reminder: ``http://agency_homeflow_domain.homeflow.co.uk/admin``\r\n\r\nThen go to ``Website/Navigation``. From here you can drag in menu items for existing pages or create custom links, e.g. to the ``/branches`` page for example. Once you've got your primary menu items, you can then edit each one and add sub-menu items.\r\n\r\nHere's a code construct that would retrieve the primary menu items:\r\n\r\n```\r\n{% assign primary_menu = 'primary' | site_menu %}\r\n
{{property.price}}
\r\n\t{{property.short_description | truncate : 185}}
\r\n\t\r\n\r\n\t\t\t{{branch.description | strip_tags | truncate : 250}}\r\n\t\t
\r\n\t\t\r\n\t\t\tMore Information\r\n\t\t
\r\n\t\r\n\t\t{{branch.description_with_agency_fallback | strip_html}}\r\n\t
\r\n{% endif %}\r\n```\r\n\r\nThis nifty bit of code will try and get the branch description, but if it's empty, we'll get the agency description. Note that it is unlikely an agent will not have a description for their branch AND their agency, but it's always good practice to check. Notice also we're stripping the HTML as sometimes some links and other formatting gets added to the description which can wreak havoc on our layout.\r\n\r\nStaff profiles are a whole subject unto themselves which we will look at later in the Wiki but for now, if you wanted to display some mini profiles with links to full profiles, or just give you branch pages the human touch, you could use something like:\r\n\r\n```\r\n{% unless branch.staff_profiles.size == 0 %}\r\n\t