Chapters1 Settings schema
Currently we can differentiate two kinds of configuration values or settings:
- Static settings
Defined in development time; cannot be changed on runtime. Usually these are values that configure how ubiquo works or basic values required by the application to work.
- Dynamic settings
Defined in development and also swappable on runtime. As an end-user can change these values, usually they are not so tied to how the code works and are simply used as parameters. E.g. API keys, email addresses… If possible, they should be used with safe default values, as they are optionally user-provided.
1.1 Sample configuration
The following code contains examples of the different settings you can define and use. A snippet like this would usually be placed in an initializer.
Settings.create_context(:application) do |settings|
# not editable in runtime, not displayed in web backend
settings.string :default_post_title, "My title"
# this value can be changed on runtime
settings.string :default_comment_title, "My customizable title", :is_editable => true
# these values can also be changed on runtime
# the with_options syntax allows to define common options for more than one setting
settings.with_options :is_editable => true do |editable_settings|
editable_settings.integer :default_award_amount, 30
editable_settings.boolean :allow_awards, false
editable_settings.email :admin_email, "alerts@ubiquo.me"
editable_settings.password :google_sites_secret, "BGDFG$$DAA"
editable_settings.string :registry_email,
"<p>My Complex text</p>",
{ :is_text => true }
# multilanguage setting
# pending translation for english
editable_settings.email :alert_email,
{
:es => 'alertas@ubiquo.me',
:ca => 'alertes@ubiquo.me'
},
{ :is_translatable => true }
# value restricted setting
editable_settings.string :z_default_license,
"apache",
{ :allowed_values => %w{apache gpl bsd mit} }
# multivalued and restricted setting
editable_settings.list :browsers,
%w{chrome chromium firefox opera},
{ :allowed_values => %w{chrome chromium opera firefox internet-explorer} }
# group of translatable settings of type string that can also be
# changed on runtime
my_options = {:is_translatable => true, :value_type => UbiquoStringSetting}
editable_settings.with_options(my_options) do |translatable_settings|
translatable_settings.add(:another_email,
{
:es => 'otro@ubiquo.me',
:ca => 'altre@ubiquo.me'
})
translatable_settings.add(:another_string_setting, { :es => 'es_string' })
end
end
end
1.2 Customizing web interface
By default, the :is_editable settings will be displayed inside the Settings section in Ubiquo. They have a default rendering which you can customize.
You have two methods to override the partial used to render a setting control.
During each template rendering you will have available the specific UbiquoSetting instance as a local value named ubiquo_setting
- For a specific setting
"#{Rails.root}/app/views/ubiquo/ubiquo_settings/#{context_name}/#{setting_key}.html.erb"
- For a specific setting type
"#{Rails.root}/app/views/ubiquo/ubiquo_settings/#{setting_type}.html.erb"
"#{Rails.root}/app/views/ubiquo/ubiquo_settings/_string.html.erb"
You can override every of the templates available at vendor/plugins/ubiquo_core/app/ubiquo/ubiquo_settings/
If no valid partial can be found for a setting, an error will be raised on runtime
2 For end-users
If :settings_override has been enabled in development, end users will have available a web interface to edit each setting.
2.1 Permission
A permission key settings_management exists to restrict the access to this functionality to some users. You can customize this permission management as usually in ubiquo plugin with an access_controller setting:
Setting[:ubiquo_settings_access_control] = lambda{ true } # allow everybody
2.2 Web interface
Users will have available an interface similar to other ubiquo scaffolds, where they will be able to set a value for every :is_editable setting
In this interface you are able to:
- Update a specific setting
- Update all avaiable settings
- Restore a setting to the default value established by developers
- Translate a value to the current locale
2.3 Class Diagram
In this diagram we can see the Settings internal structure, with the class set that allow changes on runtime
2.4 More Information
This refactoring was done according to the discussion that was taken here:
3 Settings list
This section will guide you through the most important parameters you can change.
In your app, the convention is to change the configuration options in the config/initializers/ubiquo_config.rb file.
3.1 Ubiquo Core
Most main Ubiquo configuration parameters have no context.
| Parameter | Purpose | Default value |
|---|---|---|
| app_name | The application name | name used upon project creation |
| app_title | The application title. It will be displayed on the ubiquo section | name used upon project creation |
| app_description | The application description | name used upon project creation |
| notifier_email_from | Email address used for notifications | railsmail@gnuine.com |
| elements_per_page | Elements per page to show on Ubiquo lists | 10 |
| max_size_for_links_filter | Maximum number of links to show before changing a filter to a select | 5 |
| model_groups | Model groups for fixture import and export | {} |
| attachments | Default options for attachments | {:visibility => 'public', :public_path => 'public', :use_x_send_file => !Rails.env.development?} |
| required_field_class | CSS class to use when showing a required field | 'required_field' |
| error_field_class | CSS class to use when showing an error in a form | 'error_field' |
| ubiquo_path | Default path for ubiquo section | 'ubiquo' |
| edit_on_row_click | Select the behaviour of ubiquo list actions (old or new) | true |
3.1.1 ubiquo_form_builder options
There’s a special context for options regarding the Ubiquo Form Builder. It’s called :ubiquo_form_builder and has this options:
| Parameter | Purpose | Default value |
|---|---|---|
| default_tag_options | Allows you to set default options for different inputs when using the ubiquo form builder | Check the source file and Ubiquo Core Configuration for more information |
| groups_configuration | Allows you to set default options when grouping inputs when using the ubiquo form builder | Check the source file and Ubiquo Core Configuration for more information |
| default_group_type | Sets the default html tag to use for grouping inputs when using ubiquo form builder | :div |
| unfold_tabs | Allows you to set the ubiquo form builder tabs to be folded or unfolded when using the ubiquo form builder | false |
3.2 Ubiquo Access Control
Ubiquo Access Control settings are stored under the :ubiquo_access_control context.
| Parameter | Purpose | Default value |
|---|---|---|
| role_access_control | Sets up the default access control for the roles controller | Allows default access to role_management role |
| role_permit | Sets up the default permission to access role management | Sets the permission to role_permit |
| roles_elements_per_page | number of elements per page on the role list | Inherited from elements_per_page |
| roles_default_order_field | default order field for the role list | id |
| roles_default_sort_order | default sort order for the role list | 'desc' |
3.3 Ubiquo Activity
Ubiquo Activity settings are stored under the :ubiquo_activity context.
| Parameter | Purpose | Default value |
|---|---|---|
| activities_elements_per_page | Elements per page in the activities list | Inherited from elements_per_page |
| activity_info_access_control | Sets up the default access_control for the activity controller | Allows default access to activity_info_management role |
| activity_info_permit | Sets up the default permission to access activity management | Sets the permission to activity_info_management |
| activities_date_filter_enabled | Enables or disables the date filter on activity listings | true |
| activities_user_filter_enabled | Enables or disables the user filter on activity listings | true |
| activities_controller_filter_enabled | Enables or disables the controller filter on activity listings | true |
| activities_action_filter_enabled | Enables or disables the action filter on activity listings | true |
| activities_status_filter_enabled | Enables or disables the status filter on activity listings | true |
| activities_default_order_field | Default field to order the activity listings | 'activity_infos.created_at' |
| activities_default_sort_order | Default sort order for the activity listings | 'desc' |
| info_list_partial | Partial view to use for the activity list rendering | 'standard' |
3.4 Ubiquo Authentication
Ubiquo Authentication settings are stored under the :ubiquo_authentication context.
| Parameter | Purpose | Default value |
|---|---|---|
| remember_time | Time the system will remember the logged user if checked | 2.weeks |
| user_access_control | Sets up the default access_control for the user controller | Allows default access to ubiquo_user_management role |
| user_navigator_permission | Sets up the default permission to access user management | Sets the permission to ubiquo_user_management |
| ubiquo_users_elements_per_page | Elements per page in the ubiquo user list | Inherited from elements_per_page |
| ubiquo_users_admin_filter_enabled | Enables or disables the admin filter on user listings | true |
| ubiquo_users_string_filter_enabled | Enables or disables the string filter on user listings | true |
| ubiquo_users_default_order_field | Default field to order the user listings | 'ubiquo_users.id' |
| ubiquo_users_default_sort_order | Default sort order for the user listings | 'desc' |
3.5 Ubiquo Categories
Ubiquo Categories settings are stored under the :ubiquo_categories context.
| Parameter | Purpose | Default value |
|---|---|---|
| category_sets_per_page | Elements per page in the category sets lists | Inherited from elements_per_page |
| categories_per_page | Elements per page in the categories lists | Inherited from elements_per_page |
| categories_access_control | Sets up the default access control for the categories controller | Allows default access to categories_management role |
| categories_permit | Sets up the default permission to access categories management | Sets the permission to categories_management |
| administrable_category_sets | Allows the administration of Category Sets | true |
| max_categories_simple_selector | Maximum number of categories to list in a select before switching to an autocomplete | 6 |
| available_connectors | List of connectors to use in the plugin | [:i18n, :standard] |
| connector | Default connector | :standard |
3.6 Ubiquo Design
Ubiquo Design settings are stored under the :ubiquo_design context.
| Parameter | Purpose | Default value |
|---|---|---|
| pages_elements_per_page | Elements per page in the page lists | Inherited from elements_per_page |
| design_access_control | Sets up the default access control for the design controller | Allows default access to design_management role |
| design_permit | Sets up the default permission to access design management | Sets the permission to design_management |
| static_pages_permit | Sets up the default permission to access static pages management | Sets the permission to static_pages_management |
| page_string_filter_enabled | Enables or disables the string filter on page listings | true |
| page_default_order_field | Default field to order the page listings | 'pages.url_name' |
| page_default_sort_order | Default sort order for the page listings | 'asc' |
| widget_tabs_mode | Configures how the widget list is grouped in the design view. Values can be :auto, :groups or :blocks | :auto |
| page_default_sort_order | Default sort order for the page listings | 'asc' |
| allow_page_preview | Allow previewing of pages at design time | true |
| connector | Connector to use on the plugin | :standard |
| cache_manager_class | The default manager for caching pages | Depending on the environment will use RubyHash or Memcache. Check Ubiquo Design Guide for more information |
| memcache | Hash to configure Memcache framework | {:server => '127.0.0.1', :timeout => 0} |
| generic_models | Models to select for generic widgets | [] |
| block_type_for_static_section_widget | The block type for the static widgets | Not set |
3.7 Ubiquo I18n
Ubiquo I18n settings are stored under the :ubiquo_i18n context.
| Parameter | Purpose | Default value |
|---|---|---|
| locales_default_order_field | Default field to order the locales lists | 'native_name' |
| locales_default_sort_order | Default sort order for the locales lists | 'asc' |
| locales_access_control | Set up the default access control for locales | nil |
| last_user_locale | Used to get the last user locale | Will get the locale of the current user, nil if there is none |
| set_last_user_locale | Used to set the last user locale | Will update the current user locale to the given :locale as an option |
3.8 Ubiquo Jobs
Ubiquo Jobs settings are stored under the :ubiquo_jobs context.
| Parameter | Purpose | Default value |
|---|---|---|
| job_manager_class | Default manager to handle jobs | UbiquoJobs::Managers::ActiveManager |
| job_notifier_class | Default manager to handle job notifications | UbiquoJobs::Helpers::Notifier |
3.9 Ubiquo Media
Ubiquo Media settings are stored under the :ubiquo_media context.
| Parameter | Purpose | Default value |
|---|---|---|
| assets_elements_per_page | Elements per page in the asset lists | Inherited from elements_per_page |
| media_selector_list_size | Maximum number of assets to list in a select before switching to an autocomplete | 6 |
| assets_access_control | Sets up the default access control for the assets controller | Allows default access to media_management role |
| assets_permit | Sets up the default permission to access assets management | Sets the permission to media_management |
| assets_string_filter_enabled | Enables or disables the string filter on asset listings | true |
| assets_tags_filter_enabled | Enables or disables the tags filter on asset listings | true |
| assets_types_filter_enabled | Enables or disables the types filter on asset listings | true |
| assets_visibility_filter_enabled | Enables or disables the visibility filter on asset listings | true |
| assets_date_filter_enabled | Enables or disables the date filter on asset listings | true |
| assets_default_order_field | Default field to order the assets lists | 'assets.id' |
| assets_default_sort_order | Default sort order for the assets lists | 'asc' |
| mime_types | Supported mime types as attachments | Check the source file to see the default supported mime types |
| media_styles_list | Supported styles for images | { :thumb => "100x100>", :base_to_crop => "590x442>" } |
| media_styles_options | Default options for assets. Can be a Hash or a proc receiving the style and name of the asset | Empty hash |
| media_processors_list | List of processors to apply after an asset is uploaded | [:resize_and_crop] |
| media_core_styles | The styles that belong to ubiquo and are part of the core | [:thumb, :base_to_crop] |
| assets_default_keep_backup | Keep a backup of the original backup when cropping and resizing | true |
| advanced_edit_warn_user_when_changing_asset_in_use | Warn the user when updating an asset that is related to an instance | false |
| advanced_edit_allow_restore_from_media_selector | When editing advanced from a media selector, allow to restore to uploaded asset | true |
| force_visibility | Force this asset visibility for the entire application | "public" |
| available_connectors | Connectors available for this plugin | [:standard] |
| connector | Connectorto use in this plugin | :standard |
| media_storage | Media to use to store the attachments | :filesystem |
| progress_bar | Show a progress bar when uploading an asset | false |
| ubiquo_form_builder_media_selector_tag_options | Tag options for the ubiquo form builder | Check the source file to see the default options |