Components configuration

To display your components in the admin panel, you must define them in the config/components.rb file generated when you ran the install generator.

An example configuration is given in the components.rb file.

Enabling a component in the admin navigation

First, you need to create your component, see (Creating components)[https://github.com/para-cms/para/wiki/Creating-components] for more informations.

Say you created a CRUD component for managing a Page resource.
You'll want it to be in some "Main menu" section, and call it "Pages".
You need to define the following in the config/components.rb file :

section :main_menu do
  component :pages, :crud, model_type: 'Page'
end

This will first look for a section instance with a "main_menu" identifier. If it can't find it, it will create it.
Then, it will look for a component instance of type with an identifier of "pages".
If it exists, it will update it with the given options.
If it does not exist, it will create it and add it to the parent section.

Display ordering

Sections and components have a :position field in their table, and is filled with their index as the parser finds them.

In the previous example, both component and section would have the position: 0 set.

When you have multiple components, each time the parser is re-run (at the start of the application), their position are updated. Meanining that changing their order in the config/components/rb file and restarting the application will update their position.

section :main_menu do
  component :configuration, :singleton_resource, model_type: 'Configuration'
  component :pages, :crud, model_type: 'Page'
end

Would display in the menu :

• Main menu
  • Configuration
  • Pages

Translating section and component names

By default, the displayed name for the sections and components are their :identifier with #humanize called on them. This can be enough as a defaut, but you may want to clean the names, especially when translating your app.

This can be done by translating the following keys :

• Section names : components.section.<identifier>
• Component names : components.component.<identifier>

Which, for the previous example would look like the following in a config/locales/fr.yml

fr:
  components:
    section:
      main_menu: "Menu principal"
    component:
      configuration: "Configuration de l'application"
      pages: "Pages de contenu"

Note: The :name field takes precendence over the translation system. This means that if at any time, the :name field of a section or a component is set and saved, then the translations won't work anymore and the saved :name will be used.

Deleting old components

If you delete a component from the config/components.rb file, the component won't be removed from the database. This is meant to avoid errors where you may alter your database by introducing an unwanted change to your config file.

If you need to completly remove a component from the database, you can use the dedicated rake task :

rake para:components:clean