RT 5.0.4 Documentation

RT::CustomField

Go to latest version →

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

ValidateQueue Queue

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 avaialble 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.

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, attemptes to set the relevant template value.

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

Security contact information
© 2002-2024 Best Practical Solutions LLC.