Documentation
Table of Content
Installation
Package installation
trac configuration
Browser report configuration
Creating tickets
New Ticket Block Usage
Ticket Creation User interface
Customizing the ticket form
Configuring backends
Advanced Users
Adjusting the number of active tickets
Lock or unlock the new ticket edit dialog
Hiding/"un-hiding" a backend from admin
Locking the dashboard interface
For Developers
Adding a custom report item
Adding a custom value source
Support
Quick Start
- Install Trac Pro on your target website
- Add a Trac Pro New Ticket block to a page
- Configure the trac backend in the edit dialog
- Publish the page
- That's it, users can now directly file tickets into your trac server from that page
If you want to know more, then read the rest of this documentation.
Installation
Package installation
The recommended method to install Trac Pro, is simply using your target website marketplace page. However, if you wish not to use concrete5 internal feature, you can follow the next instructions :
- Download the zip archive
- Uncompress the zip archive into your packages/ directory
- Visit your page (located at http://yoursite.com/index.php/dashboard/extend/install )
- Click on the Trac Pro Install button
After installing Trac Pro (either through downloading or preferably directly through your concrete5 website interface), you will be provided with the Trac Pro New Ticket block. The package will also install a dashboard menu containing the two following pages:
- to manage existing backends
trac configuration
A complete installation guide of trac is beyond this documentation. However, you can find the documentation on the trac project website.
This addon requires the trac TracXMLRPC plugin to be installed and activated on the trac server. In order to install the plugin, pleas follow the XMLRPC plugin.
Once installed, you can activate the TracXMLRPC plugin from the trac admin interface. ->, then enable the TracXMLRPC plugin.
Finally, a user must have the XML_RPC permission attached to his trac login account to use this plugin. This permission can be set on all users (or groups) through the > page.
The user must have the TICKET_CREATE privilege to permit ticket creation. Attachments will require to have the ATTACHEMENT_CREATE privilege. This is automatically granted to TICKET_CREATE enabled users, but you must add it manually for anonymous (in case you plan to access this trac installation via anonymous). Optional: The user must have the TICKET_ADMIN privilege to enable ticket rollback in case of error).
In case you plan to let anonymous users create tickets on your trac, don't forget to add the XML_RPC permission to your anonymous user group. You can do that by visiting the > page of your trac installation.
Browser report configuration
The automatic browser detection needs browscap.ini file to be installed on the server. More information on how to install browscap can be found on the php documentation website, or directly on the browscap homepage
In case browscap is not correctly configured, a message will be displayed in the Trac Pro New Ticket dialog, in the tab :
Additionally, in the new report dialog, under the attachment automatic report (in case you added the automated report), the following message will can be seen in the automatic report:
Creating tickets
New Ticket Block Usage
To allow your users to issue ticket from any page, add the Trac Pro New Ticket to the page.
The edit/add dialog contains the following tabs:
- to configure the backend access
- to configure the in-page prompt and behavior
- to configure the ticket form defaults
- to configure the ticket attachments
This tab allow you to select an existing (already configured backend), or to connect this block to a new backend. Any created backend will automatically be recorded and available for other blocks in the future.
To select a backend in the existing backend list, just click on any of the backend lines, the selected line will then turn blue:
If you wish to use a new backend for this block, (or if no backend is available), click on the New connection radio button:
You will then have to enter the following information:
- trac base URL
- Query user credentials (used only for browsing the server structure)
- User mapping (used for creating actual tickets)
The button allow you to test the backend connectivity before saving it with the button.
After the backend is created, you are automatically redirected to the selection interface (the new backend being selected).
This section only shows an overview of backend configuration abilities, for more information refer to the Configuring backends section of this documentation.
The tab provides several options to finely control the way users will see the ticket creation (link, text, etc...):
The following options are available:
- Ticket prompt: shows a text
- Ticket image: display an image button (3 states)
- Show to Guest: make the report link available to non-logged-in users
- Use captcha: require captcha before submitting (spam protection)
- Ticket in new window: show ticket in a window or an ajax dialog
- Ticket dialog width/height: define the dialog with/height in px
- Link to new ticket: allow users to connect to the trac server ticket
The Ticket image options, you can create a 3 state button simply by selecting images from the file manager. To change an image, simply click on an image you want to change.
Both the text prompt and the image can be disabled by unselecting the checkbox next to the option label.
Finally, a red button hides options to lock the block interface, please refer to the Advanced Userssection of this documentation for more information regarding the locking mechanism.
A ticket is structured in different fields. Each field of the ticket can be independently configured from any others:
The following controls are available for each field independently:
- ignore: so that the field is not submitted
- mandatory: to force this field to be field out
- show: to show the field in the ticket form
- read only:to make a field read only in the ticket form
For example, to show a field, but make that field not modifiable from the user, select the show and read only options. Another example, in order to add a value to the ticket but not let the user see it (static field), unselect the show option.
Finally, each field value can be set from different sources. In case the field is modifiable (that is, shown to the user, and not read only), that value will be only used as default value.
Each field value can be set from the following source
- User input : the user will fill in the value
- User attribute: read from a logged-in user text attribute value
- Page attribute: read from a current page text attribute value
- User profile: the current user profile name (user name)
- User ID: the current user id
- Current Page URI: the current page URI
- Current Page ID: the current page id (collection ID or cID)
- Automatic Report: A report item value
- Random Number: an example of a custom value source
Each automatic report is made of a collection of several items. Each item can be set directly to fill a field value. You can also add custom report items, and those custom report items will then be made available in the default value settings of this dialog. Additionally, you can develop custom value sources to retrieve specific data from your application.
Additionally, developers can add report items and value sources to their packages and distribute them directly with their packages. Those report items and value sources will then be automatically available in the ticket interface.
Please refer to the For Developerssection of this documentation, to learn how to code and distribute specific data of your application.
The attachment tab let you configure the way users can attach attachments to the ticket submission as well as the automatic report and report items.
The first part of the dialog controls the ability for reporters to add attachments. The Allow reporters to add custom attachments let your users add attachments from the file manager.
The second part will control the automatic report. You can add a automatic report containing specific informations of the currently running page into the ticket. Those information are computed at the time of the page rendering (allowing you to spot precisely the conditions your users actually were in when the face the situation they are reporting a problem about). All those information are appended in an HTML file, automatically attached to the created ticket (in case the Append automatic report as attachment is selected.
You can control which data is gathered and added to the automatic report. Each items can be activated or deactivated depending on your need. The following reports items are by default available:
- Client Information: HTTP client information (such as browser etc...)
- Form variables: the $_POST and $_GET variables
- Current Page Information: concrete5 information about the current page being displayed
- Javascript Client Information: Browser information retrieved by javascript
- Site Environment: Site environment, c5 version, PHP information etc…
If you need specific information, you can develop your custom report item, or contact us directly
Ticket Creation User interface
Tickets are directly filed into the trac server. For this reason, users (that is, the actual visitor of your website) will need to be connected onto the trac server directly. Those credentials will most likely differ from their website credentials.
Depending on the backend configuration, those credentials will be either retrieved from some existing sources, (user attributes, page attribute, default settings, etc…) or asked from the user directly (in case of user input option).
If needed, the credentials will be asked directly to the user when he/she clicks on the report button :
After the first successful connection to the trac server, those credentials will be stored into the user session. (Trac Pro stores all sensitive information ciphered, so no information can be retrieved from either side).
The next time the same user will attempt to file a ticket, if he/she already connected that specific backend (comparing the backend base URI), stored credentials will directly be used, and the user will not have to sign in again.
If you do not wish your users to input a user/password to connect to the trac server, you can either retrieve those credentials from an attribute or set them directly in the backend configuration, as the query user.
Once the user is connected to the trac server, the user can then file a new ticket from the new ticket interface:
The actual content of the dialog is fully customizable, and will depend on your actual configuration in the Trac Pro New Ticket edit block dialog. Moreover, the actual interface depend on your choice (either using the AJAX overlay dialog, or using the single page, described in the next sub-section).
By default, the New ticket interface contains the following tabs :
- : Containing the Summary, Reporter, and Description field
- : Containing all the fields detected on the trac server
- : Managing the new tickets attachments
All section names and content can be customized in the Trac Pro New Ticket edit block. You can add, delete, move any section as well as moving a field from one section to another, making that field read-only, or simply ignoring it. Additionally, you can also order fields in two columns, one column or using a custom CSS class.
The tab shows all fields declared on the trac ticket system:
Each field have the label defined in the trac server, and can be filled using the appropriate input type (depending on the ticket type directly).
The tab shows future ticket attachments:
To preview a ticket attachment in this dialog tab, just click on the attachment summary:
To fold the attachment again, just click on the preview again.
Each attachment can be directly manipulated from this tab (depending on the admin configuration) :
The reporter can either delete an existing attachment (including the automatic report), or add a new attachment directly from the concrete5 file manager. (Users can then upload new files directly if they have sufficient permissions on the c5 website).
Finally, the ticket is actually created when the reporter hits the button. Depending on the configuration, once the ticket is created on the trac server, a message will be shown to the user inviting him to directly visit the trac server:
This link can message can be disabled in the Trac Pro New Ticket edit dialog (under the tab).:
Alternatively, if you don't want reporters to file tickets from an overlay dialog, you can have them file tickets in a new window using the Ticket in new window option of the block edit dialog (under the tab. This method uses a single page provided by the package that you can customize just like any other page of concrete5 :
To modify this single page, use the (natively available from the menu of concrete5), and visit the > page. The message Invalid Block Request will be displayed in the page (this is normal since you are visiting directly instead of using the block ticket submission link)). Finally edit this page (in edit mode).
This single page provides the following areas where you can add blocks:
- Ticket Header displayed before the ticket form
- Ticket Block Not Found displayed in case of ticket error only
- Ticket Submission Success displayed after a ticket had been successfully submitted
- Ticket Footer displayed after the ticket form
Using the provided areas, you can easily customize the ticket submission page to your own need. The ticket submission interface described in the proceeding section will be displayed between the Ticket Header and Ticket Footer area. The ticket submission interface is still dependent on each block configuration, thus can still be fully customized for each need.
If the user wishes to log out from the trac server, he/she can use the button present in the new ticket dialog. To do this, just click on the report issuing prompt in any page, and locate the button in the following dialog:
Once the user disconnect from the trac server, he will be redirected to the login dialog.
Customizing the ticket form
The ticket form shown to reporters can be entirely configured. To do this, just open the edit dialog of the Trac Pro New Ticket block, and go to the tab. From there you can manage all information shown to or asked from the user, as well as the way they are displayed in the form.
The style option lets you choose the way fields are shown in the ticket form:
- One column: the section will be a list of fields, organized in only one column
- Two columns: the section will be a two column list of its field (in the order shown)
- Custom: to let you specify a custom css class name to be used on that section (you will then have to write the custom CSS for it)
By default, two sections are already created for you (Summary, and Attributes). You can either change this setup or use it directly.
In case only one section is created, no tab is present in the ticket form.
The ticket form is organized in sections. Each section will be shown in its own tab. Sections can be edited, moved, deleted depending on your needs. Sections are shown in the greyed bar, and comes with several controls:
Using these controls you can easily rename the section, (using the edit button provided in the section header), move the section by dragging the section bar (and all the fields with it), under the next section, change the style used to show the inner fields.
To move a section, just click anywhere in the section grey header, and start dragging it:
All sections will be collapsed during section dragging to help you reorganize them easily. The section being dragged will also be faded away, all other sections will reorganize around it as you move the section.
Adding a section can be done by clicking on the add button of the section header, in this case a section will be added right after the section. You will then be able to move the Fields from one section to that new section by dragging the field directly under the new section.
Finally, removing a section can be done using the remove button of the section header. Removing a section will move all its fields to the next present section.
Each field can be organized by dragging the field itself in the section or moved to another section by dragging it to another section directly.
To drag a field, just click anywhere in the field (aside from the inputs), and start dragging it. The field will be faded while dragging and other fields will automatically reorganize around it.
By playing with the different controls available (ignore,mandatory, show, read only), you can decide to show a field to the reporter, to include the field in the form or simply not to include it at all.
The default input let you decide the default value that the field will have when shown to the reporter or simply what value will be transmitted in case the field is read only. (Eg: having a not show field read only is a simple way to specify a data directly without the user noticing it).
Depending on the field type, the default can either be a text input (line or text area), or being a multiple choice input (eg: select). The structure of the field actually depends on the structure of the trac server directly. Trac Pro will enforce field types as defined directly in the trac server.
Fields can not be added directly in the ticket block edit dialog. Fields are present on the server, and depend on the trac server only. To add a new field, you must first declare it on the server side, and then come back to the edit dialog to configure it.
The project is handled as a specific field of the ticket form. This approach allows you to let the reporter choose the project he wants to file the ticket into.
Obviously, there are situations where you want to choose the project instead of your users. For this case, select the project and make the field read-only. You can then choose to show that field into the form or not (ignore option).
Since the project is a mandatory field, it can not be ignored.
Additionally, some fields may or may not be available depending on the project selected. The GUI will adapt to the user choice. Some field will be shown to the user only if selects the appropriate project.
Moreover, in some cases, a field may have different choices depending on the project selection. For those fields, a multiple default input will be shown (one for each possibility) :
Hover the field with the mouse to see what condition this field default will be used into.
If you decide to make the project field read-only, those multiple choices are hidden, since the user will not be able to select a different project. As a result, all fields not related to this project will also be hidden from the edit dialog.
Configuring backends
Trac Pro needs to access the server to discover the server structure. Most of the time, those server needs credentials (user/pass etc…) to discover their structure. For this reason, each block is attached to a specific backend description. Backend management can be accessed either from the add/edit dialog in the tab, or from the dashboard in the -> page. Both location show the full backend management GUI.
Once created (either in the add/edit dialog, or the dashboard), a backend can be used by any blocks.
Trac Pro uses a specific credential to communicate with the backend. These credentials (referred to as test user), are only used before the ticket submission. Tickets are actually created using the "mapped user". You can take this user from several location (see further section).
To create a new backend, either go to the add/edit block dialog, or visit the backends dashboard page and click on the button. This button will then show you the creation dialog asking for several information:
- trac url: the base url (eg: http://trac.localhost/) of the server
- Query User, User/Password: the credentials used to connect to the server (not to create tickets)
- Mapping User/Password: where to take the credentials to create a ticket
The same GUI can be used to modify/remove an existing backend using the edit/remove button:
The mapping user (as explained earlier) is the user actually used to create ticket. You can take this user/password from any of the following sources:
- Query user using the same credentials as for querying the trac server
- user input the user will be prompted a user/password on first connection
- c5 profile (only for user name), uses the c5 currently logged in user name
- user attributeuses a text type user attribute of the currently logged in user
- page attributeuses a text type page attribute where the block is added
Trac Pro does not store password in plain texts, but instead cipher them in the database, so it is safe to store the password there.
In case the user input method is selected, users will have to directly login onto the trac server. A login dialog will be presented before the first ticket form is shown.
Only needed information will be asked, for instance if you set the password or username source from another source, it will not be asked in the login dialog.
The credentials will then be stored in session and not asked again to the user for the same backend.
Trac Pro stores a ciphered version of the password in the session only to ensure the password can not be compromised by potential attackers.
Using the two latest options, you can actually map a user name/password for each different page or user. Attributes must exists before being assigned here (please refer to the c5 documentation on how to create text attributes).
If, for some reason, you want to globally disable all Trac Pro New Ticket blocks, you can directly control the activation using the >> page, and using the Disable all reports blocks.
Disabling all blocks will prevent the report link to be shown and any ticket report to be computed at once. (Useful for releasing websites for instance, or for performance trouble shoot).
Advanced Users
Adjusting the number of active tickets
Trac Pro stores one ticket report per page, on each page load of the users. Those tickets are stored in the user session (on the server side), and are destroyed in a FIFO type of way. By default, the last 10 tickets reports are stored in the session (which means that the 11th ticket will replace the 1st ticket that was initially stored). Off course, only tickets reports used to create an actual ticket (that is, if the user actually file a ticket from that specific page) is used, all other tickets are just stored in the session, just in case a user would then use it.
The maximum number actually means that if a user have more than 10 currently opened pages, and tries to file a ticket from one of the first (in time) he/she opened, then the ticket report can actually not be filed along with the issue. (This only applies in the specific case of one user concurrently opening multiple pages, and keep them opened).
If you think your users will open more than 10 pages (or stay on the first pages, and then navigate more than 10 pages from a new window or a page), you can increase that number in the > page:
Lock or unlock the new ticket edit dialog
In some specific situations, the website creator is actually a different entity from the one who is going to use it. For instance, the you are a developer or a web agency and want to deliver your website to a customer. In this case, you probably want to ensure all his support requests are stored on your ticket servers, but you also probably want to avoid him to meddle with the ticket system itself.
For this type of situations, (and possibly a lot more), an advanced option allows you to lock the ticket configuration away from the site admin himself. Go to the Trac Pro New Ticket edit block dialog, enter the tab and click on the button. Hitting this button will show the locking GUI:
If the Lock the configuration option is checked when the configuration is saved, the edit block dialog will then be disabled. To unlock it you will need to input an SQL query directly into your DBMS system. You can then choose between showing that SQL query or not in the edit dialog. In case the edit dialog is locked and the SQL query is shown, here is the message that will be displayed :
To unlock the GUI you will then have to run the shown SQL query. The SQL query is the following:
UPDATE btGntTracProReport SET configurationLock = 0 WHERE bID = block_id;
Replace block_id by the actual block ID (bID) of the locked block.
You can, at your choice, decide not to show the unlocking query, in this case, just unselect the Show unlock SQL query in edit dialog message, in which case the edit dialog will show the following information:
Hiding/"un-hiding" a backend from admin
In the same way you can lock a block edit configuration, you can also lock a backend away from the site admin. This ensures that your admin will not be able to meddle with the backend that points directly to your QA system. Hidden backends can not be used on new blocks but remain valid for already configured blocks.
To lock a specific backend, you must go to the > dashboard page and click on the . The following will options will be shown:
To hide the backend, check the corresponding option and hit the button.
To unlock a backend, just visit the same page again, and uncheck the corresponding backend hide option.
Locking the dashboard interface
The settings dashboard interface (allowing to hide/show backends and set the maximum number of tickets stored in the session) can be locked away from admins as well by visiting the > page, then hitting the . The following will options will be shown:
To lock this page, simply select the Lock this page option and hit the button.
Once the settings page is locked, visiting the page will display the following message:
To unlock the page, you will have to manually change the GRP_LOCK_DASHBOARD_PAGE parameter associate with gnt_trac_prodirectly in the database. To do so, you will have to run the following SQL Query:
UPDATE Config, Packages SET cfValue=0 WHERE cfKey = "GTP_LOCK_DASHBOARD_PAGE" AND Config.pkgID = Packages.pkgID AND pkgHandle = "gnt_trac_pro";
If you are unsure how to do that you probably don't want to lock this page in the first place…
For Developers
Trac Pro comes with a very powerful and flexible way to extend it to add your own data into the created ticket.
Adding a custom report item
Trac Pro will automatically create a HTML report to created ticket. As stated, you can activate or not any item of that report, but that is not all, actually you can very easily add your own report items to it, they will be then accessible to any trac button, here is how :
Report items can be added to your site override or onto a package you are creating. To add report items into your site override, create the following directory :
your_site/blocks/gnt_trac_pro_report/models/reportitems
To add a report items into a package you are creating, create the following directory :
your_package/models/gnt_trac_pro_report/reportitems
Within the created directory, create a file with the named after the report item you want, for instance my_stuff.php. Now in that file, you will need to define a class inheriting from ReportItem named after your file name (camel-cased) and suffixed with ReportItem. Following our example, if the file is named my_stuff.php then the class should be MyStuffReportItem
Here is what such a class could look like :
<?php defined('C5_EXECUTE') or die('Access Denied.'); if ( !class_exists( 'MyStuffReportItem' ) ) { class MyStuffReportItem extends ReportItem { public function heading() { // return a string providing the heading // used in the edit dialog : return t("My Important Stuffs"); } public function description() { // return a long description string // used in the edit dialog : return t("Fetch all project important data"); } protected function _compute() { // This is called in the page context // so that the report can be computed // First, let's add a section to the report : $this->addSection( 'my_stuff', // section key t( 'My Important Data' ) // section name ); // then add items into the section $this->setData( 'my_stuff', // section key 'first_text', // item data key 'My automated data', // actual data t('Important first text') // item label ); // You can add any section / data or add a data to // any existing section if you know the section key } } }
Let's explain it a little :
When a Trac Pro New Ticket block is edited, (in the edit or add dialog), Trac Pro will search for all existing *ReportItemclass files in the afore-mentioned directories, then attempt to load the file and create a corresponding object.
In the configuration tab, the heading outputted by MyStuffReportItem::heading() will be used along with the MyStuffReportItem::description() to provide a checkbox to enable the report item within this particular automatic report.
Lastly, upon ticket creation (that is when Trac Pro New Ticket is being viewed), the MyStuffReportItem::_compute() is called to compute the report content. That method must actually pull all data to add in the report. Any data must be set into a report item using ReportItem::setData() method call. Data are arranged into sections, to add a section, use ReportItem::addSection() as shown in the above example.
And ... that's it! you just added a custom report item that will be automatically added to the report whenever the end user will create a ticket. That will allow you to add any important runtime data to be fetched at the page execution time, to track down an issue for instance.
Here is a more complex example, the following file is the "Current Page Information" section of the automated report.
<?php defined('C5_EXECUTE') or die('Access Denied.'); /** *-----------------------------------------------------------------------------* * * * License: Concrete5 marketplace : * * https://marketplace.concretecms.com/help/legal/commercial_add-on_license/ * * * * @author (Florian Delizy) * * * * Copyright(C) 2013 Florian Delizy <florian.delizy@gmail.com> * *-----------------------------------------------------------------------------* */ if (!class_exists( 'PageReportItem' ) ) { class PageReportItem extends ReportItem { public function heading() { return t('Current Page Information'); } public function description() { return t( 'Get current page informations (c5 specifics) at page loading time' ); } protected function _compute() { Loader::model( 'page' ); $c = Page::getCurrentPage(); if ( ! $c || $c->isError() ) $c = null; // Trac Pro will first create a report not bound to a page to list available data // General : $this->addSection( 'general', t('General') ); $this->setData( 'general', 'name', $c ? $c->getCollectionName() : t('Dummy name'), t('name') ); $this->setData( 'general', 'path', $c ? $c->getCollectionPath() : t('Dummy path'), t('path') ); $this->setData( 'general', 'cID', $c ? $c->getCollectionID() : t('Dummy cID'), t('collection ID' ) ); $user = t('nobody'); if ( $c && $c->isCheckedOut() ) { $user = $c->getCollectionCheckedOutUserName(); if ( $c->isCheckedOutByMe() ) $user = t( 'By current User' ); } $this->setData( 'general', 'checkedout', $user, t('checked out') ); // Page Type : $this->addSection( 'type', t('Page Type') ); $this->setData( 'type', 'id', $c ? $c->getCollectionTypeID() : t('Dummy Type ID'), t('ID') ); $this->setData( 'type', 'name', $c ? $c->getCollectionTypeName() : t('Dummy Type Name'), t('name') ); $this->setData( 'type', 'handle', $c ? $c->getCollectionTypeHandle() : t('Dummy Type Handle'), t('handle') ); // Version : $v = null; if ( $c ) $v = $c->getVersionObject(); $this->addSection( 'version', t('Page Versions') ); $this->setData( 'version', 'id', $v ? $v->getVersionID() : t('Dummy Version ID'), t('ID') ); $this->setData( 'version', 'name', $v ? $v->getVersionName() : t('Dummy Version Name'), t('name') ); $this->setData( 'version', 'perm', $v ? $v->getPermissionObjectIdentifier() : t('Dummy Perm ID'), t('Permission Object') ); // Package related info $this->addSection( 'package', t('Package related' ) ); if ( $c && $c->getPackageID() > 0 ) { $pkg = Package::getByID( $c->getPackageID() ); $this->setData( 'package', 'id', $pkg->getPackageID(), t('ID') ); $this->setData( 'package', 'name', $pkg->getPackageName(), t('name') ); $this->setData( 'package', 'handle', $pkg->getPackageHandle(), t('Handle') ); } else { $this->setData( 'package', 'id', t('NA'), t('ID') ); $this->setData( 'package', 'name', t('NA'), t('name') ); $this->setData( 'package', 'handle', t('NA'), t('Handle') ); } } } } // vim: set noexpandtab ts=4 :
In edit mode Trac Pro will create a dummy page report, not bound to any page in order to list all report available data. Those data will be shown in the available sources in the fields default. Thus, it is important that whenever you create a report, you always have all data items reported (even if those data are not relevant in a particular scenario) so that the defaults system can pick any value at any time.
You will notice that this report item will add several sections under its global heading. Each report item has its own heading as global section, so don't fear to override an existing section, actually, each report item uses its handle (the lower cased name of the class without ReportItem, in that case page) as a section handle. As long as your report item is having a unique report item handle, no data can overlap.
Which brings up another interesting feature of Trac Pro: you actually can override an existing report item.
In order to override an existing report item, just copy an existing report item file in your site override : your_site/blocks/gnt_trac_pro_report/models/reportitems and then the default report item will be auto-magically overridden by your new file.
Additionally, instead of using PHP server side data, you also might be interested to add some data from the client side using javascript. To do that you can send a javascript code from the report item directly into the page, and the Trac Pro ticket framework will handle the rest.
Here is a practical example:
-
-
-
class MyJSReportItem extends ReportItem
-
{
-
public function heading()
-
{
-
// return a string providing the heading
-
// used in the edit dialog :
-
return t("My JS Important Stuffs");
-
}
-
-
public function description()
-
{
-
// return a long description string
-
// used in the edit dialog :
-
return t("Fetch all js project important data");
-
}
-
-
public function hasJSInspection() { return true; }
-
-
protected function _compute()
-
{
-
$this->addSection( 'mysectionid', t('My JS Section') );
-
$this->setData( 'mysectionid', 'mydatahandle', 'dummy value', t('Value Heading') );
-
}
-
-
protected function _jsInspectionCode( $jsName )
-
{
-
$code = 'report.setData("mysectionid", "mydatahandle", "my-value");'
-
. 'report.save();';
-
return $code;
-
}
-
}
-
-
}
-
First you need to declare your report item as containing javascript data, this is done by defining the hasJSInspection() (line 21) method to return true. After that point, you return the javascript code directly from the _jsInspectionCode() method (line 29). (the $jsName parameter is the id of the js report storage to use, and can be ignored for most cases).
Finally, you need to declare the sections and variable in the _compute method to make them available as defaults in the defaults attribute selection dialog.
The javascript code will be executed in a closure after the document is fully loaded. A report variable will be created for you that report object contains the following methods:
- addSection( sectionID, sectionName ): To add a section to the current report (optional)
- setData( sectionID, valueID, value, valueName ): to set a data in the report under the sectionID created before
- save(): sends the report via JSON to the server, ready to be used in the ticket
The sectionName and valueName can be omitted in you defined it in the _compute method. In case you actually add it in the javascript code, the new name will replace the one defined in _compute method.
This simple API allows you to create any data from the client using javascript, and retrieve any data you would need.
Adding a custom value source
Fields defaults are obtained from different sources. From the Trac Pro New Ticket edit interface you can select where this default value is coming from in the tab.
In the same way you could add a report item in your site override or within a package, you can add a value source type in your site override or in a package.
To add a value source type into a package you are creating, create the following directory :
your_site/blocks/gnt_trac_pro_report/models/valuesources
To add a value source type into a package you are creating, create the following directory :
your_package/models/gnt_trac_pro_report/valuesources
Within the created directory, create a file with the named after the report item you want, for instance my_stuff.php. Now in that file, you will need to define a class inheriting from ValueSource named after your file name (camel-cased) and suffixed with ValueSource. Following our example, if the file is named my_source.php then the class should be MySourceValueSource
Here is what such a class could look like :
<?php defined('C5_EXECUTE') or die('Access Denied.'); class MySourceValueSource extends ValueSource { public function name() { // returns the name used in the source list return t("My source name"); } public function id() { // return a unique ID (integer) for your source // it must be greater than // ValueSource::SOURCE_CUSTOM (or self::SOURCE_CUSTOM) return self::SOURCE_CUSTOM + 42; } public function value() { // fetch and return the value return 'my value'; } }
Here is complete example of a custom value source (shipped with the package in models/valuesources/randow.php):
<?php defined('C5_EXECUTE') or die('Access Denied.'); /** *-----------------------------------------------------------------------------* * This ValueSource is given as a simple example on how to create your own * * tickets value source (used to automatically fill in ticket attributes) * * * * License: Concrete5 marketplace : * * https://marketplace.concretecms.com/help/legal/commercial_add-on_license/ * * * * @author (Florian Delizy) * * * * Copyright(C) 2014 Florian Delizy <florian.delizy@gmail.com> * *-----------------------------------------------------------------------------* */ class RandomValueSource extends ValueSource { // Custom name for your value source : public function name() { return t('Random Number'); } // assign yourself a unique id, this id must // be greater than self::SOURCE_CUSTOM public function id() { return self::SOURCE_RANDOM; } // retrieve and return the value itself public function value() { return rand(); } } // vim: set noexpandtab ts=4 :
Support
If you need any assistance regarding this addon, please use the support forum directly.
In case you need a new feature, or anything else, feel free to contact us threw concrete5 PM system, or contact us directly.