guides.ubiquo.me

Chapters

1. Settings
   • Getting a value
   • Creating a new setting
   • Setting a value
   • Inherited values
   • Use of ubiquo_config_call
   • Runtime changes to settings (dynamic settings)
2. Core helpers
   • Index helpers
   • Show helpers
   • Form helpers
3. Navigation
   • Tabs navigations
   • Link navigations
4. Filtered Search
   • Default named_scopes
   • Enabling named_scopes and customizing text search
   • Using filtered_search
5. Relation selector
   • Selector types
   • Common options allowed
   • Required code
   • General examples
   • Notes
6. Filters
   • Text filter
   • Link filter
   • Select filter
   • Links or Select filter
   • Boolean Filter
   • Date filter
   • Single Date filter
7. Cron jobs
   • Defining our crontab schedule
   • Rendering our crontab
   • Installing our crontab
   • Testing your jobs
   • Defining cron jobs in your ubiquo plugins
8. Ubiquo Loader
9. Configuring the locales of your Ubiquo project
10. Changelog

1 Settings

Settings allows developers to easily store configuration variables. These variables can be grouped in contexts.

1.1 Getting a value

To get the stored value of a configuration variable:

1.2 Creating a new setting

Before accesing a setting, it is required to register it, generally using the add method.

You can also use the extended format, which provides more goodies that we will cover later.

1.3 Setting a value

Once you have added a key, you can override its value assigning another one or with the set method:

1.4 Inherited values

You can define settings which by default will take their default value from another setting unless it is manually set.

For example, this is currently is used to set the plugins lists max rows number. All listings inherit it from a common setting, but you can be reset it for a single list.

1.5 Use of ubiquo_config_call

ubiquo_config_call lets you to define keys with a lambda as value and then evaluate them in any context.

It’s very powerful as is another way to add hooks in the application.

For example, it is currently used in all the access_control calls of the plugins, letting you to change the permissions in your application without changing plugin code.

1.6 Runtime changes to settings (dynamic settings)

Settings can be configured to allow them to be changed by end-users on runtime. To achieve this goal, there is a custom connector that keeps settings persistent on a database backend.

You need to satisfy two requirements:

• Enabled the override mechanisms:

• And provide some settings:

The :is_editable option means that this setting will be available to the users, inside the Settings section in Ubiquo.

To know more about settings please take a look to the Ubiquo Configuration guide

2 Core helpers

Ubiquo provides a series of helpers that can be useful in most ubiquo projects. On the rdoc you will find an exhaustive list, and here examples for some of the most usual plugins will be shown.

2.1 Index helpers

Currently, the index views that ubiquo_scaffold generates use filters defined in the corresponding helper file. The main helper there is the xxx_list helper (e.g. book_list in the Book scaffold). For more information about it please refer to the ubiquo_scaffold guide where you will find a more detailed explanation, including the different options and features available for this method.

2.2 Show helpers

The helpers in this group will assist you when creating ‘show’ pages in Ubiquo.

2.2.1 Lists

This will create a normal, styled ul list.

2.2.2 media_attachment helpers

Visit the ubiquo_media guide if you are interested in helpers to easily print lists of images or documents

2.2.3 HTML text

Just add the class ‘text’ to the dd tag and you are ready

2.3 Form helpers

The forms were pieces of repeated code till now. Full of HTML that could be deduced from the field type and name of the fields. We focused on it to be DRY and get a powerful abstraction applying the “the convention over configuration” concept.

We have a new helper named ubiquo_form_for which is like the form_for but uses our custom form builder UbiquoFormBuilder.

This builder does the same as usual but adds all the surrounding html that uses to be added to a input in a ubiquo form.

Using the regular builder, we would write this:

but with UbiquoFormBuilder we write this:

As you can see the form gets more “right to the point”, and the code is far less verbose.

The usual methods for the form like text_field, text_area, media_selector, etc., are enriched with a wrapper and a label with the name of the field. All of them generate the right html to be rendered correctly in the Ubiquo side.

These methods accept the following options aside the usual ones for them:

• translatable : when true shows that this field is translatable.
• description : a text that will be appended to the field to add extra information.
• help: will show a tooltip when clicking on an icon to see extra information.
• label: in case you want to show another label and not the one of the attribute
• group: options for the group. When false, no group wraps the field. It can be a hash with options to pass to the group generation, like :type => :fieldset, etc.

