- NAME
- DESCRIPTION
- 'CORE' METHODS
  - Create PARAMHASH
  - Load ID/NAME
  - LoadByName Name => NAME, [...]
  - LoadNameAndQueue
  - LoadByNameAndQueue
  - Custom field values
    - Values FIELD
    - AddValue HASH
    - DeleteValue ID
  - ValidateValue VALUE
  - ValidateName NAME
  - ValidateQueue QUEUE
  - Types
  - IsSelectionType
  - IsCanonicalizeType
  - IsExternalValues
  - SetValuesClass CLASS
  - ValidateValuesClass CLASS
  - SetCanonicalizeClass CLASS
  - ValidateCanonicalizeClass CLASS
  - FriendlyType [TYPE, MAX_VALUES]
  - ValidateType TYPE
  - SetPattern STRING
  - _IsValidRegex(Str $regex) returns (Bool $success, Str $msg)
  - SingleValue
  - ACLEquivalenceObjects
  - ContextObject and SetContextObject
  - LoadContextObject
  - ValidateContextObject
  - _Value
  - SetDisabled
  - SetTypeComposite
  - TypeComposite
  - TypeComposites
  - RenderType
  - SetRenderType TYPE
  - DefaultRenderType [TYPE COMPOSITE]
  - HasRenderTypes [TYPE_COMPOSITE]
  - RenderTypes [TYPE COMPOSITE]
  - SetLookupType
  - Groupings Object|Class Name, Queue Name|Catalog Name
  - CustomGroupings
  - RegisterBuiltInGroupings
- AddedTo
- NotAddedTo
  - IsAdded
  - IsAddedToAny
  - AddToObject OBJECT
  - RemoveFromObject OBJECT
  - AddValueForObject HASH
  - MatchPattern STRING
  - FriendlyPattern
  - DeleteValueForObject HASH
  - ValuesForObject OBJECT
  - CurrentUserCanSee
  - CurrentUserCanCreate
  - CurrentUserCanModify
  - IncludeContentForValue [VALUE] (and SetIncludeContentForValue)
  - LinkValueTo [VALUE] (and SetLinkValueTo)
  - _URLTemplate NAME [VALUE]
  - IsNumeric
  - NumericPrecision
  - id
  - Name
  - SetName VALUE
  - Type
  - SetType VALUE
  - RenderType
  - SetRenderType VALUE
  - MaxValues
  - SetMaxValues VALUE
  - Pattern
  - SetPattern VALUE
  - BasedOn
  - SetBasedOn VALUE
  - Description
  - SetDescription VALUE
  - SortOrder
  - SetSortOrder VALUE
  - LookupType
  - SetLookupType VALUE
  - SetEntryHint VALUE
  - SetValidationHint VALUE
  - Creator
  - Created
  - LastUpdatedBy
  - LastUpdated
  - Disabled
  - SetDisabled VALUE
  - LoadByNameAndCatalog

# NAME

      RT::CustomField_Overlay - overlay for RT::CustomField

# DESCRIPTION

# 'CORE' METHODS

## Create PARAMHASH

Create takes a hash of values and creates a row in the database:

      varchar(200) 'Name'.
      varchar(200) 'Type'.
      int(11) 'MaxValues'.
      varchar(255) 'Pattern'.
      varchar(255) 'Description'.
      int(11) 'SortOrder'.
      varchar(255) 'LookupType'.
      varchar(255) 'EntryHint'.
      varchar(255) 'ValidationHint'.
      smallint(6) 'Disabled'.

`LookupType` is generally the result of either `RT::Ticket-`CustomFieldLookupType> or `RT::Transaction-`CustomFieldLookupType>.

## Load ID/NAME

Load a custom field. If the value handed in is an integer, load by custom field ID. Otherwise, Load by name.

## LoadByName Name => `NAME`, [...]

Loads the Custom field named NAME. As other optional parameters, takes:

LookupType => `LOOKUPTYPE`

  The type of Custom Field to look for; while this parameter is not required, it is highly suggested, or you may not find the Custom Field you are expecting. It should be passed a `LookupType` such as "CustomFieldLookupType" in RT::Ticket or "CustomFieldLookupType" in RT::User.

ObjectType => `CLASS`

  The class of object that the custom field is applied to. This can be intuited from the provided `LookupType`.

