From 38963e49be5c8e14b3b8f685b57475a700173473 Mon Sep 17 00:00:00 2001 From: Azul Date: Tue, 8 Apr 2014 11:23:18 +0200 Subject: update documentation: included core in toplevel now we only include some engines - we don't build the whole webapp based on them. Reflecting this in the documentation. --- CUSTOM.md | 4 ++-- DEVELOP.md | 44 ++++++++++---------------------------------- 2 files changed, 12 insertions(+), 36 deletions(-) diff --git a/CUSTOM.md b/CUSTOM.md index 8671323..53e4d88 100644 --- a/CUSTOM.md +++ b/CUSTOM.md @@ -9,6 +9,6 @@ See config/customization/README.md Engines --------------------- -Leap Web is based on Engines. All things in `app` will overwrite the default behaviour. You can either create a new rails app and include the leap_web gem or clone the leap web repository and add your customizations to the `app` directory. +Leap Web includes some Engines. All things in `app` will overwrite the engine behaviour. You can clone the leap web repository and add your customizations to the `app` directory. Including leap_web as a gem is currently not supported. It should not require too much work though and we would be happy to include the changes required. -If you have no use for one of the engines you can remove it from the Gemfile. Not however that your app might still need to provide some functionality for the other engines to work. For example the users engine provides `current_user` and other methods. +If you have no use for one of the engines you can remove it from the Gemfile. Engines should really be plugins - no other engines should depend upon them. If you need functionality in different engines it should probably go into the toplevel. The 'users' engine will soon become part of the main webapp for that reason. diff --git a/DEVELOP.md b/DEVELOP.md index 6aeccff..43af04d 100644 --- a/DEVELOP.md +++ b/DEVELOP.md @@ -5,21 +5,23 @@ Some tips on modifying the views: * Many of the forms use [simple_form gem](https://github.com/plataformatec/simple_form) +* We still use client_side_validations for the validation code but since it is not maintained anymore we want to drop it asap. ## Engines ## -Leap Web consists of different Engines. They live in their own subdirectory and are included through bundler via their path. This way changes to the engines immediately affect the server as if they were in the main `app` directory. +Leap Web contains some. They live in their own subdirectory and are included through bundler via their path. This way changes to the engines immediately affect the server as if they were in the main `app` directory. -Currently Leap Web consists of 5 Engines: +Currently Leap Web includes of 4 Engines: -* [core](https://github.com/leapcode/leap_web/blob/master/core) - ships some dependencies that are used accross all engines. This might be removed at some point. -* [users](https://github.com/leapcode/leap_web/blob/master/users) - user registration and authorization -* [certs](https://github.com/leapcode/leap_web/blob/master/certs) - Cert distribution for the EIP client +* [users](https://github.com/leapcode/leap_web/blob/master/users) - user registration and authorization - this will probably be included in the main webapp any time soon +* [certs](https://github.com/leapcode/leap_web/blob/master/certs) - Cert distribution for the EIP client - might be included in toplevel too. * [help](https://github.com/leapcode/leap_web/blob/master/help) - Help ticket management * [billing](https://github.com/leapcode/leap_web/blob/master/billing) - Billing System ## Creating a new engine ## +If you want to add functionality to the webapp but keep it easy to remove you might consider adding an engine. This only makes sense if your engine really is a plugin - so no other pieces of code depend on it. + ### Rails plugin new ### Create the basic tree structure for an engine using @@ -32,28 +34,10 @@ rails plugin new ENGINE_NAME -O --full See http://guides.rubyonrails.org/engines.html for more general info about engines. -### Require Leap Web Core and dependencies ### - -Leap Web Core provides a common set of dependencies for the engines with CouchRest Model etc. -It also comes with an optional set of UI gems like haml, sass, coffeescript, uglifier, bootstrap-sass, jquery and simple_form. +You need to require engine specific gems in lib/my_engine/engine.rb: -In order to use the core dependencies you need to add leap_web_core to your .gemspec: ```ruby -# make sure LeapWeb::VERSION is available -require File.expand_path('../../lib/leap_web/version.rb', __FILE__) -# ... - Gem::Specification.new do |s| - # ... - s.add_dependency "rails" - s.add_dependency "leap_web_core", LeapWeb::Version - end -``` - -You also need to require it before you define your engine in lib/my_engine/engine.rb: -```ruby -require "leap_web_core" -# uncomment if you want the ui gems: -# require "leap_web_core/ui_dependencies" +require "my_dependency" module MyEngine class Engine < ::Rails::Engine @@ -62,17 +46,9 @@ module MyEngine end ``` -Some development and UI dependencies can not be loaded via leap_web_core. To make them available add the following lines to your engines Gemfile - -```ruby - eval(File.read(File.dirname(__FILE__) + '/../common_dependencies.rb')) - # uncomment if you want the ui gems: - # eval(File.read(File.dirname(__FILE__) + '/../ui_dependencies.rb')) -``` - ## Creating Models ## -You can use the normal rails generators to create models. Since you required the leap_web_core gem you will be using CouchRest::Model. So your models inherit from CouchRest::Model::Base. +You can use the normal rails generators to create models. You probably want to require couchrest_model so your models inherit from CouchRest::Model::Base. http://www.couchrest.info/model/definition.html has some good first steps for setting up the model. CouchRest Model behaved strangely when using a model without a design block. So make sure to define an initial view: http://www.couchrest.info/model/view_objects.html . -- cgit v1.2.3