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

= Administer Custom Fields in Trac
{{{#!box info
**Notice:** Equivalent functionality is proposed for Trac in [trac:#11469].
}}}

== Description

This plugin is a Web Admin panel for administering custom fields - adding, modifying and deleting them without editing the `trac.ini` file directly.

The plugin is available for Trac 0.10 and 0.11/0.12/1.0 (0.11 branch is compatible with current 0.12+).

This plugin is a cooperation between !CodeResort.com and Optaros.com, and is made freely available under a BSD license.

== Bugs/Feature Requests

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

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

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

== Download

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

== Source

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

== Installation

The plugin can also be installed directly from the code repository:
{{{#!sh
pip install svn+https://trac-hacks.org/svn/customfieldadminplugin/0.11
}}}

Substitute `0.11` with `0.10` for older Trac version.

== Configuration

This plugin requires Web Admin plugin ([trac:wiki:WebAdmin]) if you are using the 0.10 version. For more recent versions the Web Admin panel is integrated into Trac core.

Enable the plugin in your `trac.ini` file:
{{{#!ini
[components]
customfieldadmin.* = enabled
}}}

== API

The plugin also has an API that can be called from other code if you need to create or modify custom fields. Here is an interactive session as example:

{{{#!python
from trac.env import Environment
from customfieldadmin.api import CustomFields

myenv = Environment('/path/to/env')
mycfcomp = CustomFields(myenv)

# Get Cusom fields (list of dicts)
myfields = mycfcomp.get_custom_fields()
for item in myfields: print item

# Create a custom field - text box
mycfdict = {                # a template dictionary
    'name': 'test01',       # name of field (alphanumeric only)
    'type': 'text',         # text|checkbox|select|radio|textarea
    'label': 'Test 01',     # description
    'value': 'first test',  # default value for field content
    'options': None,        # options for select and radio types (list, leave first empty for optional)
    'cols': None,           # number of columns for text area
    'rows': None,           # number of rows for text area
    'order': 0 }            # specify sort order for field, 0 for last
mycfcomp.update_custom_field(mycfdict, create=True)

# Updating
mycfdict['type'] = 'select'
mycfdict['options'] = ['', 'one', 'two', 'three']
mycfdict['value'] = None
mycfcomp.update_custom_field(mycfdict)

# And deleting an existing custom field
mycfcomp.delete_custom_field(mycfdict)
}}}

== Recent Changes

[[ChangeLog(customfieldadminplugin, 3)]]

== Author/Contributors

'''Authors:''' [wiki:osimons], [wiki:cbalan] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''