So how do we do that? In most cases, you wouldn't need a custom searcher. Instead you can use the built in custom field searchers in JIRA itself. The list includes, but not restricted to, Text Field Searcher, Date Searcher, Number Searcher, User Searcher etc.
The first step of course is to determine what is the kind of Searcher your new field needs. For example, a Select field can easily be searched with Text Searcher or an Exact Text Searcher! A User Picker field can be searched with a User Searcher or a Text Searcher. You might even want to extend one of these Searchers to add some extra functionality. Some special conditions or hacks you want to introduce! Yeah, you know what I mean!!
Now, we have the custom field ready and the Searcher decided. Let us , in this example, consider using a TextSearcher puerly because the customfield we created in the other tutorial is extending a TextCFType.
Here is how JIRA has defined the text searcher for its system custom fields:
i18n-name-key="admin.customfield.searcher.textsearcher.name"
class="com.atlassian.jira.issue.customfields.searchers.TextSearcher">
<description key="admin.customfield.searcher.textsearcher.desc">Search for values using a free text search.</description>
<resource type="velocity" name="search" location="templates/plugins/fields/edit-searcher/search-basictext.vm"/>
<resource type="velocity" name="view" location="templates/plugins/fields/view-searcher/view-searcher-basictext.vm"/>
<valid-customfield-type package="com.atlassian.jira.plugin.system.customfieldtypes" key="textfield"/>
<valid-customfield-type package="com.atlassian.jira.plugin.system.customfieldtypes" key="textarea"/>
<valid-customfield-type package="com.atlassian.jira.plugin.system.customfieldtypes" key="readonlyfield"/>
</customfield-searcher>
class="com.atlassian.jira.issue.customfields.searchers.TextSearcher">
<description key="admin.customfield.searcher.textsearcher.desc">Search for Read Only User using a free text search.</description>
<resource type="velocity" name="search" location="templates/plugins/fields/edit-searcher/search-basictext.vm"/>
<resource type="velocity" name="view" location="templates/plugins/fields/view-searcher/view-searcher-basictext.vm"/>
<valid-customfield-type package="com.jtricks" key="readonly-user"/>
</customfield-searcher>
And then comes the most important part where you mention your customfield within the valid-customfield-type tag. There can be multiple entries for different custom fields as you saw in the first snippet from Atlassian. In our case we have the read-only user custom field added.
There is basic but very common error you might make here. The package attribute here refers to the atlassian-plugin key where the custom field resides in and not the Java package where the Searcher class resides in! Just to make it clear, the Atlassian plugin key is the key in the first line of your atlassian-plugin.xml which is 'com.jtricks' in our case.
Now all these works fine pre 4.x or pre OSGI! With the introduction of v2 plugins, courtesy OSGI bundles, referring the JIRA classes directly in the atlassian-plugin.xml will fail sometimes because it can't resolve all the dependencies (the notorious Unsatisfied dependency errors!). This is because some of the classes are not available for dependency injection in the version 2 plugins as they were in version 1 plugins.
But don't worry, there is an easy hack to do it. Just create a dummy custom Searcher class with the constructor that does the dependency injection for you. So you will endup doing something what Leonids suggest in the forums:
public MySearcher(PluginComponent ioc) {
super(ioc, ComponentManager.getInstanceOfType(anotherType));
}
}
If nothing works, you always have the option of adding the field to the system-customfield-types.xml under WEB-INF/classes along with the JIRA system custom fields. i.e. one more valid-customfield-type entry into the relevant customfield-searcher element.
Phew! So we have the searcher defined and the stage is set to create your first filter with the new custom field. Happy coding.