CustomizingWithCallbacks - Revision history

Phanousk: /* Comments */

2023-07-27T12:22:45Z

Comments

← Older revision		Revision as of 08:22, 27 July 2023
Line 70:		Line 70:

	* when using the 'local' directory, you overlay '''files'''. If the original file is changed in a new release, e. g. a bug is fixed or a feature is added, you will not profit from this changes immediately, because your overlay is used.		* when using the 'local' directory, you overlay '''files'''. If the original file is changed in a new release, e. g. a bug is fixed or a feature is added, you will not profit from this changes immediately, because your overlay is used.
	* when using a XXX_Local.pm, you overlay '''methods''' and the same drawback as above will hit you if the method has been changed across releases.		* when using a XXX_Local.pm, you overlay '''methods''' and the same drawback as above will hit you if the method has been changed across releases. See [[CustomizingWithOverlays]] for details.

	For both customisation methods hold: They are not local enough! If you overlay, it might be possible that you overlay code (that you did not change) from earlier versions, that have been corrected or adopted to other changes in new versions and that is not compatible with the new version. Hence version upgrades may be complicated. I added two Sections above with customization methods I prefer, because we do many customizations, these are Patches and Callbacks. --[[DirkPape]]		For both customisation methods hold: They are not local enough! If you overlay, it might be possible that you overlay code (that you did not change) from earlier versions, that have been corrected or adopted to other changes in new versions and that is not compatible with the new version. Hence version upgrades may be complicated. I added two Sections above with customization methods I prefer, because we do many customizations, these are Patches and Callbacks. --[[DirkPape]]

Brett: formatting cleanups

2022-01-06T21:34:37Z

formatting cleanups

← Older revision		Revision as of 17:34, 6 January 2022
Line 7:		Line 7:
	Callbacks are called on different places and have to be placed into directories		Callbacks are called on different places and have to be placed into directories

	<rt root>/local/html/Callbacks/<any directory>/<normal path to html-page>/<~~CallbackName~~>		<pre><rt root>/local/html/Callbacks/<any directory>/<normal path to html-page>/<CallbackName></pre>


	* <rt root> - we suppose you know where your RT is installed		* <rt root> - we suppose you know where your RT is installed

Phanousk: /* CallbackName */

2018-08-29T08:41:16Z

CallbackName

← Older revision		Revision as of 04:41, 29 August 2018
Line 53:		Line 53:

	For example, the following callback call in Modify.html lacks a name, so its name (by default) is Default		For example, the following callback call in Modify.html lacks a name, so its name (by default) is Default
	<source lang="perl>		<source lang="perl">
	$m->callback( TicketObj => $TicketObj, CustomFields => $CustomFields, ARGSRef => \%ARGS );		$m->callback( TicketObj => $TicketObj, CustomFields => $CustomFields, ARGSRef => \%ARGS );
	</source>		</source>

Phanousk: /* CallbackName */

2018-08-29T08:40:57Z

CallbackName

← Older revision		Revision as of 04:40, 29 August 2018
Line 53:		Line 53:

	For example, the following callback call in Modify.html lacks a name, so its name (by default) is Default		For example, the following callback call in Modify.html lacks a name, so its name (by default) is Default
			<source lang="perl>
	$m->callback( TicketObj => $TicketObj, CustomFields => $CustomFields, ARGSRef => \%ARGS );		$m->callback( TicketObj => $TicketObj, CustomFields => $CustomFields, ARGSRef => \%ARGS );
			</source>

	== Sample callbacks ==		== Sample callbacks ==

Barton: /* GaryOberbrunner -- clean up code block */

2017-01-08T18:46:24Z

GaryOberbrunner -- clean up code block

@@ Line 76: / Line 76: @@
 ==== GaryOberbrunner ====
-Here's a sample [[ShowMessageStanza]] callback. Put this in
+Here's a sample [[ShowMessageStanza]] callback. Put this in /opt/rt3/share/html/Callbacks/*/Ticket/Elements/ShowMessageStanza/Default :
 Note that the stanza will appear in $$content, you just modify it in place. Thanks to Toby Darling for the code!
 ==Troubleshooting==

Barton: /* Introduction */

2017-01-08T18:38:58Z

Introduction

