Developing - envato/guide GitHub Wiki
Table of Contents
Running the test app
- $
bundle install
- $
cd spec/test_app
- $
rails s
- Open http://localhost:3000/guide/structures/friendly/example
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" %>
.
npm install
to install dependenciesnpm run watch
to start live-reload watchify serernpm run build
to build production assets(this is what being used and publish to the gem)npm run lint
to fix javascript code styles
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.