Skip to content

Latest commit

 

History

History
174 lines (111 loc) · 5.6 KB

quickstart-guide.md

File metadata and controls

174 lines (111 loc) · 5.6 KB
Raw

Quickstart Guide

This installation guide is for a Rails 7.0 application.

If you are starting from scratch, install Rails via:

gem install rails -v '~> 7.0.0'

Installation

  1. Add the gem to your Gemfile and run bundle install.
gem 'fae-rails'
  1. Run Fae's installer.
rails g fae:install
  1. Start your Rails server and visit http://localhost:3000/admin to setup your super admin user.

That's it, you are up and running with Fae!

An Example CMS

To give you an idea of where to go from there, here is a brief walkthrough of an example CMS setup. This example CMS will manage articles, the article categories they belong to and content on an about page.

Fae's Scaffold Generator

To add an object to manage in Fae, you can use Fae's built in generators to create all necessary files. They are built on the Rails generators and work very similarly.

First let's scaffold our ArticleCategory object:

rails g fae:scaffold ArticleCategory name:string position:integer

Next is our Article object:

rails g fae:scaffold Article title:string slug:string introduction:text body:text date:date hero_image:image pdf:file article_category:references

This one has a couple special Fae moves in it. image and file are custom attribute types that setup everything Fae needs to manage those assets.

Learn more about managing images and files

Fae's Page Generator

Fae has a built-in pages module that let's you define content blocks on a page as attributes on a model. This allows you to get content for an about page via AboutUsPage.instance instead of dealing with hard-coded IDs.

To use this module, you'll have to follow Fae's convention, but we have a custom generator to get you started.

To generate content blocks for an AboutUsPage:

rails g fae:page AboutUs hero_image:image headline:string body:text

Learn more about content blocks and pages

Finally, let's add the scaffolded objects to the database:

rails db:migrate

Use rake db:migrate with Rails 4

Customizing the Forms

With those four commands we are now able to manage those three objects in our CMS. There are some things we can do now to make these forms easier to work with.

Article Categories

Go to http://localhost:3000/admin/article_categories and add/update a couple categories. You'll notice that Fae picked up the position attribute and automatically made the categories sortable in the index view.

Articles

Now let's go to create a new article at http://localhost:3000/admin/articles/new. This form already does the job, but let's make it better. Fae's generators create files in your application so you can customize this form as you please.

Open app/views/admin/articles/_form.html.slim and focus on the main.content section where the form fields are:

main.content
  = fae_input f, :title
  = fae_input f, :slug
  = fae_input f, :introduction
  = fae_input f, :body
  = fae_input f, :date

  = fae_association f, :article_category

  = fae_image_form f, :hero_image
  = fae_file_form f, :pdf

Automatically generate the slug from content in the title.

Fae's form helpers offer many options to help you customize. Let's add a class to the title field to trigger Fae's slugger feature:

= fae_input f, :title, input_class: 'slugger'

Learn more about Fae's slugger

Add a markdown editor to body.

= fae_input f, :body, markdown: true

Add a datepicker to date.

Fae also has a number of other form helpers that provide a variety of UI elements.

fae_datepicker f, :date

See documentation on all form helpers

Form Validations

Fae's forms will honor any standard validation rules defined in the model. Fae even has some helpers for common validation scenerios.

To add form validations to our articles, we just need to define them in app/models/article.rb:

validates :title, presence: true
validates :slug, Fae.validation_helpers.slug

Fae uses Judge for client side validations. Judge requires you to expose any attributes that have a uniqueness validation. You can do this in config/initializers/judge.rb:

Judge.configure do
  expose Article, :slug
end

Navigation

We should update our navigation so these three sections are easy to find. We'll update our app/models/concerns/fae/navigation_concern.rb like so:

def structure
  [
    item('News', subitems: [
      item('Articles', path: admin_articles_path),
      item('Article Categories', path: admin_article_categories_path),
    ]),
    item('Pages', subitems: [
      item('About Us', path: fae.edit_content_block_path('about_us'))
    ])
  ]
end

Learn more about setting up your navigation

Scale and Customize

Now that we are up and running with our CMS we can continue to scale it. When you run into a use case that Fae's can't handle, don't fret, Fae is built to be overridden.

Use Rails helpers in place of Fae form helpers, override views, methods and whole classes. Fae even provides concerns to inject custom logic into its base classes.

We want Fae to get you off the ground quickly but be able to scale with your project and all the customized use cases you don't know you need yet.