Documentation
Table of Content
Quick Start
- Install Trac Free on your target website
- Add a Trac Free 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 Free, 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 Free Install button
After installing Trac Free (either through downloading or preferably directly through your concrete5 website interface), you will be provided with the Trac Free New Ticket block.
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).
Creating tickets
New Ticket Block Usage
To allow your users to issue ticket from any page, add the Trac Free New Ticket to the page.
You will first have to fill in the trac server base URL in the trac base URL field. This URL will be used to connect to the trac server in order to create tickets but also in order to detect the ticket system structure.
- Ticket prompt: shows a text
- Show to Guest: make the report link available to non-logged-in users
- Use captcha: require captcha before submitting (spam protection)
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.
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 Free 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.
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 Free 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).
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
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.
Finally, the ticket is actually created when the reporter hits the button. 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:
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.
Support
This addon is a free addon, and does not come with free support. If you have a problem, just post a support request, we will reply when we have some time to do so.