ObjectId => `ID`

  limits the custom field search to one applied to the relevant id. For example, if a `LookupType` of `RT::Ticket->CustomFieldLookupType` is used, this is which Queue the CF must be applied to. Pass 0 to only search custom fields that are applied globally.

IncludeDisabled => `BOOLEAN`

  Whether it should return Disabled custom fields if they match; defaults to on, though non-Disabled custom fields are returned preferentially.

IncludeGlobal => `BOOLEAN`

  Whether to also search global custom fields, even if a value is provided for `ObjectId`; defaults to off. Non-global custom fields are returned preferentially.

For backwards compatibility, a value passed for `Queue` is equivalent to specifying a `LookupType` of "CustomFieldLookupType" in RT::Ticket, and a `ObjectId` of the value passed as `Queue`.

If multiple custom fields match the above constraints, the first according to `SortOrder` will be returned; ties are broken by `id`, lowest-first.

## LoadNameAndQueue

## LoadByNameAndQueue

Deprecated alternate names for "LoadByName".

## Custom field values

### Values FIELD

Return a object (collection) of all acceptable values for this Custom Field. Class of the object can vary and depends on the return value of the `ValuesClass` method.

### AddValue HASH

Create a new value for this CustomField. Takes a paramhash containing the elements Name, Description and SortOrder

### DeleteValue ID

Deletes a value from this custom field by id.

Does not remove this value for any article which has had it selected

## ValidateValue VALUE

Make sure that the supplied value is valid

## ValidateName NAME

Make sure that the name specified is valid

## ValidateQueue QUEUE

Make sure that the queue specified is a valid queue name

## Types

Retuns an array of the types of CustomField that are supported

## IsSelectionType

Returns a boolean value indicating whether the `Values` method makes sense to this Custom Field.

## IsCanonicalizeType

Returns a boolean value indicating whether the type of this custom field permits using a canonicalizer.

## IsExternalValues

## SetValuesClass CLASS

Writer method for the ValuesClass field; validates that the custom field can use a ValuesClass, and that the provided ValuesClass passes "ValidateValuesClass".

## ValidateValuesClass CLASS

Validates a potential ValuesClass value; the ValuesClass may be `undef` or the string `"RT::CustomFieldValues"` (both of which make this custom field use the ordinary values implementation), or a class name in the listed in the "@CustomFieldValuesSources" in RT_Config setting.

Returns true if valid; false if invalid.

## SetCanonicalizeClass CLASS

Writer method for the CanonicalizeClass field; validates that the custom field can use a CanonicalizeClass, and that the provided CanonicalizeClass passes "ValidateCanonicalizeClass".

## ValidateCanonicalizeClass CLASS

Validates a potential CanonicalizeClass value; the CanonicalizeClass may be `undef` (which make this custom field use no special canonicalization), or a class name in the listed in the "@CustomFieldValuesCanonicalizers" in RT_Config setting.

Returns true if valid; false if invalid.

## FriendlyType [TYPE, MAX_VALUES]

Returns a localized human-readable version of the custom field type. If a custom field type is specified as the parameter, the friendly type for that type will be returned

## ValidateType TYPE

Takes a single string. returns true if that string is a value type of custom field

## SetPattern STRING

Takes a single string representing a regular expression. Performs basic validation on that regex, and sets the `Pattern` field for the CF if it is valid.

## _IsValidRegex(Str $regex) returns (Bool $success, Str $msg)

Tests if the string contains an invalid regex.

## SingleValue

Returns true if this CustomField only accepts a single value. Returns false if it accepts multiple values

## ACLEquivalenceObjects

Returns list of objects via which users can get rights on this custom field. For custom fields these objects can be set using ContextObject.

## ContextObject and SetContextObject

Set or get a context for this object. It can be ticket, queue or another object this CF added to. Used for ACL control, for example SeeCustomField can be granted on queue level to allow people to see all fields added to the queue.

## LoadContextObject

Takes an Id for a Context Object and loads the right kind of RT::Object for this particular Custom Field (based on the LookupType) and returns it. This is a good way to ensure you don't try to use a Queue as a Context Object on a User Custom Field.

## ValidateContextObject

Ensure that a given ContextObject applies to this Custom Field. For custom fields that are assigned to Queues or to Classes, this checks that the Custom Field is actually added to that object. For Global Custom Fields, it returns true as long as the Object is of the right type, because you may be using your permissions on a given Queue of Class to see a Global CF. For CFs that are only added globally, you don't need a ContextObject.