All this simplification/convention can be customized in two ways:

• Pass options to the methods to modify the conventioned behaviour
• Disable all extra features of the form builder and generate the code in the old way inside a block.

There are examples of both below.

2.3.1 Customize the building

All the overloaded methods that we usually use, have various options that allows you to customize them.

2.3.1.1 Example 1: removing fieldset tags or form-item wrapper

In our builder, most fields are automatically wrapped by a fieldset or a div tag b y default. This can be overriden setting the :group option to false.

2.3.1.2 Example 2: grouping various selectors in a fieldset and disable its owns fieldsets

2.3.1.3 Example 3: forwarding options to the inside generators like label or fieldsets

In this case, the options given in :group will be sent to UbiquoFormBuilder#group to customize the wrapper tag.

This will generate the same as:

2.3.1.4 Example 4: disable custom form builder methods in a block

This option allows to disable all extra UbiquoFormBuider features and all methods behave like a regular FormBuilder instance. Useful when you want to output custom form html.

2.3.1.5 Example 5: append custom html around the field

Sometimes you want to append content inside a field, before or after the field. This can be done sending the content to the group.

The span#password_strength will be rendered just after the input inside the wrapper like this:

2.3.2 Tabs

The tabs allow to wrap long forms in topics to reduce form page length.

The usage is really easy:

Don’t forget to wrap the tabs inside a tabbed from group. Otherways the builder could not guess where this tab belongs to.

3 Navigation

3.1 Tabs navigations

All ubiquo applications have two tab navitations, one for normal mode and one for superadmin mode. This tab navigator is what is showed under the ubiquo header.

3.1.1 Create new tab to the normal mode

Open RAILS_ROOT/app/views/navigators/_main_navtabs.html.erb.

Here you can edit navigator_left or navigator_right. Inside the ‘create_tab_navigator’ method block you can add new tabs with a piece of code like that:

3.2 Link navigations

Link navigations work like tab navigations but showing links instead tabs.

Currently there are only one default link navigation, but scaffold generates one for the new controller.

The default navigation is showed on top of the Ubiquo, where is showed user name, logout link, etc.

To add a link to any link navigation just add this code to the ‘create_link_navigation’ method block:

4 Filtered Search

Provides a mechanism to search and filter data in a model based on the params hash and named_scopes.

First step is to add the funcionality to the model:

This macro does several things:

• Adds some named scopes if some fields exist.
• Provides a filtered_search class method to search the model.
• Provides a paginated_filtered_search (same but suports a page parameter for pagination).

Let’s check how it is normally used in the controller:

What this does is match the “filter_blah” like params to “blah” scopes, it also takes into account order_by and sort_order params.

4.1 Default named_scopes

Some named_scopes are automatically created if some fields exist in the table. For example:

If title, name or description exist a “text” named_scope will be created. This named scope suports case and accent insensitive search.

So a param called filter_text would match against this scope and its value passed to it.

If a published_at field exist two named_scopes will be created:

4.2 Enabling named_scopes and customizing text search

Default scopes are enabled by default by just including the filtered_search_scopes macro in the model.

You can disable them:

If you need to enable some additional scopes you can do so:

Enabling scopes means that they would be elegible to be matched against filter_ like params.

Additionally you can customize which fields do you want the text named_scope to operate on:

4.3 Using filtered_search

You can search and filter results using 2 methods:

• filtered_search
• paginated_filtered_search

Usually you will pass the params hash to the paginated_filtered_search methods as seen in previous examples but you can also pass additional conditions to the search too.

Valid params for filters and options are:

• filter_ like params (to match against named scopes).
• sort_order and order_by for ordering.
• page and per_page params for pagination. (if using paginated_filter_search).

5 Relation selector

Ubiquo relation selector provides an easy way to implement form-controls on model to model relations. This feature offers a compact view to work with different relation types, like belongs_to and has_many through different controls.

Supported relations are belongs_to, has_many and has_many through with all their options

5.1 Selector types

Current selector types are:

