[[PageOutline(2-5,Contents,pullout)]]

= Dynamically change field depending on value of parent

== Description

This plugin allows you to dynamically change fields options by their parent fields.

For example, there are 3 fields: brand, phone, OS. When the phone brand changes, the phone field will change its options to show only the phone that belongs to that brand. When the phone changes, the OS field will change accordingly.
 1. Add 3 custom fields in your `trac.ini` file:
 {{{#!ini
[ticket-custom]
tcf_brand = text
tcf_brand.label = Brand
tcf_brand.order = 3
tcf_phone = text
tcf_phone.label = Phone
tcf_phone.order = 4
tcf_os = text
tcf_os.label = OS
tcf_os.order = 5
}}}
 2. Go to Admin -> Chained Fields, edit the configuration:
{{{
{
    "tcf_brand": {
        "Nokia": {
            "tcf_phone":{
                "5800": {
                    "tcf_os":{
                        "Symbian": {},
                        "Android": {}
                    }
                }
            }
        },
        "SE": {
            "tcf_phone":{
                "": {
                    "tcf_os":{
                        "": {}
                    }
                }
            }
        },
        "Apple": {
            "tcf_phone":{
                "iPhone": {
                    "tcf_os":{
                        "OS X": {},
                        "OS": {}
                    }
                },
                "iPhone 3G": {
                    "tcf_os":{
                        "OS X": {},
                        "other": {}
                    }
                }
            }
        }
    }
}
}}}

'''Notes''': 
 * If there are no options for some fields, like "SE" above, you still need to supply the full structure, with empty string as keys.
 * It supports any fields after [7793].

The list of applicable phones changes based on the selections made in the Brand and OS fields:

[[Image(TracTicketChainedFieldsPlugin.png, border=2)]]

See also [KeepInterfaceSimplePlugin#UtilityforimportingTracTicketChainedFieldsPluginconfigurations KeepInterfaceSimplePlugin], which contains similar (and additional) functionality.

== Bugs/Feature Requests

Existing bugs and feature requests for TracTicketChainedFieldsPlugin are 
[report:9?COMPONENT=TracTicketChainedFieldsPlugin here].

If you have any issues, create a 
[/newticket?component=TracTicketChainedFieldsPlugin new ticket].

[[TicketQuery(component=TracTicketChainedFieldsPlugin&group=type,format=progress)]]

== Download

Download the zipped source from [export:tracticketchainedfieldsplugin here].

== Source

You can check out TracTicketChainedFieldsPlugin from [/svn/tracticketchainedfieldsplugin here] using Subversion, or [source:tracticketchainedfieldsplugin browse the source] with Trac.

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

[pypi:Simplejson] is a requirement for Python < 2.6, and it should be installed automatically if required when running `easy_install`.

 1. Uninstall TracTicketTemplate if you have it installed before.
 1. Change to the directory containing setup.py.
 1. If you want to install this plugin globally, this will install this plugin to the Python path:
{{{#!sh
python setup.py install
}}}
 1. If you want to install this plugin to the Trac instance only:
  * python setup.py bdist_egg
  * copy the generated egg file to the trac instance's plugin directory:
{{{#!sh
cp dist/*.egg /srv/trac/env/plugins
}}}
 1. Add the follwing line to the components section of the `trac.ini` file:
{{{#!ini
[components]
tcf.* = enabled

[tcf]
hide_empty_fields = false
chained_fields = tcf_brand, tcf_phone, tcf_os
}}}
 or:
{{{#!ini
chained_fields = component, tcf_brand, tcf_phone, tcf_os
}}}
 for non-tcf_ starting fields.

`hide_empty_fields` is the option which enable "hide fields when there are no supplied options", default is false. See #5638 for more details.

== Recent Changes

[[ChangeLog(tracticketchainedfieldsplugin, 3)]]

== Author/Contributors

'''Author:''' [wiki:richard] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''