## _Value

Takes the name of a table column. Returns its value as a string, if the user passes an ACL check

## SetDisabled

Takes a boolean. 1 will cause this custom field to no longer be available for objects. 0 will re-enable this field.

## SetTypeComposite

Set this custom field's type and maximum values as a composite value

## TypeComposite

Returns a composite value composed of this object's type and maximum values

## TypeComposites

Returns an array of all possible composite values for custom fields.

## RenderType

Returns the type of form widget to render for this custom field. Currently this only affects fields which return true for "HasRenderTypes".

## SetRenderType TYPE

Sets this custom field's render type.

## DefaultRenderType [TYPE COMPOSITE]

Returns the default render type for this custom field's type or the TYPE COMPOSITE specified as an argument.

## HasRenderTypes [TYPE_COMPOSITE]

Returns a boolean value indicating whether the "RenderTypes" and "RenderType" methods make sense for this custom field.

Currently true only for type `Select`.

## RenderTypes [TYPE COMPOSITE]

Returns the valid render types for this custom field's type or the TYPE COMPOSITE specified as an argument.

## SetLookupType

Autrijus: care to doc how LookupTypes work?

## Groupings Object|Class Name, Queue Name|Catalog Name

Returns a (sorted and lowercased) list of the groupings in which this custom field appears.

If called on a loaded object, the returned list is limited to groupings which apply to the record class this CF applies to ("RecordClassFromLookupType").

If passed a loaded object or a class name, the returned list is limited to groupings which apply to the class of the object or the specified class.

You can optionally pass queue/catalog name to get queue/catalog level of groupings for the record class, and it'll automatically fallback to default groupings for the record class.

If called on an unloaded object, all potential default groupings are returned.

## CustomGroupings

Identical to "Groupings" but filters out built-in groupings from the the returned list.

## RegisterBuiltInGroupings

Registers groupings to be considered a fundamental part of RT, either via use in core RT or via an extension. These groupings must be rendered explicitly in Mason by specific calls to /Elements/ShowCustomFields and /Elements/EditCustomFields. They will not show up automatically on normal display pages like configured custom groupings.

Takes a set of key-value pairs of class names (valid RT::Record subclasses) and array refs of grouping names to consider built-in.

If a class already contains built-in groupings (such as RT::Ticket and RT::User), new groupings are appended.

# AddedTo

Returns collection with objects this custom field is added to. Class of the collection depends on "LookupType". See all "NotAddedTo" .

Doesn't takes into account if object is added globally.

# NotAddedTo

Returns collection with objects this custom field is not added to. Class of the collection depends on "LookupType". See all "AddedTo" .

Doesn't take into account if the object is added globally.

## IsAdded

Takes object id and returns corresponding RT::ObjectCustomField record if this custom field is added to the object. Use 0 to check if custom field is added globally.

## IsAddedToAny

Returns true if custom field is applied to any object.

## AddToObject OBJECT

Add this custom field as a custom field for a single object, such as a queue or group.

Takes an object

## RemoveFromObject OBJECT

Remove this custom field for a single object, such as a queue or group.

Takes an object

## AddValueForObject HASH

Adds a custom field value for a record object of some kind. Takes a param hash of

Required:

        Object
        Content

Optional:

        LargeContent
        ContentType

## MatchPattern STRING

Tests the incoming string against the Pattern of this custom field object and returns a boolean; returns true if the Pattern is empty.

## FriendlyPattern

Prettify the pattern of this custom field, by taking the text in `(?#text)` and localizing it.

## DeleteValueForObject HASH

Deletes a custom field value for a ticket. Takes a param hash of Object and Content

Returns a tuple of (STATUS, MESSAGE). If the call succeeded, the STATUS is true. otherwise it's false

## ValuesForObject OBJECT

Return an RT::ObjectCustomFieldValues object containing all of this custom field's values for OBJECT

## CurrentUserCanSee

If the user has SeeCustomField they can see this custom field and its details.

Otherwise, if the user has SetInitialCustomField and this is being used in a "create" context, then they can see this custom field and its details. This allows you to set up custom fields that are only visible on create pages and are then inaccessible.

## CurrentUserCanCreate

If the user has AdminCustomField they can create a new custom field.

## CurrentUserCanModify

If the user has AdminCustomField they can modify the custom field.

## IncludeContentForValue [VALUE] (and SetIncludeContentForValue)

