GitBlixt
teagles/comfortable-mexican-sofa

rewrote readme

Oleg committed Feb 06, 2011
commit f09393a74e9fcb00eb238da12b2b9af83c155db8
Showing 1 changed file with 110 additions and 104 deletions
README.md +110 -104
@@ @@ -1,11 +1,7 @@
- Comfortable Mexican Sofa (CMS)
- ==============================
+ Comfortable Mexican Sofa (MicroCMS)
+ ===================================
- What is this?
- -------------
- ComfortableMexicanSofa is a micro CMS implemented as a Rails 3.* engine. This CMS is not a full-blown application like RadiantCMS. It's more like the ComatoseCMS, only more modern and infinitely more powerful and flexible. ComfortableMexicanSofa can function as a stand-alone installation, but it's designed to be used as an extension to your Rails application. If you have any (static) content that needs to be managed this CMS will handle it.
-
- This CMS also allows high level of integration. You can easily use page content anywhere within your app, and even use page content as renderable templates from inside your controllers. You may also reuse CMS's admin interface for your own admin backend.
+ ComfortableMexicanSofa is a tiny and powerful micro CMS for your Rails 3 application. This CMS is a plugin for your application, not the other way around. Implemented as an Engine so installation is no different than for any other plugin out there.
Installation
------------
@@ @@ -19,134 +15,144 @@ Then from the Rails project's root run:
rails g cms
rake db:migrate
- At this point you should have database structure created, some assets copied to /public directory and [initializer](https://github.com/twg/comfortable-mexican-sofa/blob/master/config/initializers/comfortable_mexican_sofa.rb) set up.
-
Usage
-----
- Now you should be able to navigate to http://yoursite/cms-admin
+ After finishing installation you should be able to navigate to http://yoursite/cms-admin
- ### Step 1: Create Layout
- Before creating pages and populating them with content we need to create a layout. Layout is the template of your pages. It defines some reusable content (like header and footer, for example) and places where the content goes. A very simple layout can look like this:
+ Default username and password is 'username' and 'password'. You probably want to change it right away. Admin credentials (among other things) can be found and changed in the cms initializer: [/config/initializers/comfortable\_mexican\_sofa.rb](https://github.com/twg/comfortable-mexican-sofa/blob/master/config/initializers/comfortable_mexican_sofa.rb)
+ Before creating pages and populating them with content we need to create a layout. Layout is the template of your pages. It defines some reusable content (like header and footer, for example) and places where the content goes. A very simple layout can look like this:
+
<html>
<body>
- <h1>My Awesome Site</h1>
- {{ cms:page:content }}
+ <h1>{{ cms:page:header:string }}</h1>
+ {{ cms:page:content:text }}
</body>
</html>
-
- So there's your layout and the `{{cms:page:content}}` defines a place where renderable `content` will go. There's just a handful of tags that you can use.
- Layout may also be linked to the `application layout`. As a result cms page content will end up inside `<%= yeild %>` of your application layout.
+ Once you have a layout you may start creating pages and populating content. It's that easy.
- #### Page Blocks
- pieces of content that will be output on the page:
-
- {{ cms:page:some_label:text }} # will render a text area during page creation
- # alternatively you may use: {{ cms:page:some_label }}
- {{ cms:page:some_label:string }} # will render a text field during page creation
- {{ cms:page:some_label:datetime }} # datetime select widget
- {{ cms:page:some_label:integer }} # a number field
+ CMS Tags
+ --------
+ There are a number of cms tags that define where the content goes and how it's populated. **Page** and **Field** tags are used during layout creation. **Snippet**, **Helper** and **Partial** tags can be peppered pretty much anywhere. Tag is structured like so:
+
+ {{ cms:page:content:text }}
+ \ \ \ \
+ \ \ \ ‾ tag format or extra attributes
+ \ \ ‾‾‾‾‾‾‾ label/slug/path for the tag,
+ \ ‾‾‾‾‾‾‾‾‾‾‾‾ tag type (page, field, snippet, helper, partial)
+ ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾ cms tag identifier
+
+ Here's a number of tag variations:
+
+ # Page tags are pieces of text content that will get rendered on the page. Format defines how form field
+ # gets rendered in the page editing/creation section of the admin area.
+
+ {{ cms:page:some_label:text }}
+ {{ cms:page:some_label }} # shorthand for above. 'text' is default format for pages
+ {{ cms:page:some_label:string }} # in admin area text field is displayed instead of textarea
+ {{ cms:page:some_label:datetime }} # similarly, datetime widget in the admin area
+ {{ cms:page:some_label:integer }} # a number field
+ {{ cms:page:some_label:rich_text }} # TinyMCE wysiwyg editor will be used to edit this content
+
+ # Field tags are pieces of text content that are NOT rendered on the page. They can be accessed via
+ # your application's layout / helpers / partials etc. Useful for populating this like <meta> tags.
+ # Field formats are exactly the same as for Page tags.
+
+ {{ cms:field:some_label:string }}
+ {{ cms:field:some_label }} # same as above. 'string' is default format for fields
+
+ # Snippet tags are bits or reusable content that can be used anywhere. Imagine creating content like
+ # a sharing widget, or business address that you want to randomly use across your site.
+
+ {{ cms:snippet:some_label }}
+
+ # Helpers is a wrapper for your regular helpers. Normally you cannot have IRB in CMS content, so there are
+ # tags that allow calling things like helpers and partials.
+
+ {{ cms:helper:method_name }} # same as <%= method_name() %>
+ {{ cms:helper:method_name:x:y:z }} # same as <%= method_name('x', 'y', 'z') %>
+
+ # Partial tags are wrappers just like above helper ones.
+
+ {{ cms:partial:path/to/partial }} # same as <%= render :partial => 'path/to/partial' %>
+ {{ cms:partial:path/to/partial:a:b }} # same as <%= render :partial => 'path/to/partial',
+ # :locals => { :param_1 => 'a', :param_1 => 'b' } %>
+
+ Integrating CMS with your app
+ -----------------------------
+ Comfortable Mexican Sofa is a plugin, so it allows you to easily access content it manages. Here's some things you can do.
- #### Page Fields
- pieces of content that are not rendered. They are useful for hidden values you want to use inside your app. `@cms_page` instance variable is available when you need to access field values.
+ You can use your existing application layout. When creating CMS layouts there's an option to use an application layout. Suddenly all CMS pages using that layout will be rendered through <%= yield %> of your application layout.
- {{ cms:field:some_label:text }} # text area for the page creation form
- {{ cms:field:some_label:string }} # same as {{ cms:field:some_label }}, this is a text field
- {{ cms:field:some_label:datetime }} # datetime
- {{ cms:field:some_label:integer }} # a number field
+ You can use CMS pages as regular views:
+
+ def show
+ @dinosaur = Dinosaur.find(params[:id])
+ # CMS page probably should have either helper or partial tag to display @dinosaur details
+ render :cms_page => '/dinosaur
+ end
+
+ Actually, you don't need to explicitly render a CMS page like that. Sofa will try to rescue a TemplateNotFound by providing a matching CMS page.
- #### Snippets
- bits of reusable content that can be used in pages and layouts
+ You can access **Page** or **Field** tag content directly from your application (layouts/helpers/partials) via `cms_page_content` method. This is how you can pull things like meta tags into your application layout.
- {{ cms:snippet:snippet_slug }}
+ # if @cms_page is available (meaning Sofa is doing the rendering)
+ cms_page_content(:page_or_field_label)
- #### Helpers
- are tags that map to your view helpers methods
+ # anywhere else
+ cms_page_content(:page_or_field_label, CmsPage.find_by_slug(...))
- {{ cms:helper:method_name }} # gets translated to <%= method_name( ) %>
- {{ cms:helper:method_name:x:y:z }} # gets translated to <%= method_name('x', 'y', 'z') %>
+ Similarly you can access **Snippet** content:
- #### Partials
- are exactly that. You don't want to do IRB inside CMS so there's a handy tag:
+ cms_snippet_content(:snippet_slug)
- {{ cms:partial:path/to/partial }} # gets translated to <%= render :partial => 'path/to/partial' %>
- {{ cms:partial:path/to/partial:x:y }} # gets translated to <%= render :partial => 'path/to/partial',
- # :locals => { :param_1 => 'x', :param_2 => 'y'} %>
+ Extending Admin Area
+ --------------------
- ### Step 2: Create Page
- Now you're ready to create a page. Based on how you defined your layout, you should have form inputs ready to be populated.
- Save a page, and it will be accessible from the public side.
-
- Integrating CMS with your app
- -----------------------------
- Unlike most CMS solutions, Sofa is here only to help. Your application is more important. There are few useful ways you can use CMS functionality from your application.
+ If you wish you can re-use Sofa's admin area for things you need to administer in your application. To do this, first of all you need to make your admin controllers to inherit from CmsAdmin::BaseController. This way your admin views will be using Sofa's admin layout and it's basic HttpAuth.
+
+ class Admin::CategoriesController < CmsAdmin::BaseController
+ # your code goes here
+ end
+
+ From your views you can user `cms_form_for` method to re-use Sofa's FormBuilder. There are also some existing styles for tables, will\_paginate helpers, etc. Take a look in [/public/stylesheets/comfortable\_mexican\_sofa/content.css](https://github.com/twg/comfortable-mexican-sofa/blob/master/public/stylesheets/comfortable_mexican_sofa/content.css)
- * When CMS renders a page, you automatically have access to `@cms_page` variable.
- * CMS can take over the rendering of views for your application. For example, http://your-app.local/books hits books\_controller#index and if you don't have a view setup CMS will try to serve a page with '/books' path. You can even force your controller to render a particular page like this: `render :cms_page => '/books'`
+ You probably want to add a navigation link on the left side. For that you want to use ViewHook functionality. Create a partial that has a link to your admin area and declare in in Sofa's initializer: `ComfortableMexicanSofa::ViewHooks.add(:navigation, '/admin/navigation')`. Similarly you can add extra stylesheets, etc into admin area in the same way.
+
+ Do you have other authentication system in place like Devise, AuthLogic, etc and wish to use that? For that you need to create a module that does the authentication check and make Comfortable Mexican Sofa use it. For example:
+
+ module CmsDeviseAuth
+ def authenticate
+ unless current_user && current_user.admin?
+ redirect_to new_user_session_path
+ end
+ end
+ end
+
+ You can put this module in /config/initializers/comfortable\_mexican\_sofa.rb and change authentication method: `config.authentication = 'CmsDeciseAuth'`. Now to access Sofa's admin area users will be authenticated against your existing authentication system.
Working with fixtures
---------------------
- During development it's often more convenient to work with files that can be source controlled, versus putting content in the database and then manage database dump. Thankfully Sofa makes working with fixtures easy.
+ Comfortable Mexican Sofa has fixtures, functionality that helps manage content during development phase. It's very different than Rails seeds as Sofa's fixtures are loaded with each page load. Database is completely bypassed when fixtures are active. This way you can source-control content before going live, disabling fixtures and dumping everything into database.
- ### Setting up Fixtures
- First of all you need to set a path where fixture files will be found:
+ First of all you need to set a path where fixture files will be found (inside Sofa's initializer):
- # in config/initializers/comfortable_mexican_sofa.rb
if Rails.env.development? || Rails.env.test?
ComfortableMexicanSofa.config.seed_data_path = File.expand_path('db/cms_seeds', Rails.root)
end
- This is an example of the file/folder structure for fixtures:
-
- your-site.local/
- - layouts/
- - default_layout.yml
- - pages
- - index.yml
- - help.yml
- - help/
- - more_help.yml
- - snippets
- - random_snippet.yml
-
- Then it's a matter of populating the content. Few rules to remember:
-
- - root page is always index.yml
- - sections of the page are defined by cms\_block\_attributes
- - parent pages are identified by full_path (slug for layouts)
- - folder structure reflects tree structure of the site
-
- Example fixture files for a [layout](https://github.com/twg/comfortable-mexican-sofa/blob/master/test/cms_seeds/test.host/layouts/nested.yml), [page](https://github.com/twg/comfortable-mexican-sofa/blob/master/test/cms_seeds/test.host/pages/child/subchild.yml) and [snippet](https://github.com/twg/comfortable-mexican-sofa/blob/master/test/cms_seeds/test.host/snippets/default.yml)
+ If you ran `rails g cms`, you should find an example set of fixtures in /db/cms\_seeds directory. Each file is an YAML representation of a database entry for that layout/page/snippet.
- **Note:** If ComfortableMexicanSofa.config.seed\_data\_path is set no content is loaded from database. Only fixture files are used.
-
- ### Importing fixtures into database
- Now that you have all those fixture files, how do we get them into database? Easy:
-
- rake comfortable_mexican_sofa:import:all FROM=your-site.local TO=your-site.com SEED_PATH=/path/to/fixtures
+ There's a rake task that makes moving fixtures into database (and vice-versa) easy:
- PATH is optional if seed\_data\_path configuration option is set.
-
- ### Exporting database data into fixtures
- If you need to pull down database content into fixtures it's done as follows:
+ # from fixtures into database
+ rake comfortable_mexican_sofa:import:all FROM=your-site.local TO=your-site.com SEED_PATH=/path/to/fixtures
+ # from database to fixtures
rake comfortable_mexican_sofa:export:all FROM=your-site.com TO=your-site.local SEED_PATH=/path/to/fixtures
- During import/export it will prompt you if there are any files/database entries that are going to be overwritten
-
- Admin Area Integration
- ----------------------
- Sofa has a wonderful admin area. Why would you want to make your own layout, styling and so on if you can reuse what CMS has.
-
- You can easily make your controllers use layouts and CMS authentication like this:
-
- class Admin::UsersController < CmsAdmin::BaseController
- # ...
- end
-
- To add your own tabs to the admin area you can use hooks:
-
- # in config/initializers/comfortable_mexican_sofa.rb
- ComfortableMexicanSofa::ViewHooks.add(:navigation, '/path/to/view/partial')
- ComfortableMexicanSofa::ViewHooks.add(:html_head, '/path/to/view/partial')
+ What else?
+ ----------
+ Versioning control will be eventually implemented. Also I'd love to hear ideas how this CMS can be improved. But feel free to just fork and hack away.
+
\ No newline at end of file