← Older revision		Revision as of 14:38, 8 January 2017
Line 5:		Line 5:
	RT uses Callbacks for adding extensions into the Web GUI without modifying html code. Wikipedia defines a callback as “executable code that is passed as an argument to other code. It allows a lower-level software layer to call a subroutine (or function) defined in a higher-level layer." So callback in RT is a code that you can put into right place and it will be called when a user opens a page.		RT uses Callbacks for adding extensions into the Web GUI without modifying html code. Wikipedia defines a callback as “executable code that is passed as an argument to other code. It allows a lower-level software layer to call a subroutine (or function) defined in a higher-level layer." So callback in RT is a code that you can put into right place and it will be called when a user opens a page.

	Callbacks are called on different places and have to be placed into directories ~~<~~rt root~~>~~/local/html/Callbacks/~~<~~any directory~~>~~/~~<~~normal path to html-page~~>~~/~~<~~CallbackName~~>.~~		Callbacks are called on different places and have to be placed into directories

			<rt root>/local/html/Callbacks/<any directory>/<normal path to html-page>/<CallbackName>


	* <rt root> - we suppose you know where your RT is installed		* <rt root> - we suppose you know where your RT is installed

Barton: /* Finding callbacks -- code block reformatting */

2017-01-08T18:35:51Z

Finding callbacks -- code block reformatting

← Older revision		Revision as of 14:35, 8 January 2017
Line 33:		Line 33:
	You can find all callbacks using grep command:		You can find all callbacks using grep command:

	cd /opt/rt3/		cd /opt/rt3/
	find share/html \| xargs grep '\->callback'		find share/html \| xargs grep '\->callback'

	In RT 3.6 and older syntax is slightly different, old syntax is still valid and supported:		In RT 3.6 and older syntax is slightly different, old syntax is still valid and supported:

	cd /opt/rt3/		cd /opt/rt3/
	find share/html \| xargs grep 'Elements/Callback'		find share/html \| xargs grep 'Elements/Callback'

	In RT 4.2.x these are most of them: [[RT_4.2_Callbacks]]		In RT 4.2.x these are most of them: [[RT_4.2_Callbacks]]

Barton: /* reformat code blocks */

2017-01-08T18:34:54Z

reformat code blocks

← Older revision		Revision as of 14:34, 8 January 2017
Line 17:		Line 17:
	Places where callbacks are called look in the following way (RT 3.8):		Places where callbacks are called look in the following way (RT 3.8):

	$m-~~>~~callback(		$m->callback(
	TicketObj =~~>~~ $TicketObj,		TicketObj => $TicketObj,
	ARGSRef =~~>~~ \%ARGS,		ARGSRef => \%ARGS,
	CallbackName =~~>~~ 'Initial',		CallbackName => 'Initial',
	);		);

	This is example from Ticket/Display.html in RT 3.8.7, full path to your code may look like this:		This is example from Ticket/Display.html in RT 3.8.7, full path to your code may look like this:

	/opt/rt3/local/html/Callbacks/MyCallbacks/Ticket/Display.html/Initial		/opt/rt3/local/html/Callbacks/MyCallbacks/Ticket/Display.html/Initial

	Arguments passed to callback function are passed into your code and you can use them to explore situation and modify behaviour.		Arguments passed to callback function are passed into your code and you can use them to explore situation and modify behaviour.

Admin: 13 revisions imported

2016-04-06T20:03:37Z

13 revisions imported

New page

= Callbacks =

== Introduction ==

RT uses Callbacks for adding extensions into the Web GUI without modifying html code. Wikipedia defines a callback as “executable code that is passed as an argument to other code. It allows a lower-level software layer to call a subroutine (or function) defined in a higher-level layer." So callback in RT is a code that you can put into right place and it will be called when a user opens a page.

Callbacks are called on different places and have to be placed into directories <rt root>/local/html/Callbacks/<any directory>/<normal path to html-page>/<CallbackName>.

* <rt root> - we suppose you know where your RT is installed
* local - local directory for your customizations, [[CustomizingWithLocalDir]].
* html - directory with Mason components.
* Callbacks - directory for your Callbacks, create if it doesn't exist. It's Callbacks (lowercase "b") not CallBacks (uppercase "B"), not callbacks.
* <any directory> - one directory with any name you like. Call it MyCallbacks, his_callbacks or boo. The assumption is that you will group your callbacks, based on logic of your choosing. You can have many different callback groups, and the callback will be run for each of them.
* <normal path to html-page> - if a call you want to hook on is in <code>html/X/Y.html</code> file then you should create <code>X/Y.html</code> directory.
* <CallbackName> - name of the callback, each page may have multiple callbacks. By default is 'Default', but might be different. Read more about names below.