Gets or sets the `IncludeContentForValue` for this custom field. RT uses this field to automatically include content into the user's browser as they display records with custom fields in RT.

## LinkValueTo [VALUE] (and SetLinkValueTo)

Gets or sets the `LinkValueTo` for this custom field. RT uses this field to make custom field values into hyperlinks in the user's browser as they display records with custom fields in RT.

## _URLTemplate NAME [VALUE]

With one argument, returns the _URLTemplate named `NAME`, but only if the current user has the right to see this custom field.

With two arguments, attempts to set the relevant template value.

## IsNumeric

Returns true if the custom field is supposed to be numeric, default is 0.

Right now you need to override this method to mark the chosen ones numeric.

## NumericPrecision

Returns the precision if the custom field is numeric, default is `undef`.

Right now you need to override this method to customize it.

## id

Returns the current value of id. (In the database, id is stored as int(11).)

## Name

Returns the current value of Name. (In the database, Name is stored as varchar(200).)

## SetName VALUE

Set Name to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, Name will be stored as a varchar(200).)

## Type

Returns the current value of Type. (In the database, Type is stored as varchar(200).)

## SetType VALUE

Set Type to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, Type will be stored as a varchar(200).)

## RenderType

Returns the current value of RenderType. (In the database, RenderType is stored as varchar(64).)

## SetRenderType VALUE

Set RenderType to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, RenderType will be stored as a varchar(64).)

Only valid when `Type` is "Select". Controls how the CF is displayed when editing it. Valid values are: `Select box`, `List`, `Dropdown`, and `Checkbox`.

`List` is rendered as radio buttons when MaxValues is 1 (accepts one value) or as checkboxes when MaxValues is 0 (accepts multiple values).

`Checkbox` renders as a single checkbox and expects two values, first for unchecked and the other for checked.

## MaxValues

Returns the current value of MaxValues. (In the database, MaxValues is stored as int(11).)

## SetMaxValues VALUE

Set MaxValues to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, MaxValues will be stored as a int(11).)

## Pattern

Returns the current value of Pattern. (In the database, Pattern is stored as text.)

## SetPattern VALUE

Set Pattern to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, Pattern will be stored as a text.)

## BasedOn

Returns the current value of BasedOn. (In the database, BasedOn is stored as int(11).)

## SetBasedOn VALUE

Set BasedOn to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, BasedOn will be stored as a int(11).)

## Description

Returns the current value of Description. (In the database, Description is stored as varchar(255).)

## SetDescription VALUE

Set Description to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, Description will be stored as a varchar(255).)

## SortOrder

Returns the current value of SortOrder. (In the database, SortOrder is stored as int(11).)

## SetSortOrder VALUE

Set SortOrder to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, SortOrder will be stored as a int(11).)

## LookupType

Returns the current value of LookupType. (In the database, LookupType is stored as varchar(255).)

## SetLookupType VALUE

Set LookupType to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, LookupType will be stored as a varchar(255).)

## SetEntryHint VALUE

Set EntryHint to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, EntryHint will be stored as a varchar(255).)

## SetValidationHint VALUE

Set ValidationHint to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, ValidationHint will be stored as a varchar(255).)

## Creator

Returns the current value of Creator. (In the database, Creator is stored as int(11).)

## Created

Returns the current value of Created. (In the database, Created is stored as datetime.)

## LastUpdatedBy

Returns the current value of LastUpdatedBy. (In the database, LastUpdatedBy is stored as int(11).)

## LastUpdated

Returns the current value of LastUpdated. (In the database, LastUpdated is stored as datetime.)

## Disabled

Returns the current value of Disabled. (In the database, Disabled is stored as smallint(6).)

## SetDisabled VALUE

Set Disabled to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, Disabled will be stored as a smallint(6).)

## LoadByNameAndCatalog

Loads the described asset custom field, if one is found, into the current object. This method only consults custom fields applied to RT::Catalog for RT::Asset objects.

Takes a hash with the keys:

Name

  A RT::CustomField ID or Name which applies to assets.

Catalog

  Optional. An RT::Catalog ID or Name.

If Catalog is specified, only a custom field added to that Catalog will be loaded.

If Catalog is `0`, only global asset custom fields will be loaded.

If no Catalog is specified, all asset custom fields are searched including global and catalog-specific CFs.

Please note that this method may load a Disabled custom field if no others matching the same criteria are found. Enabled CFs are preferentially loaded.

← Back to index