move readme to wiki
This commit is contained in:
parent
b44c29ff50
commit
5b0ccafc0e
168
README.md
168
README.md
@ -10,176 +10,14 @@ branches, possible staging, possible reviews and controlled deploys.
|
|||||||
|
|
||||||
Merged is designed for developers to give limited editing facilities
|
Merged is designed for developers to give limited editing facilities
|
||||||
to users. As with rails, there is great flexibility how this can be
|
to users. As with rails, there is great flexibility how this can be
|
||||||
achieved, a basic example below.
|
achieved, see wiki for more details.
|
||||||
|
|
||||||
## Concepts
|
|
||||||
|
|
||||||
Merged has simple but powerful concepts and structures to define
|
|
||||||
the interactions users may have.
|
|
||||||
|
|
||||||
### Page
|
|
||||||
|
|
||||||
The core entity that may be edited is a Page. Pages contain Sections
|
|
||||||
(below) in a way defined by developers.
|
|
||||||
|
|
||||||
A Page has a type, different types may define different layouts, or rather types of Sections they may include.
|
|
||||||
|
|
||||||
A page has a name which is it's Url, Merged is not designed for nesting currently.
|
|
||||||
|
|
||||||
All data that users change is stored in the Pages' Yaml, which get
|
|
||||||
committed and __merged__ to propagate to the site.
|
|
||||||
|
|
||||||
A Page also has data, attributes and options, see below.
|
|
||||||
|
|
||||||
### Sections
|
|
||||||
|
|
||||||
Merged itself defines many styles of sections, and off course
|
|
||||||
developers may define more.
|
|
||||||
For example a Header with text is a section, a hero section is a section, and a card section is a different style.
|
|
||||||
|
|
||||||
The only defining characteristic of a section is really that it is full width, and it has a template that renders the content.
|
|
||||||
|
|
||||||
A Page may contain as many sections as the Page definition allows.
|
|
||||||
|
|
||||||
A Section in turn may contain cards.
|
|
||||||
|
|
||||||
Like a Page, a Section may have options.
|
|
||||||
|
|
||||||
### Cards
|
|
||||||
|
|
||||||
Cards, as in general css lingo, are usually smaller html boxes,
|
|
||||||
usually contained in a grid (defined by the Section). But they may
|
|
||||||
be form fields, or features (svg).
|
|
||||||
|
|
||||||
Cards have data and options like the other elements.
|
|
||||||
|
|
||||||
### Image
|
|
||||||
|
|
||||||
Merged also manages images, adding deleting, renaming, even a small editor.
|
|
||||||
Images are stored in the assets folder. With the Pages, Sections and Cards they
|
|
||||||
define the content that users can change.
|
|
||||||
|
|
||||||
Images merge into the upstream in the same way as the pages, through
|
|
||||||
git actions (partially done by Merged)
|
|
||||||
|
|
||||||
### Change (-sets)
|
|
||||||
|
|
||||||
As data is in files, all change happens by git.
|
|
||||||
Merged partially manages this, by making changes visible to the
|
|
||||||
users, ie what Pages and Images were added/removed or edited.
|
|
||||||
Merged can commit and in the future maybe even push.
|
|
||||||
|
|
||||||
Merged requires a user to be logged in and will log all changes, meaning
|
|
||||||
change times and the email of the editor. The last change is displayed in
|
|
||||||
the ui for auditing purposes.
|
|
||||||
|
|
||||||
## Basic setup
|
|
||||||
|
|
||||||
A developer set up a machine on a intranet/lan. Ie access is
|
|
||||||
restricted by physical access.
|
|
||||||
|
|
||||||
The machine is set up as a developer machine, on a "feature" branch.
|
|
||||||
A User may use the machine to edit and commit and push (the branch).
|
|
||||||
|
|
||||||
The developer reviews, merges changes and deploys.
|
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
Add to your Gemfile:
|
And more info see the wiki
|
||||||
|
|
||||||
```ruby
|
|
||||||
gem "merged" , git: "https://github.com/HubFeenixMakers/merged"
|
|
||||||
```
|
|
||||||
|
|
||||||
And then bundle:
|
|
||||||
```bash
|
|
||||||
$ bundle
|
|
||||||
```
|
|
||||||
|
|
||||||
Mount engine in routes for editing (possibly not in production).
|
|
||||||
|
|
||||||
```ruby
|
|
||||||
mount Merged::Engine => "/merged" unless Rails.env.production?
|
|
||||||
```
|
|
||||||
|
|
||||||
Create route to serve content.
|
|
||||||
```ruby
|
|
||||||
get ":id" , to: "merged/view#page" , id: :id
|
|
||||||
```
|
|
||||||
|
|
||||||
If Merged served the root:
|
|
||||||
```ruby
|
|
||||||
root "merged/view#page" , id: 'index'
|
|
||||||
```
|
|
||||||
|
|
||||||
### Stylesheets
|
|
||||||
|
|
||||||
#### Apps not using tailwind
|
|
||||||
|
|
||||||
Include merged stylesheet to your layout or asset
|
|
||||||
pipeline.
|
|
||||||
|
|
||||||
```
|
|
||||||
= stylesheet_link_tag "application"
|
|
||||||
= stylesheet_link_tag "merged/merged"
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 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, so your app needs to pick up the merged styles. This can be configured like so:
|
|
||||||
|
|
||||||
```
|
|
||||||
const output = execSync('bundle show merged', { encoding: 'utf-8' });
|
|
||||||
const fullname = output.trim() + '/app/**/*.{haml,html,rb}' ;
|
|
||||||
|
|
||||||
|
|
||||||
module.exports = {
|
|
||||||
content: [
|
|
||||||
fullname ,
|
|
||||||
.... as before
|
|
||||||
]
|
|
||||||
```
|
|
||||||
|
|
||||||
Also, merged overrides some tailwind styles (especially prose/markdown),
|
|
||||||
so if you want to use markdown i suggest importing the `merged/tailwind_styles` into your application.css. This is pure css, and does not
|
|
||||||
need to be processed by tailwind.
|
|
||||||
|
|
||||||
|
|
||||||
## Developers
|
|
||||||
|
|
||||||
### Styles
|
|
||||||
|
|
||||||
Developers should look at the predefined styles. These are found in
|
|
||||||
merged gem /config/merged/**style.yml
|
|
||||||
|
|
||||||
And on a running app http://localhost:3000/merged/styles/index
|
|
||||||
|
|
||||||
### Section Views
|
|
||||||
|
|
||||||
These are under app/views/merged/views/sections/*haml
|
|
||||||
and the name of the file matches the section_style entry
|
|
||||||
|
|
||||||
Developers may define more section styles, but must provide the partials to render them.
|
|
||||||
|
|
||||||
### Card Views
|
|
||||||
|
|
||||||
These are under app/views/merged/views/cards/*haml
|
|
||||||
and the name of the file matches the card entry.
|
|
||||||
|
|
||||||
Developers may define more card styles, but must provide the partials to render them.
|
|
||||||
|
|
||||||
### Options
|
|
||||||
|
|
||||||
Option definitions (also found under style dir) are common between elements.
|
|
||||||
Options may be added and then used in the view partials. Many common ones (background,
|
|
||||||
color) and many more are already defined.
|
|
||||||
|
|
||||||
To make the partials more dry, Helpers are defined in OptionsHelper
|
|
||||||
|
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
Ask first.
|
Ask first.
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
@ -56,7 +56,7 @@ module ActionDispatch::Routing
|
|||||||
get ":id" , to: "merged/view#page" , id: :id , as: :view_page
|
get ":id" , to: "merged/view#page" , id: :id , as: :view_page
|
||||||
|
|
||||||
engine_path = options[:path] || "/merged"
|
engine_path = options[:path] || "/merged"
|
||||||
if ! Rails.env.production? or !options[:production].truthy?
|
if ! Rails.env.production? or options[:production].present?
|
||||||
mount Merged::Engine => engine_path
|
mount Merged::Engine => engine_path
|
||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
Loading…
Reference in New Issue
Block a user