Breeze is a rails 7 engine (ie standard practise..) and has an install generator.
After which you have to decide on the routes and authentication.
How to set up a machine for editors is covered below
Demo first
Breeze is mounted, but read only
Use
Learn how to use
Styles
Create your own styles
**Get the gem**
Add to your Gemfile and bundle
```shell
gem "breeze_cms" , "~> 1.0.1"
```
```shell
bundle
```
And run the installer:
```shell
bundle exec rails breeze:install
```
Look at `config/initializers/breeze.rb` and adjust if you need
**Routes**
Add routes using routes helper (no routes are generated by the generator).
Normally the engine is not mounted in production, only viewing routes are always created by the engine.
```ruby
Rails.application.routes.draw do
breeze_routes(options_hash)
end
```
Use production: true , to mount in production , or root: true to define the root to index.
Breeze generates a route for any page you define. And it generates redirects if you rename a page.
Access the back-end under [localhost:3000/breeze/pages](/breezy/pages)
Stylesheets, Authentication, SEO
These need some adjusting, unfortunately for tailwind it gets a little tricky. This is because it is not possible to have several tailwind stylesheets in use, and so we need to distinguish between apps that use tailwind themselves or not.
**Apps using tailwind**
If you use tailwind with the tailwind gem, you need to edit the tailwind config.
Basically it is impossible to have [two tailwind generated stylesheets](https://stackoverflow.com/questions/71232601/how-to-use-tailwind-css-gem-in-a-rails-7-engine/74737193#74737193), so your app needs to pick up the breeze styles. This can be configured like so:
```
const output = execSync('bundle show breeze', { encoding: 'utf-8' });
const fullname = output.trim() + '/**/*.{haml,html,rb}' ;
module.exports = {
content: [
fullname ,
.... as before
]
```
Also, breeze overrides some tailwind styles (especially prose/markdown), so if you want to use markdown i suggest importing the `breeze/tailwind_styles` into your `application.css`. This is pure css, and does not need to be processed by tailwind.
**Apps not using tailwind**
Include breeze stylesheet to your layout or asset pipeline.
```
= stylesheet_link_tag "application"
= stylesheet_link_tag "breeze/breeze"
```
**Authentication**
If your ApplicationController has a `authenticate_member!` it will be called before any breeze action (in the backend). Currently there is no way to configure devise user class (obviously we assume Member) , but you can use it to call whatever you use, ie ` authenticate_user! `
Breeze backend logs all changes and calls `current_member_email` to do so. If your controller responds to `current_member`, that will be used, otherwise a dummy. Override `current_member_email` to return your users email if you wish.
**SEO**
Meaning how to get meaningful titles and description into your page, since Breeze is not actually rendering the header. *content_for* to the rescue!
A breeze page defines **content_for :title** and **:description**. So you need to add those to the html header, eg like so:
```
%title= yield( :title)
%meta{ name: "description" , content: yield(:description)}/
```
Also breeze sets the alt tag for images to the image name. Since the actual images are numbered,it pays to make those names good.
Basic Setup
In it's most basic usage the developer uses the cms herself. And creates new templates as needed.
Or maybe a copywriter creates text and a (junior) developer does the edit.
A dedicated cms developer should be picked in this case to avoid git conflicts, of ids if nothing else.
**Part time editors**
Editors may sometimes use the developers machine. Either physically or remotely (on the same network).
Dedicated staging machine
A developer sets up a dedicated staging machine on an intranet/lan. Ie access is restricted by physical access, either to the machine, or the lan.
Users, or editors, may still need an account, (set up by a developer) and for ultimate safely the machine can be made to listen on localhost only. Ie a normal developer machine, and only that machine may be used to edit the content.
The developers reviews changes, if branches are used merges, and deploys. Ie the developer always deploys.
Installation
Breeze is a rails 7 engine (ie standard practise..) and has an install generator.
After which you have to decide on the routes and authentication.
How to set up a machine for editors is covered below
Demo first
Breeze is mounted, but read only
Use
Learn how to use
Styles
Create your own styles
**Get the gem**
Add to your Gemfile and bundle
```shell
gem "breeze_cms" , "~> 1.0.1"
```
```shell
bundle
```
And run the installer:
```shell
bundle exec rails breeze:install
```
Look at `config/initializers/breeze.rb` and adjust if you need
**Routes**
Add routes using routes helper (no routes are generated by the generator).
Normally the engine is not mounted in production, only viewing routes are always created by the engine.
```ruby
Rails.application.routes.draw do
breeze_routes(options_hash)
end
```
Use production: true , to mount in production , or root: true to define the root to index.
Breeze generates a route for any page you define. And it generates redirects if you rename a page.
Access the back-end under [localhost:3000/breeze/pages](/breezy/pages)
Stylesheets, Authentication, SEO
These need some adjusting, unfortunately for tailwind it gets a little tricky. This is because it is not possible to have several tailwind stylesheets in use, and so we need to distinguish between apps that use tailwind themselves or not.
**Apps using tailwind**
If you use tailwind with the tailwind gem, you need to edit the tailwind config.
Basically it is impossible to have [two tailwind generated stylesheets](https://stackoverflow.com/questions/71232601/how-to-use-tailwind-css-gem-in-a-rails-7-engine/74737193#74737193), so your app needs to pick up the breeze styles. This can be configured like so:
```
const output = execSync('bundle show breeze', { encoding: 'utf-8' });
const fullname = output.trim() + '/**/*.{haml,html,rb}' ;
module.exports = {
content: [
fullname ,
.... as before
]
```
Also, breeze overrides some tailwind styles (especially prose/markdown), so if you want to use markdown i suggest importing the `breeze/tailwind_styles` into your `application.css`. This is pure css, and does not need to be processed by tailwind.
**Apps not using tailwind**
Include breeze stylesheet to your layout or asset pipeline.
```
= stylesheet_link_tag "application"
= stylesheet_link_tag "breeze/breeze"
```
**Authentication**
If your ApplicationController has a `authenticate_member!` it will be called before any breeze action (in the backend). Currently there is no way to configure devise user class (obviously we assume Member) , but you can use it to call whatever you use, ie ` authenticate_user! `
Breeze backend logs all changes and calls `current_member_email` to do so. If your controller responds to `current_member`, that will be used, otherwise a dummy. Override `current_member_email` to return your users email if you wish.
**SEO**
Meaning how to get meaningful titles and description into your page, since Breeze is not actually rendering the header. *content_for* to the rescue!
A breeze page defines **content_for :title** and **:description**. So you need to add those to the html header, eg like so:
```
%title= yield( :title)
%meta{ name: "description" , content: yield(:description)}/
```
Also breeze sets the alt tag for images to the image name. Since the actual images are numbered,it pays to make those names good.
Basic Setup
In it's most basic usage the developer uses the cms herself. And creates new templates as needed.
Or maybe a copywriter creates text and a (junior) developer does the edit.
A dedicated cms developer should be picked in this case to avoid git conflicts, of ids if nothing else.
**Part time editors**
Editors may sometimes use the developers machine. Either physically or remotely (on the same network).
Dedicated staging machine
A developer sets up a dedicated staging machine on an intranet/lan. Ie access is restricted by physical access, either to the machine, or the lan.
Users, or editors, may still need an account, (set up by a developer) and for ultimate safely the machine can be made to listen on localhost only. Ie a normal developer machine, and only that machine may be used to edit the content.
The developers reviews changes, if branches are used merges, and deploys. Ie the developer always deploys.