• Select: select form, used to manage belongs_to relations, displaying all available options in a list with the instance choice as a selected one. Example: form.relation_selector :publisher, :type => :select
• Check box group: a group of checkboxes, used to manage has_many relations, displaying all available options and marking the instances choices. Example: form.relation_selector :authors, :type => :checkbox
• Text field with autocomplete functionality: a text field with autocomplete functionality, used to manage both belongs_to and has_many relations, offering a list of available options filtered for the current text entered by user. It blocks input depending on the size of the given relation. Example: form.relation_selector :authors, :type => :autocomplete

5.2 Common options allowed

Options allowed for this helper are:

• type(optional, default => autocomplete): to choose the type of selector. Options available are select, check_box and autocomplete
• autocomplete_style(optional): this option will allow to choose between text-field like autocomplete or list-field like autocomplete.
• name_field(optional, default => [title, name]): to choose which model field will be displayed to the final user. This field must be a valid model field or a valid function with a string type return.
• collection_url(optional): this option will give the needed string to be called to retrieve model instances from its controller. The string must be a valid rails url generator.
• url_params(optional): this option will contain all additional params needed for all requests made by relation selector to retrieve desired objects.
• required(optional): this option will append a * character to the given control, showing if that data field is required.
• add_callback(optional): this option allows user to register a callback function that will be triggered when adding occur.
• remove_callback(optional): this option allows user to register a callback function that will be triggered when removing occur
• related_object_id_field(optional, default => id): this field will be used as the given class objects identifier.

5.3 Required code

The code required to use this helper is the following:

• Related models for autocomplete: if use of autocomplete selector type is required, the related model will need to add a json return format to its index controller action (default url discovery option) or another arbitrary defined action with the same return requirements (collection_url option)

Actually Ubiquo provides a default javascript response in the controller actions rendering a json with the collection or object instance using only the fields id and name/title of the model. It’s possible to change the default javascript response in your controller actions using the controllers’ class method default_format_response_with in this way:

5.4 General examples

5.4.1 Autocomplete with custom name field and collection_url

5.4.2 Checkbox group with select/unselect callbacks

5.4.3 Autocomplete with filters

5.5 Notes

The required javascript to make it work is included by default at new projects to the main ubiquo layout. However, if you’re adding this new feature to an older project, you must include that javascript.

Then, file app/views/layouts/ubiquo/default.html.erb will have a javascript_include_tag as follows

• javascript_include_tag ‘ubiquo/relation_selector.js’

With the bolded part being the needed new inclusion

6 Filters

Ubiquo filters are sidebar elements used to filter ubiquo listings.

The Ubiquo::Filters module provides some commonly used filters. Each filter has two main components:

• The sidebar filter itself, containing the HTML that displays the filter on the lateral panel. It contains a header and a link to disable the filter when it is active.

• The displayed information about the applied filters that appears on top of the index listing. It informs about all the active filters and contains a link to disable them all.

Filters are automatically added to the index view, you only have to fill the helper (example for controller articles_controller):

6.1 Text filter

It consists of an input text tag with a search button. Default options are shown.

6.2 Link filter

Given an attribute to filter, generate a link for each possible value. There are two common cases:

• You have a separated model (one-to-many relationship). On this case, you have to pass the collection of values and the associated model tablename (plural, underscore form).

• Default values are:

• So you could use something like:

• The possible values for an attribute but directly a list of them on the model. Let’s see an example:

6.3 Select filter

Generate a select tag given an array of items.

• It works exactly on the same way than the links filter, only that an extra option options[:all_caption] is needed to add a “all” option that disables the filter:

6.4 Links or Select filter

This filter renders a select filter if the collection items length is greater than the :max_size_for_links parameter it uses a link filter otherwise. Pass the same options needed by a select filter. An example of the filter info code:

6.5 Boolean Filter

For boolean attributes use a link or select filter, but instead of collection/id_field/name_field options, pass boolean/caption_true/caption_false.

• Default values are:

6.6 Date filter

Date filters employ the plugin calendar_date_select . If you need to change the stylesheets, edit public/stylesheets/calendar_date_select/ubiquo.css. To use the lateral filter on your listing, you have to indicate the caption and the start/end date field names:

• Default values are:

6.7 Single Date filter

Used to filter with only one date. It’s like last filter but with just one date field:

• Default values are:

7 Cron jobs

Ubiquo provides a mechanism for defining, scheduling and running cron jobs. It requires a cron daemon and it has been tested with vixie cron.

