Foodsoft/foodsoft
1
1
Fork 0
Code Issues 36 Pull requests 5 Projects 1 Releases Wiki Activity

cleanup doc markup [ci skip]

Browse source
This commit is contained in:
wvengen 2014-06-01 00:46:43 +02:00
parent 24b0628825
commit 63e2ec9d49
8 changed files with 649 additions and 708 deletions
Download patch file Download diff file Expand all files Collapse all files

8
doc/DEPLOYMENT.md
View file

@ -6,11 +6,9 @@ Setup
1. Initialise your [Capistrano](http://capistranorb.com/) setup
```sh
bundle exec cap install
sed -i 's|^# \(require.*rails.*\)|\1|' Capfile
cp config/deploy.rb.SAMPLE config/deploy.rb
```
bundle exec cap install
sed -i 's|^# \(require.*rails.*\)|\1|' Capfile
cp config/deploy.rb.SAMPLE config/deploy.rb
When you're using [RVM](http://rvm.io/) on the server you may want to
uncomment the corresponding line in `Capfile`.

95
doc/SETUP_DEVELOPMENT.md
View file

@ -14,44 +14,41 @@ Getting started
---------------
0. Clone the repository from GitHub:
```
git clone https://github.com/foodcoops/foodsoft.git
```
git clone https://github.com/foodcoops/foodsoft.git
This brings up the bleeding-edge development version, which might contain some
unfinished parts. If you want to be safe, choose the last release:
`git checkout $(git tag -l | grep ^v | sort -rn | head -n1)`
1. Install RVM and Ruby 2.0 (if you have not done so before):
```
\curl -L https://get.rvm.io | bash
source ~/.rvm/scripts/rvm
rvm install 2.0
```
\curl -L https://get.rvm.io | bash
source ~/.rvm/scripts/rvm
rvm install 2.0
We try to keep foodsoft compatible with Ruby 1.9.3 as well as any later versions,
so if you have those and don't want to use RVM, that might actually work.
2. Install Ruby dependencies:
```
bundle install
```
bundle install
3. Setup your development environment:
```
rake foodsoft:setup_development
```
rake foodsoft:setup_development
This will interactively prompt with several questions relating to your
required environment.
4. Start rails by running:
```
bundle exec rails s
```
bundle exec rails s
5. Open your favorite browser and open the web application at:
```
http://localhost:3000/
```
http://localhost:3000/
You might want to watch a
[kitten video](https://www.youtube.com/watch?v=9Iq5yCoHp4o)
while it's loading.
@ -75,21 +72,20 @@ explained here.
1. **Configure database**
Create the database configuration from the default:
```sh
cp config/database.yml.SQLite_SAMPLE config/database.yml
```
cp config/database.yml.SQLite_SAMPLE config/database.yml
If you are fine with using a file-based sqlite database you are all set.
The sqlite files (development/test/production) will reside in the "db"
The sqlite files (`development/test/production`) will reside in the `db`
directory. Otherwise you would want to copy one of the other
"database.yml.*_SAMPLE" files and edit database.yml to suit your needs.
`database.yml.*_SAMPLE` files and edit `database.yml` to suit your needs.
2. **Configure development environment**
Again, you need to create your own copy of the default configuration:
```
cp config/environments/development.rb.SAMPLE config/environments/development.rb
```
cp config/environments/development.rb.SAMPLE config/environments/development.rb
Edit development.rb to specify your settings (at least the ActionMailer SMTP
settings). If you just leave the file as is, emails will not work but
@ -99,10 +95,10 @@ explained here.
3. **Foodsoft settings**
You need to create your own copy of the foodsoft configuration settings:
```
cp config/app_config.yml.SAMPLE config/app_config.yml
```
Edit app_config.yml to suit your needs or just keep the defaults for now.
cp config/app_config.yml.SAMPLE config/app_config.yml
Edit `app_config.yml` to suit your needs or just keep the defaults for now.
4. **Secret token**
@ -110,16 +106,16 @@ explained here.
The user session are stored in cookies. Do avoid misusing the cookies and
its sensitive information, rails will encrypt it with a token. So copy the
config file
```
cp config/initializers/secret_token.rb.SAMPLE config/initializers/secret_token.rb
```
cp config/initializers/secret_token.rb.SAMPLE config/initializers/secret_token.rb
and modify the token!! You can run `bundle exec rake secret`
5. **Create database (schema) and load defaults**
```
rake db:setup
```
rake db:setup
With this, you also get a ready to go user with username 'admin' and
password 'secret'.
@ -129,13 +125,12 @@ explained here.
We use for time intensive tasks a background job queue, at the moment resque
with redis as key/value store. Install redis (in ubuntu the package
redis-server works out of the box) and start the resque worker with:
```
rake resque:work QUEUE=foodsoft_notifier
```
rake resque:work QUEUE=foodsoft_notifier
To have look on the current queue, failed jobs etc start the resque server with
```
resque-web
```
resque-web
7. (optional) **View mails in browser** instead in your logs
@ -143,10 +138,10 @@ explained here.
We use mailcatcher in development mode to view all delivered mails in a
browser interface. Just install mailcatcher with gem install mailcatcher
and start the service with
```
mailcatcher
```
mailcatcher
From now on you have a smtp server listening on 1025. To see the emails go to
```
http://localhost:1080
```
http://localhost:1080

50
doc/design_patterns/publish_subscribe.md
View file

@ -1,32 +1,58 @@
# Publish/subscribe pattern
## Handling DOM updates after AJAX database manipulation
As an example, let us consider the manipulation (create, update...) of `StockArticles`. This can be done in different views, e.g., `stock_articles/index`, `stock_articles/show` and `deliveries/_form` through modals using AJAX requests. As an advantage of the AJAX technique, the user does not need to reload the entire page. However, (after the update of the `StockArticle` in the database) it is generally required to update the DOM in the current view such that the page properly reacts to the asynchronous actions.
As an example, let us consider the manipulation (create, update...) of
`StockArticles`. This can be done in different views, e.g.,
`stock_articles/index`, `stock_articles/show` and `deliveries/_form` through
modals using AJAX requests. As an advantage of the AJAX technique, the user
does not need to reload the entire page. However, (after the update of the
`StockArticle` in the database) it is generally required to update the DOM in
the current view such that the page properly reacts to the asynchronous
actions.
The process can be divided in two steps: **1.** AJAX database manipulation and **2.** DOM updates for the particular view. The crucial point is the coupling of the two steps since the controller for the first step offers the same functionality to all views and does not need to know anything about the current view.
The process can be divided in two steps:
### 1. AJAX database manipulation
**(i)** Example: current view `deliveries/_form` offers a link for the AJAX action `StockArticle#new`. This opens a modal filled with `stock_articles/_form`.
1. AJAX database manipulation and
2. DOM updates for the particular view.
**(ii)** AJAX form post addresses the `StockArticle#create` action which handles the database manipulation.
The crucial point is the coupling of the two steps since the controller for the
first step offers the same functionality to all views and does not need to know
anything about the current view.
**(iii)** The database manipulation is finished by the rendering of, e.g., `stock_articles/create.js.erb`. The key task there is to **publish** the database changes by calling `trigger`, i.e.,
### AJAX database manipulation
**(i)** Example: current view `deliveries/_form` offers a link for the AJAX
action `StockArticle#new`. This opens a modal filled with
`stock_articles/_form`.
**(ii)** AJAX form post addresses the `StockArticle#create` action which
handles the database manipulation.
**(iii)** The database manipulation is finished by the rendering of, e.g.,
`stock_articles/create.js.erb`. The key task there is to **publish** the
database changes by calling `trigger`, i.e.,
$(document).trigger({
type: 'StockArticle#create',
stock_article_id: <%= @stock_article.id %>
});
### 2. DOM updates for the particular view
**(i)** Each view has the opportunity to **subscribe** to particular events of the previous step. A very simple example is the update of the `stock_articles/index` view after `StockArticle#destroy`:
### DOM updates for the particular view
**(i)** Each view has the opportunity to **subscribe** to particular events
of the previous step. A very simple example is the update of the
`stock_articles/index` view after `StockArticle#destroy`:
$(document).on('StockArticle#destroy', function(e) {
$('#stockArticle-' + e.stock_article_id).remove();
});
However, in most of the situations you will like to use the full power of the MVC framework in order to read new data from the database and render some partial. Let us consider this slightly more advanced case in the following.
However, in most of the situations you will like to use the full power of the
MVC framework in order to read new data from the database and render some
partial. Let us consider this slightly more advanced case in the following.
The view `stock_articles/index` could listen (amongst others) to `StockArticle#create` like this:
The view `stock_articles/index` could listen (amongst others) to
`StockArticle#create` like this:
$(document).on('StockArticle#create', function(e) {
$.ajax({
@ -37,4 +63,6 @@ The view `stock_articles/index` could listen (amongst others) to `StockArticle#c
});
});
**(ii)** The action `StockArticles#index_on_stock_article_create` is a special helper action to handle DOM updates of the `stock_articles/index` view after the creation of a new `StockArticle` with the given `id`.
**(ii)** The action `StockArticles#index_on_stock_article_create` is a special
helper action to handle DOM updates of the `stock_articles/index` view after
the creation of a new `StockArticle` with the given `id`.