Places where callbacks are called look in the following way (RT 3.8):

$m->callback(
TicketObj => $TicketObj,
ARGSRef => \%ARGS,
CallbackName => 'Initial',
);

This is example from Ticket/Display.html in RT 3.8.7, full path to your code may look like this:

/opt/rt3/local/html/Callbacks/MyCallbacks/Ticket/Display.html/Initial

Arguments passed to callback function are passed into your code and you can use them to explore situation and modify behaviour.

== Finding callbacks ==

You can find all callbacks using grep command:

cd /opt/rt3/
find share/html | xargs grep '\->callback'

In RT 3.6 and older syntax is slightly different, old syntax is still valid and supported:

cd /opt/rt3/
find share/html | xargs grep 'Elements/Callback'

In RT 4.2.x these are most of them: [[RT_4.2_Callbacks]]

In RT-Assets 1.01 these are most of them: [[RT-Assets_1.01_Callbacks]]

== CallbackName ==

Each Mason component may call multiple callbacks, so each callback has a name. The name of the callback you figure out from arguments used to call $m->callback. Understandably, the argument to define a callback name is 'CallbackName' and if it's absent then 'Default' is used.

For example, the following callback call in Modify.html lacks a name, so its name (by default) is Default

$m->callback( TicketObj => $TicketObj, CustomFields => $CustomFields, ARGSRef => \%ARGS );

== Sample callbacks ==

* [http://page.mi.fu-berlin.de/~pape/rt3/Callbacks/ Samples] from [[DirkPape]].
* [[AddCustomStyleSheet]]
* [[HideTransactions]]: Hide all transactions created by the system user.
* [[ShowPerQueueInstructions]]
* [[RequireCFResolve]]: Require CF value before resolve
* [[ToggleCFs]]: Hide certain Custom Fields unless a "control" CF is set to a specific value. Allows decluttering the user interface in the common case and exposes additional detail (CFs) when needed.

== Comments ==

There are some drawbacks, when customizing RT with the "Local" principle: If you have many customizations it is difficult to propagate customizations across version changes. This is mainly because

* when using the 'local' directory, you overlay '''files'''. If the original file is changed in a new release, e. g. a bug is fixed or a feature is added, you will not profit from this changes immediately, because your overlay is used.
* when using a XXX_Local.pm, you overlay '''methods''' and the same drawback as above will hit you if the method has been changed across releases.

For both customisation methods hold: They are not local enough! If you overlay, it might be possible that you overlay code (that you did not change) from earlier versions, that have been corrected or adopted to other changes in new versions and that is not compatible with the new version. Hence version upgrades may be complicated. I added two Sections above with customization methods I prefer, because we do many customizations, these are Patches and Callbacks. --[[DirkPape]]

==== GaryOberbrunner ====

Here's a sample [[ShowMessageStanza]] callback. Put this in

<nowiki>/opt/rt3/share/html/Callbacks/*/Ticket/Elements/ShowMessageStanza/Default :

<%init>
my $val = $$content;
use bytes;
# Auto link 12-digit hex strings to a search page
$val =~ s{[0-9a-f]{12}}{<a href="http://my.example.com/search?$&">$&<\/a>}gi;
$$content = $val;
</%init>
<%args>
$content => undef
</%args>

</nowiki>

Note that the stanza will appear in $$content, you just modify it in place. Thanks to Toby Darling for the code!

==Troubleshooting==
Did you clear your Mason cache? (See [[ClearMasonCache|CleanMasonCache]])

Did you restart your webserver process?

Are your Mason component settings accurate (in the web UI, visit Tools -> System Configuration and scroll down)?

Are your file and directory permissions for your new callback set properly?

Are you sure you have your callback arguments correct? Beware 'TicketObj' vs. 'Ticket' being passed!

207.236.194.136: /* Troubleshooting */

2012-02-10T19:38:40Z

Troubleshooting

← Older revision		Revision as of 15:38, 10 February 2012
Line 90:		Line 90:

	==Troubleshooting==		==Troubleshooting==
	Did you clear your Mason cache?		Did you clear your Mason cache? (See [[ClearMasonCache\|CleanMasonCache]])

	Did you restart your webserver process?		Did you restart your webserver process?