Have you noticed that the previous two chapters were about what can be called customization? That's natural because after we have learned an application, we would want to make it better fit our needs. Thus, personalization is the customization made by users for themselves using only the permissions they have. Installing plugins is the customization done by server administrators (don't confuse this with the Redmine administrator). But there was also another customization described – the configuration of Redmine, which was reviewed in Chapter 3, Configuring Redmine. While these were actually three chapters, all of them miss another customization level. All these chapters describe quite common things, which get done by everyone, who installs Redmine. These things are enough for corporate installations. But there are also advanced things, which become necessary, for example, if we want to use Redmine for a public forge site.
In such cases we usually want to have our own look and feel (theme), to add custom content to different pages, and so on. During this customization phase users usually ask experts for help. Thus, sometimes they want to develop plugins to implement different ideas but plugins, actually, are not always needed. Also, during this phase users often customize Redmine by themselves and, usually, do this incorrectly. So, what the right way is to customize Redmine, what we can do without developing custom plugins, and so on, are the topics we will speak about now.
In this chapter we will cover the following topics:
- Custom fields
- Customizing with Textile
- Customizing theme
- Customizing with plugins
I believe custom fields support is essential for any issue tracker or similar application. And, luckily, Redmine implements this feature very well. Thus, custom fields can be defined for issues, projects, versions, users, and so on (as well as for some objects provided by third-party plugins). Custom fields enrich these objects by allowing you to add properties, which are missing. They can also be used in filters, forms, and so on. To a great extent, custom fields let you change the way Redmine looks and behaves. This makes them a tool for advanced customization. This and the fact that they are supported for many object types make them appear in this chapter.
In fact, custom fields are the least unusual technique we will review in this chapter. Yet users rarely make use of them. My guess is that they feel they will be too complicated, but, actually, they are not. So let's go.
Custom fields can be managed using the Custom fields section in the Administration menu, as shown in the following screenshot:
This section contains tabs, which correspond to different customized objects. Under each tab we can see the list of custom fields (by default they are all empty). We will review each tab (that is, customized Redmine core object) later. Now let's see what happens if we click on the New custom field link:
This form is for issue custom fields (as we invoked it under the Issues tab). The form for other objects (which can be invoked under other tabs) differs, but most elements remain the same.
Thus, the first top block defines properties of the custom field and does not differ for different customized objects, but does differ for different custom field formats (this will be reviewed next). The following is an explanation about the properties of the custom field, which are shown in the preceding screenshot:
- Name is the only required property, which should contain the easy-to-understand and intelligible name of the custom field. This name will be shown in object forms and on object properties pages.
- Format field allows you to select the format of the custom field. As custom field formats introduce changes to the properties form, we will separately review them next.
- Min – Max length fields specify the minimal and maximal size of the custom field value.
- The value of the Regular expression field will be used to verify the custom field value. This is a very useful property as it allows you to ensure, that users will specify proper values for the custom field. Unfortunately, you need to be familiar with regular expressions to be able to use this property. Still I highly recommend you learn them.
- The Default value field can be used to specify the default value for the custom field.
Tip
Changing the way custom field values are displayed
The Extended Fields plugin can be used to define template files for certain custom fields (by format or by name). This way you can render boolean values as check marks, Twitter usernames as "Follow me" buttons, and so on. See http://projects.andriylesyuk.com/projects/extended-fields/wiki/Custom-fields-view-customization.
The second block contains custom field options. The Trackers option is exceptional and is only available for issue custom fields (this option allows you to select issue trackers, for which the custom field will be available). Other options get represented as checkboxes (not all available options are shown in the preceding screenshot).
The following table presents the availability of custom field options for customized objects:
|
Customized object |
Required |
Visible |
Editable |
For all projects |
Searchable |
Used as a filter |
|---|---|---|---|---|---|---|
|
Issues |
|
|
|
| ||
|
Spent time |
| |||||
|
Projects |
|
|
|
| ||
|
Versions |
|
| ||||
|
Users |
|
|
|
| ||
|
Groups |
|
| ||||
|
Activities (time tracking) |
| |||||
|
Issue priorities |
| |||||
|
Document categories |
The Required checkbox is available for all customized objects. It specifies whether the value for the custom field should be required.
The Visible checkbox controls whether the value of the custom field should be displayed on the object properties page (for example, the project overview page or the user profile page). That is, if this checkbox is not checked, the value of the custom field will be visible only in the edit mode (for example, in project settings or in the user account).
The Editable checkbox determines whether users can see and edit the value of the custom field. This checkbox is currently available only for the user object. Thus, custom fields of users with this checkbox unchecked are available only for administrators (under Administration | Users, and not in user accounts).
The For all projects checkbox specifies whether the custom field should be available for all projects. This checkbox can be currently used only by issues. If this checkbox is unchecked for the custom field, project managers will still be able to enable the custom field for the particular project in project settings (Custom fields block in Information | Custom fields).
The Searchable checkbox tells if the value of the custom field should be checked to contain the search string, when users search for the customized object. This checkbox is available only for projects and issues as only these objects (out of all supported customized objects) are available in the Redmine search form.
The Redmine search form becomes available when we type the search string into the textbox in the upper-right corner and press Enter, or when we click on the Search label, as shown in the following screenshot:
The Redmine search form looks like the following screenshot:
In other words, when we search for something in issues (that is, the Issues checkbox is checked in the search form), Redmine also searches in values of custom fields, for which the Searchable checkbox was checked.
The Used as a filter checkbox allows the custom field to be used in custom queries. That's natural for issue custom fields but the checkbox is also available for projects, versions, users, and groups. Have a look at the following screenshot:
All filters under Private are custom fields and only (meaning that others are for other customized objects) the Resolution field is for issues. So as you see, project, user, version, and group custom fields are shown here with the appropriate prefix (Project's, Author's, Assignee's, and Target version's).
This way custom fields with the Used as a filter checkbox checked can be used in custom queries.
Sometimes we need the custom field to store just a string, other times we want it to store a date or a Boolean value. Therefore, custom fields support the Format property, which can also be named the data type.
The Long text format is very much like the Text format except that it gets rendered as a text area when edited and not as a textbox like the latter. Despite possible expectation, this format does not support the wiki formatting.
Custom fields of the Integer format accept only integer values. However, minimal and maximal size, and regular expression can still be applied to custom fields of this format (for example, to allow only positive values).
Custom fields of the Float format accept float values. Such custom fields can have minimal and maximal size, and regular expression as well.
In many cases custom fields are needed to ask users just to select a pre-defined value. For example, the project licence—from the list of available licences, the resolution type—from the list of resolution types, and so on. In all such cases it is more user friendly to render a drop-down list with values to select from. This is what can be done with the List format.
Due to the specificity of this format the block for entering custom field properties looks different (it gets changed, when you select the List format):
We see the following two new properties in the preceding screenshot:
- Multiple values, which specifies whether users will be able to select several values at a time.
- Possible values, where we specify strings, from which users will need to select the value for the custom field. Each possible value should be on its own line.
The Date format can be used to get a date value using a custom field. The input element for this format is rendered along with the calendar icon, as shown in the following screenshot:
Clicking on the calendar icon invokes the calendar pop-up menu, assisting in choosing the date.
The custom field properties block for the Date format also differs:
The Boolean format can be used if the custom field needs to accept just "Yes" or "No". As Boolean values are very simple, the properties block for custom fields of this format look like the following screenshot:
Unlike all other formats for the Boolean format the Default value propety is rendered as a checkbox.
The input element for custom fields of the User format is rendered as a drop-down menu containing the list of project members. In other words, this format can be used to allow choosing a project member as a value for the custom field (can be used for, for example, second assignee, associated tester, or code reviewer).
The custom field properties block for this format includes the Multiple values checkbox, as shown in the following screenshot:
If this checkbox is checked, the custom field will allow choosing several users at a time.
Not all Redmine objects can have custom fields. Those which can, are available as tabs in the Custom fields section under Administration. In fact, every "customized" object introduces its own way of using custom fields. So, that's what we will speak about under this topic.
Redmine is primarily an issue tracker, therefore, it's no wonder that custom fields support for issues is the most advanced. Thus, issue custom fields have the additional Trackers option (see the screenshot at the beginning of this chapter); they can be enabled for all projects (using the For all projects checkbox) or for certain projects only (in project settings); their states (Read-only or Required) can be managed per issue status in the Workflow section under Administration along with core issue fields; they can be used in custom queries and more.
Issue custom fields can be specified or modified in the issue form, their values are shown on the issue page.
Tip
Instead of requiring users to enter the issue custom field (using the Required checkbox), you can define conditions, on which the custom field will become required, on the Fields permissions tab in the Workflow section under Administration. Thus, to create the Resolution custom field we can make the custom field read-only for all issue statuses except Closed.
Custom fields can be added to time entries as well. Values of such custom fields can be specified or edited in the time entry form. Unfortunately, this form is also the only place, where we can see these values.
Project custom fields are usually used to collect more details about the project. Values for these custom fields can be specified under the Information tab in project settings. If the Visible checkbox for the custom field is checked, the value of the field will be displayed on the project overview page under the description (and under the hom page, if the last has been specified).
A project can have any number of versions; project versions can also have custom fields. Values for version custom field can be specified in the version form, which becomes available when we click on the New version link or the Edit link under the Versions tab in project settings. Values of version custom fields can be viewed on the roadmap and on the version page, as follows:
Here Release is a version custom field and New features is its value.
In my opinion the default Redmine user profile is too scant, as it provides no fields to share any data with other Redmine users. Thus, this data could be Facebook, Twitter accounts, phone number, phone extension, company, position, and much more. Luckily the user object can be customized with custom fields.
Values of user custom fields can be edited in user accounts (Administration | Users) by administrators or in user profiles (the My account link) by users, but only if the Editable checkbox for these custom fields is checked. If the Visible checkbox for the user custom field is checked, it also gets shown on the user page, as follows:
User groups can also have custom fields, for which values can be specified in the group edit form (which can be accessed by clicking on Administration | Groups). Unfortunately, group custom fields are not shown anywhere else (however, issues can be filtered using them – see the Used as a filter option that we discussed previously).
Time tracking activities are, actually, "enumerations". Enumerations are Redmine objects, which allow storing list-style values. Activities such as other enumerations, also support custom fields. These custom fields can be edited or viewed in the enumeration edit form, which can be invoked in Administration | Enumerations, and under the Activities (time tracking) tab in the project settings, where per-project values for these custom fields can be specified.