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
|
||||
to users. As with rails, there is great flexibility how this can be
|
||||
achieved, a basic example below.
|
||||
|
||||
## 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.
|
||||
achieved, see wiki for more details.
|
||||
|
||||
## Installation
|
||||
|
||||
Add to your Gemfile:
|
||||
|
||||
```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
|
||||
|
||||
And more info see the wiki
|
||||
|
||||
## Contributing
|
||||
|
||||
Ask first.
|
||||
|
||||
## License
|
||||
|
||||
@ -56,7 +56,7 @@ module ActionDispatch::Routing
|
||||
get ":id" , to: "merged/view#page" , id: :id , as: :view_page
|
||||
|
||||
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
|
||||
end
|
||||
end
|
||||
|
||||
Loading…
Reference in New Issue
Block a user