The ubiquo cron job system provides several advantages:

• Ability to put jobs under version control. (minimizes sysadmin burden).
• Ability to deal with concurrency, it avoids running multiple instances of the same job at the same time.
• Ability to log job execution details.
• Alert on job errors.
• Provides a standard mechanism for running rake or script/runner like tasks.

7.1 Defining our crontab schedule

We can use the ubiquo_crontab initializer that you should be able to find at config/initializers/ubiquo_crontab.rb:

As we can see it is easy to schedule new jobs using the already known cron syntax but with the added advantage of specifying rake or runner tasks in a convenient way without having to deal with all the low level details.

7.2 Rendering our crontab

With our crontab defined we can run the ubiquo:crontab:render task to see how the real crontab file would look like.

As we can see our jobs are run by a rake task that deals with the low level details like:

• logging
• error alerts
• concurrency

7.3 Installing our crontab

We can install our defined crontab, but keep in mind that doing so removes all existing jobs in crontab and replaces them with the current definition:

Usually this task would be executed by a capistrano’s hook when deploying the application:

A similar recipe should be included in your capistrano file.

7.4 Testing your jobs

You can test your jobs using the ubiquo:cron:runner task:

You can now look at the cron log in the application’s log folder and see the output.

7.5 Defining cron jobs in your ubiquo plugins

You can use this system to define jobs for your ubiquo plugins, for example:

This would translate to:

8 Ubiquo Loader

When you are extending external classes usually an order problem appears. For example, if you are developing a lib that extends a class from another plugin, you have to make sure that the plugin is already loaded in order to work properly.

While this is sometimes feasible using explicit requires, you might prefer, or even require, some plugin parts to be lazy loaded. In some other circumstances, you don’t have control in the loading order, and you can’t guarantee that the class you need is already loaded. For example, this is usually the case when you extend a plugin from another plugin.

Another common problem is that you cannot load extensions from a lib file into an application (controller, model) class, since in development, with cache_classes disabled, the extension would be lost in the second request, when the classes are reloaded. While there are hacks to fix this (e.g. using before_dispatch to reload the extensions), it’s an annoying and unnecessary recurrent problem.

To fix all these loading issues, which you probably have already experienced, since you are reading this, Ubiquo has an Extension Loader that allows you to overcome all this.

The idea of the Loader is the following: you simply “define”:

• The class to extend,
• The module that encapsulates the extension
• The extension action

And the extension will be applied either at this same moment (if the class to extend is already loaded), or else, in the future, when the class is really loaded.

So, what it used to be, for example

now becomes

As you can see, you only pass the name of the class (:Asset), since if you use Asset you’d trigger the class loading.

The other difference is that instead of extend, you use append_extend, to schedule the extension inclusion.

Of course if that is too verbose for you, and provided you don’t have name conflicts, you can alias Ubiquo::Extensions::Loader to a shorter name:

The methods currently available in Loader are the following:

• append_extend
• append_include
• append_helper

The first two simply schedule the launch of extend and include. The last one is handy to add helpers to controllers.

Note that there still remains a limitation when extending classes, and is to use ActiveRecord’s relations from plugin models to application models. For example, if in a plugin you have a User class, and you want to add a has_many :books, with Book defined into your application app/models folder, you will run into trouble.

With the development standard configuration, application models are reloaded but plugins are not. The internals in Rails 2.X will break these associations because of this, causing the “second request” symptom, when things work in the first request but not in the successive ones.

The solutions for this are, either make the plugins also unloadable (which may create other bugs, since some of the plugins could not support it), or activate cache_classes in development. If you have a closed circuit of associations between classes, you might consider also moving them to a new plugin, so that you can maintain cache_classes disabled for the rest of classes.

9 Configuring the locales of your Ubiquo project

By default, all Ubiquo projects will use three different locales: English (en), Catalan (ca) and Spanish (es). When you create your Ubiquo project you can select the default language (english if not specified). However, you may want to use other locales, just one, or even change the default locale after the project creation.

To set up a specific locale as the default one, you have to modify the config/environment.rb file. In there you’ll have to add or change a line to this one:

Changing en for the desired locale

Also, to set the available locales for your application, you’ll have to add a line like this one in the same file:

Using the array of the locales you want to be able to use in your application.

10 Changelog

Lighthouse tickets