Developing - envato/guide Wiki

Original URL: https://github.com/envato/guide/wiki/Developing

Table of Contents


Running the test app

Note: Make sure your running at least Ruby 2.1 (you can set version by running rbenv shell 2.1.5 and re-re-running bundle install).


JavaScript

This app uses browserify to bundle client-side JavaScript files.

To start adding new JavaScript file to the project, simply add it to javascript/application.js. Source code will be compiled to app/assets/javascripts/guide/application and load through <%= javascript_include_tag "guide/application" %>.


Local Gem development

TODO: How to specify local gem in your project

Specify source

gem 'guide', :git => "git://github.com/guide/guide.git", :ref => "4aded"
gem 'guide', :git => "git://github.com/guide/guide.git", :branch => "1-0-stable"
gem 'guide', :git => "git://github.com/guide/guide.git", :tag => "v1.0.0"

Model definitions

Internal to Guide gem

Bouncer

Responsible for access control of Guide content.

Content

Where all of the Guide content for your app lives.

Monkey

Given a node_path, the Monkey will navigate the tree and fetch the node that you asked for.

Nobilizer

Used to turn a node_path into nice fancy strings for display.

Scout

Given a node_path, the Scout can look along the path to the node and tell you the highest level of permission that you need in order to access it.

Arborist

Tell it where your content tree starts and it will give you a list of all of leaf nodes on the tree.

Cartographer

Tell it where your content tree starts and it will give you a list of all of the nodes that can be rendered.

Diplomat

This object figures out a locale for you based on the params, session and default. It can also tell you about which locales you have supported in configuration.

Node

A node is a point on the content tree. Everything in the content folder is a node.

Structure

This type of node can manage a list of scenarios, so that we can render a piece of the UI as it would look in lots of different situations.

Document

This type of node has no scenarios, but is still renderable. It corresponds to a static template, usually with the same name, in the same folder.

Photographer

Sometimes we want to display images in our content. The Photographer sorts out asset paths so that we don’t have to link directly to them within nodes or (worse) templates.

Simulator

When we want to render a specific scenario for a structure, we ask the simulator to find it for us. It will throw an error if the scenario does not exist or we are not allowed to access it.

ViewModel

Our templates generally rely on view models (presenters) to give them data, but we don’t want to hook them up to our real back end. When we render a template in Guide, we give it one of these ViewModel objects instead. They inherit from OpenStruct, so it’s easy to fake out the return values of method calls.

FormObject

Sometimes we create an object whose job it is to power a form in a template. This is a bit like a view model, except it usually handles some validation tasks as well. A commonly used gem called Simple Form relies on these validation powers and will throw errors if we try to render one of its forms without them. When you need a form object in your template, you can give it one of these things instead.