CFIELD_PLACE_DETAILS
CFIELD_PLACE_DETAILS
SimpleDesk API
Navigation
Search
\
Constants
Functions
scheduled_simpledesk()
scheduled_simpledesk()
Placeholder for calling the scheduled maintenance functions.
All scheduled tasks have to have the name prefix scheduled_ and must be defined by the time we get to running AutoTask() in Scheduled.php. Short of modifying that file, we can define a placeholder here (which will exist for AutoTask) and have that be called.
shd_admin_action_log()
shd_admin_action_log()
Initialises the helpdesk action log.
This function loads the language strings, and hands off to shd_load_action_log_entries() to perform the actual log generation.
Before doing so, however, this function will also prepare for deletion of old entries, as well as sorting out the columns and ordering rules before handing control to the other function.
shd_admin_cf_change_types()
shd_admin_cf_change_types(mixed $from_type) : array
This function takes a given type of field and indicates what possible types it could be changed to afterwards.
Parameters
| mixed | $from_type | One of the CFIELD_TYPE constants to indicate the type of field. Alternatively, can be boolean false to return a list of all known types. |
Returns
array —An array of CFIELD_TYPE constants indicating the possible field types it can be turned into.
shd_admin_info()
shd_admin_info()
Loads the main SimpleDesk information page for forum administrators.
This function is the main focus point for information about SimpleDesk in the admin panel, primarily it collects the following for the template:
- list of helpdesk staff
- totals of tickets in the system (open/closed/deleted)
- credits
- also, in the template, whether this is a current or outdated version of SimpleDesk
Since 1.1, it also receives the requests for subactions for action log and support page (since these are sub menu items) but simply directs them onward.
shd_admin_log()
shd_admin_log(string $action, array $extra)
Logs a change in our admin area.
Parameters
| string | $action | The area this was from. |
| array | $extra | An array of extra elements, in the following format. (required) string $action The action performed. (optional) string $setting During a setting update, this is the variable we changed. (optional) string $type The subaction peformed or during a setting update, int/string/etc. (optional) int $id The ID of the item we performed the action on. (optional) string $direction During a reorder up/down operation which way we moved. (optional) int $to The ID of the destination item used during copy/move operation. (optional) int $from The ID of the source item used during the copy/move operation |
shd_admin_main()
shd_admin_main()
The start point for all interaction with the SimpleDesk administration area.
Enforces that users attempting to access the area have either forum or helpdesk administrative privileges, loads the SimpleDesk administrative CSS and Javascript and promptly directs users to the specific function for the task they are performing.
shd_admin_options()
shd_admin_options(boolean $return_config) : null|array
Configuration options and save functions generally for SimpleDesk.
This function handles all the sub areas under General Options, and adds the options listed in the relevant functions. In 1.0, all the options were stored in here, but in 1.1 they have been moved into their own functions.
Parameters
| boolean | $return_config | Whether to return configuration items or not |
Returns
null|array —If $return_config is true, An array of options, otherwise this falls into to SMF's generic settings handler.
shd_admin_smf_perms()
shd_admin_smf_perms( $permissionGroups, $permissionList, $leftPermissionGroups, $hiddenPermissions, $relabelPermissions)
Perform any processing on SMF permissions subject to SimpleDesk options (namely removing permissions that make no sense in helpdesk-only mode)
All of the parameters are the normal variables provided by ManagePermissions.php to its integration hook.
Parameters
| $permissionGroups | ||
| $permissionList | ||
| $leftPermissionGroups | ||
| $hiddenPermissions | ||
| $relabelPermissions |
shd_ajax()
shd_ajax()
Receives AJAX requests and facilitates replying to them.
This function sets up and calls the AJAX handlers; it is the primary receiver for action=helpdesk;sa=ajax.
Primarily, it expects $context['ajax_return'] to be populated as an array of tags to be returned as XML items to the user, with this element being a key-value pair (e.g. $context['ajax_return']['message'] = 'Success!') to be returned as a literal tag, element message, value of Success!, wrapped in the character data block.
An AJAX handler function may also return content in $context['ajax_raw'], this is when the function has prepared its own XML block to return. In such an instance, this function simply outputs the xml headers and assumes the return value is otherwise value.
For example, if the error subarray is populated (['error'] = 'Insufficient permission'), the XML block will contain a tag called error, with a CDATA block containing 'Insufficient permission'.
shd_ajax_assign()
shd_ajax_assign() : array
Returns the list of possible assignees for a ticket for AJAX assignment purposes.
Operations:
- Session check
- Permissions check (that you can assign a ticket to someone else); if you can't assign a ticket to someone else, bail.
- Get the list of information for a ticket (which implicitly checks ticket access); if you can't see the ticket, bail.
- Get the list of who can be assigned a ticket.
- Return that via AJAX.
Returns
array —Response data for Ajax. @since 1.0
shd_ajax_assign2()
shd_ajax_assign2() : array
Action a new assignment via AJAX.
Operations:
- Session check
- Permissions check (that you can assign a ticket to someone else); if you can't assign a ticket to someone else, bail.
- Get the list of information for a ticket (which implicitly checks ticket access); if you can't see the ticket, bail.
- Get the list of who can be assigned a ticket; if requested user not on that list, bail.
- Update and build return status, and return via AJAX.
Returns
array —Response data for Ajax. @since 1.0
shd_ajax_canned()
shd_ajax_canned() : array
Collects a canned reply from the database and serves it via XML for insertion.
Operations:
- Session check; failing in a regular fashion (as opposed to normal return since we're using ;xml in the URL; the SMF handler can deal with that)
- Checks for a department number in the URL, validates access to that department then queries for the requested template.
- Call un_preparsecode to remove extraneous sanity encoding.
- Convert to SMF style BBC-to-HTML if using WYSIWYG
- Do other XML sanitising
- Return via $context['ajax_raw'] for shd_ajax() to output
Returns
array —Response data for Ajax. @since 2.0
shd_ajax_privacy()
shd_ajax_privacy() : array
Handles AJAX updates to privacy.
Receives a request via ?action=helpdesk;sa=ajax;op=privacy to flip the privacy setting.
Operations:
- silent session check; if fail, add to $context['ajax_return']['error']
- ticket id check; if fail, add to $context['ajax_return']['error']
- get enough ticket data to do this
- check if the ticket is not able to be updated (either is closed/deleted, or insufficient permissions); if fail add to $context['ajax_return']['error']
- switch privacy, update database
- clear the cache of tickets for the Helpdesk menu item
- return $context['ajax_return']['message'] as the new privacy item
Returns
array —Response data for Ajax. @since 1.0
shd_ajax_quote()
shd_ajax_quote() : array
Collects ticket post data for quoting posts through AJAX (i.e. inserting a quote live into the postbox)
Operations:
- Session check; failing in a regular fashion (as opposed to normal return since we're using ;xml in the URL; the SMF handler can deal with that)
- If a message id is provided, query for it. If not found (or not provided), die, otherwise continue.
- Call un_preparsecode to remove extraneous sanity encoding.
- Build the [quote] bbcode around the post body.
- Convert to SMF style BBC-to-HTML if using WYSIWYG
- Do other XML sanitising
- Return via $context['ajax_raw'] for shd_ajax() to output
Returns
array —Response data for Ajax. @since 1.0
shd_ajax_urgency()
shd_ajax_urgency() : array
Handles AJAX updates to ticket urgency.
Receives request through ?action=helpdesk;sa=ajax;op=urgency;change=x where x is increase or decrease.
Operations:
- silent session check; if fail, add to $context['ajax_return']['error']
- ticket id check; if fail, add to $context['ajax_return']['error']
- get enough ticket data to do this
- check permissions with shd_can_alter_urgency() and permissions; if fail, add to $context['ajax_return']['error']
- identify whether the new urgency needs 'urgent' styling or not and put the new urgency in $context['ajax_return']['message']
- update the database with the new urgency
- identify whether the new urgency continues to allow the current user to change urgency or not
- put the button links if appropriate into $context['ajax_return']['increase'] and $context['ajax_return']['decrease'] and return
Returns
array —Response data for Ajax. @since 1.0
shd_ajax_urgencylist()
shd_ajax_urgencylist() : array
Handles AJAX updates to ticket urgency list.
Operations:
- silent session check; if fail, add to $context['ajax_return']['error']
- ticket id check; if fail, add to $context['ajax_return']['error']
- get enough ticket data to do this
- check permissions with shd_can_alter_urgency() and permissions; if fail, add to $context['ajax_return']['error']
- identify whether the new urgency needs 'urgent' styling or not and put the new urgency in $context['ajax_return']['message']
- update the database with the new urgency
- identify whether the new urgency continues to allow the current user to change urgency or not
- put the button links if appropriate into $context['ajax_return']['increase'] and $context['ajax_return']['decrease'] and return
Returns
array —Response data for Ajax. @since 2.1
shd_allowed_to()
shd_allowed_to(mixed $permission, integer|boolean $dept) : boolean|array
Determines if a user has a given permission within the system.
All SimpleDesk-specific permissions should be checked with this function. Any other permission check that is not specifically SimpleDesk-related should use allowedTo instead.
Prior to 1.0, this function was in Subs-SimpleDesk.php
Parameters
| mixed | $permission | A string or array of strings naming a permission or permissions that wish to be examined. Array format is only supported if $dept is not identical to false. |
| integer|boolean | $dept | Normally, the department number which the permission is considered for. Can also be 0 to indicate whether the user has that permission in any department, or false to indicate that it should return a list of all the departments where that permission is available. |
Returns
boolean|array —True if any of the permission(s) outlined in $permission are true in the department(s) identified, or an array indicating the departments applicable for that permission if $dept is true boolean 'false'.
shd_append_custom_fields()
shd_append_custom_fields( $body, integer $id_msg, integer $type)
Processes the custom fields for making them part of the body of the new post.
Expects $context['custom_fields'] to have been prepared already in shd_tickettotopic2()
Parameters
| $body | ||
| integer | $id_msg | The message id to consider, or in the case of the ticket's opening post, the ticket id. |
| integer | $type | Should contain either CFIELD_TICKET or CFIELD_REPLY to confirm whether we are looking at the ticket or the post. |
shd_assign()
shd_assign()
Sets up the assignment UI and invokes the template.
This validates that the user can see the ticket in question initially, before determining the level of assignment that can be carried out.
Users who can assign any ticket cause a query to trigger to identify users who have shd_staff permission (and thus can be the target of assignment) and the template is loaded with a dropdown to provide this choice to the user.
Users who can only assign to themselves will at this point have the ticket assigned to them if it was unassigned before, or unassigned from them if they are able to assign tickets to themselves in the first place; if it was assigned to someone else, they will not have the option.
Access through action=helpdesk;sa=assign;ticket=x;sessvar=sessid before redirecting back to the ticket, or add ;home to the URL to have it redirect back to the home page (passed through to the form for shd_assign2()'s use too)
shd_assign2()
shd_assign2()
Handles the actual assignment form, validates it and carries it out.
Primarily this is just about receiving the form, making the same checks that shd_assign() does and then logging the action before passing over to shd_commit_assignment() to actually assign the ticket.
shd_can_alter_urgency()
shd_can_alter_urgency(integer $urgency, boolean $ticket_starter, boolean $closed, boolean $deleted, $dept)
Determines if the current user can raise/lower the urgency of a ticket.
This function identifies whether the current user can raise or lower the urgency of a ticket based on the current urgency of the ticket and whether it is their ticket; this is used in the ticket display as well as the actions linked directly to modifying urgency (both AJAXively and non AJAXively)
Parameters
| integer | $urgency | The current urgency of a ticket as an integer |
| boolean | $ticket_starter | Whether the user in question is the starter of the ticket (instead of querying to establish that, that detail should already be known to the calling function) |
| boolean | $closed | Whether the ticket is currently closed or not |
| boolean | $deleted | Whether the ticket is currently closed or not |
| $dept |
shd_clear_active_tickets()
shd_clear_active_tickets(integer $dept)
Clears the cache of active tickets for the menu item.
shd_get_active_tickets() generates the number of active tickets for the user display, and caches it for 180 seconds normally. This function clears the cache and should be called whenever any operation modifies the state of a ticket.
Parameters
| integer | $dept | The department that is being affected by this change. Users who cannot see this department will not be affected. |
shd_commit_assignment()
shd_commit_assignment(integer $ticket, integer $assignment, $is_ajax = false)
Actually commits a ticket assignment to the database.
This function sets up the relevant options before handing over to shd_modify_ticket_post() which is the preferred way to modify tickets generally. No permissions check is performed here.
Relies on $context['shd_return_to'] to have been set, defaults to 'ticket' to return to ticket, otherwise return to home page on value of 'home'.
Parameters
| integer | $ticket | Ticket id number, assumed to exist. |
| integer | $assignment | User id of the user to which this ticket will be assigned; can be 0 to unassign a ticket |
| $is_ajax |
shd_count_action_log_entries()
shd_count_action_log_entries(string $clause = '') : integer
Returns the total number of items in the helpdesk log.
This function gets the total number of items logged in the helpdesk log, for the purposes of establishing the number of pages there should be in the page-index.
Parameters
| string | $clause | An SQL fragment that forms a WHERE clause to limit log items, e.g. to load a specific ticket or specific member's log items. |
Returns
integer —Number of entries in the helpdesk action log table.
shd_count_admin_log_entries()
shd_count_admin_log_entries() : integer
Returns the total number of items in the helpdesk admin log.
This function gets the total number of items logged in the helpdesk admin log, for the purposes of establishing the number of pages there should be in the page-index.
Returns
integer —Number of entries in the helpdesk action log table.
shd_count_helpdesk_tickets()
shd_count_helpdesk_tickets(string $status = '', boolean $is_staff = false) : integer
Queries the database to find the number of applicable tickets
This function collects counts for the different states of tickets (new, with staff, with user, etc) of all the tickets visible to the user, and returns a selection of that dataset based on the values provided to $status and $is_staff.
Parameters
| string | $status | The relevant count of tickets to return:
|
| boolean | $is_staff | If the user in question is staff or not. |
Returns
integer —Number of applicable tickets.
shd_create_ticket_post()
shd_create_ticket_post( $msgOptions, $ticketOptions, $posterOptions) : boolean
Creates a new ticket or reply in the database.
This function handles all of the creation of posts and tickets within SimpleDesk, even with respect to managing tickets spawned from forum topics being moved. New tickets' contents as well as replies to tickets generally hold the same format.
All three parameters are by reference meaning they WILL be updated if things change. Note that this function is not validating that they are sensible values; it is up to the calling function to ascertain that.
Parameters
| $msgOptions | ||
| $ticketOptions | ||
| $posterOptions |
Returns
boolean —True on success, false on failure.
shd_db_query()
shd_db_query(string $identifier, string $db_string, array $db_values = array(), resource|null $connection = null) : resource
Query wrapper around $smcFunc['db_query'] for helpdesk specific operations.
This function provides a basic wrapper around SMF's internal $smcFunc['db_query'] function, adding the parameter {query_see_ticket} to it, specifically so that ticket visibility can be enforced in a query without being aware of the specific rules for the user.
If not previously loaded, user permissions are loaded with shd_load_user_perms().
Parameters
| string | $identifier | SMF-style query identifier for database backend-specific replacements |
| string | $db_string | Standard SMF 2.0 style database query, including {query_see_ticket} if appropriate |
| array | $db_values | Standard SMF 2.0 style hash map of parameters to inject into the query |
| resource|null | $connection | A database connection variable, if supplied, to override the one used by SMF by default |
Returns
resource —Standard database query resource, suitable for processing with other $smcFunc['db_*'] functions
shd_determine_status()
shd_determine_status(string $action, integer $starter_id, integer $replier_id, integer $replies = -1, $dept = -1) : integer
Establishes the next change of status of a ticket.
Tickets invariably have multiple changes of status during their life. All actions that could change a ticket's status should call here, even if it is a straight forward, one-route-only change of status since it is possible we could end up giving the user a choice one day over how statuses work, so we should route everything through here all the time.
Parameters
| string | $action | (required), represents the action carried out by the calling function Known values: new, resolve, unresolve, deleteticket, restoreticket, deletereply, restorereply, reply, topictoticket (new is default) |
| integer | $starter_id | Numeric id of the ticket's starter (should be provided) |
| integer | $replier_id | Numeric id of the ticket's last reply author (should be provided) |
| integer | $replies | Number of replies in the ticket (should be provided) |
| $dept |
Returns
integer —Returns an integer value that corresponds to the ticket's status, relating to one of the TICKET_STATUS states.
shd_display_btn_mvtopic()
shd_display_btn_mvtopic( $normal_buttons)
Adds the button to the thread view for moving topics into the helpdesk, if appropriate.
This explicitly relies on the display template hook for such things. If the theme does not provide it, the theme author needs to update their theme.
Parameters
| $normal_buttons |
shd_display_load_attachments()
shd_display_load_attachments() : null|array
Loads data on all the attachments that will be displayed in a ticket's view.
Queries the {db_prefix}helpdesk_attachments table for the current ticket, or the messages that will be displayed (previously identified by shd_view_ticket()) and loads the id, name and size of them for display purposes. Differentiation between "attach to ticket" and "attach to reply" is made here; the data is loaded differently depending on the context; "attach to ticket" is simply loaded into an indexed array stored in $context['ticket_attach']['ticket'], while "attach to reply" is loaded into an indexed array subset in $context['ticket_attach']['reply'][msg_id] to retain the association.
Returns
null|array —Builds an array within $contxt['ticket_attach'], as noted above. The individual data items per attachment are:
- id: Numeric id for attachment itself
- name: HTML sanitised name of the attachment's filename
- size: string listing the size of the attachment, converted to kilobytes and rounded to two decimal places
- byte_size: integer of raw size of attachment
- href: the URL that would be used to access the attachment (required $context['ticket_id'] to be available, which it would anyway)
- link: full HTML "a" element linking to the attachment, using the filename as the link text and (since 1.1) with icon img element
shd_done_posting()
shd_done_posting()
Redirects the user once a ticket has been posted or replied to.
Commits the action log entry for what the user has done (since 1.1), then directs the user based on where they were and what was selected:
- if 'return to ticket' was not selected, return to the front page
- if it was, and we edited a reply, return to the reply
- if it was select, but it was a new topic/reply, return just to the topic itself
shd_fatal_error()
shd_fatal_error(string $error, string|boolean $log = 'general', integer $status = 500)
SimpleDesk Fatal Error handler.
Works the same way as SMF, but allows customizing and overriding.
Parameters
| string | $error | The error message |
| string|boolean | $log | = 'general' What type of error to log this as (false to not log it)) |
| integer | $status | The HTTP status code associated with this error |
shd_format_text()
shd_format_text(string $text, boolean $smileys = true, string $cache = '') : string
Formats a string for bbcode and/or smileys.
Formatting is done according to the supplied settings and the master administration settings.
Parameters
| string | $text | Raw text with optional bbcode formatting |
| boolean | $smileys | Whether smileys should be used; this is not an override to the master administration setting of whether to use smileys or not, and that takes precedence. |
| string | $cache | If specified, this will provide the cache'd id that SMF should use to cache the output if it is suitably large. |
Returns
string —Will return $text as processed for bbcode (if $modSettings['shd_allow_ticket_bbc'] permits) and smileys (if $modSettings['shd_allow_ticket_smileys'] and $smileys permits)
shd_get_active_tickets()
shd_get_active_tickets() : string
Defines the helpdesk menu item, including the number of active tickets to be displayed to the user.
Identifies the number of tickets that a user might be interested in, and generates the menu text for the main menu to include this; note that the value should be cached through SMF's functions. The cache is also clearable, through the shd_clear_active_tickets() function.
Returns
string —A formatted string containing the language-specific version of "Helpdesk [x]" menu item with the x in bold
shd_get_block_columns()
shd_get_block_columns(string $block) : array
Return the list of columns that is applicable to a given block.
In order to centralise the list of actions to be displayed in a block, and in its counterpart that displays all the values, the lists of columns per block is kept here.
Parameters
| string | $block | The block we are calling from:
|
Returns
array —An indexed array of the columns in the order they should be displayed as the key. Value contains the width of the column.
shd_get_possible_assignees()
shd_get_possible_assignees(boolean $private = false, integer $ticket_owner, integer $dept = -1) : array
Return a list of possible users that can be assigned a ticket.
This function centralises who a ticket can be assigned to. Currently this is:
- user with shd_staff permission
- can see "any" ticket (not just their own)
- additionally, if the ticket is private, the user must also be able to see 'any' private ticket.
- additionally, check whether user is staff + ticket starter, and then whether we should block them from being assigned
- (since 1.1) additionally if we have set the option, which users are true admins, and if so, remove them from the list too
Parameters
| boolean | $private | Whether the ticket in question is private or not. |
| integer | $ticket_owner | User id of the ticket owner |
| integer | $dept | The department of the ticket, used for establishing permissions. |
Returns
array —An indexed array of member ids that this ticket could be assigned to.
shd_get_urgency_options()
shd_get_urgency_options(boolean $self_ticket = false, $dept)
Identifies the range of options that a user could have for ticket urgency and updates $context['ticket_form'] accordingly.
Ticket urgency permissions are checked, and an array is built suitable for $context['ticket_form'], which is the principle format used in the ticket posting/reply posting functions in SimpleDesk-Post.php.
There is no return function; $context['ticket_form']['urgency'] is updated, both the ['options'] and ['can_change'] keys may be modified.
Parameters
| boolean | $self_ticket | (default false) Permissions will be different for many users depending on whether it is one of their own tickets or not. This allows the code to state whether it is a ticket owned by the current user or not. |
| $dept |
shd_get_visible_list()
shd_get_visible_list(integer $dept, boolean $private, integer $ticket_starter, boolean $include_admin = true, boolean $include_current_user = false) : array
Returns a list of all the possible people that would want notification, that can see the ticket we're interested in.
Parameters
| integer | $dept | The department the given ticket is in. |
| boolean | $private | Whether the given ticket is private or not. |
| integer | $ticket_starter | User id of the ticket starter. |
| boolean | $include_admin | If false, exclude forum admins from the list of possible candidates. |
| boolean | $include_current_user | If true, exclude the current user from the list of possible candidates. |
Returns
array —An array of user ids of the staff members (and ticket starter) that can see tickets, matching the given criteria of department, privacy and permissions.
shd_groups_allowed_to()
shd_groups_allowed_to(string $permission, integer $dept) : array
Identifies which SMF membergroups hold a given permission.
Parameters
| string | $permission | A string naming a permission that members should hold. |
| integer | $dept | An integer indicating which department should be checked. If only confirmation that the user has the permission in at least one department without reference to any particular department, specify a department of 0. |
Returns
array —Array of arrays containing 'allowed' and 'denied', each of which can contain ids for zero or more membergroups that hold the relevant permission.
shd_hash()
shd_hash(string $string) : string
Creates our hash. Due to the way floats can be used, we can safely store an integer equal to 2^52 in a float, so we'll use this. It should be relatively free from avalanching.
Theoretically, a 32 bit hash (a la CRC32) would be suitable if it didn't have the collision incidence factor it does, so we have to do it this way. If we didn't permit prefix matching it would probably be suitable, actually.
Parameters
| string | $string | The string to take the hash of. |
Returns
string —$hash The 52 bit number as a string to prevent it being mashed by any more formatting.
shd_helpdesk_listing()
shd_helpdesk_listing()
Gather the data and prepare to display the ticket blocks.
Actually performs the queries to get data for each block, subject to the parameters specified by the calling functions.
It also sets up per-block pagination links, collects a variety of data (enough to populate all the columns as listed in shd_main_helpdesk, even if not entirely applicable, and populates it all into $context['ticket_blocks']['tickets'], extending the array that was already there.
shd_image_url()
shd_image_url(string $filename) : string
Generate an image URL given the base filename.
As of 2.0, images can live either in the main Themes/default/images/simpledesk folder, or additionally in Themes/default/images/sd_plugins, the latter of which is intended for plugins (the former is removed on SD uninstall, the latter is not)
It should only be used in cases where there is ambiguity over where the image may live, e.g. preferences, permissions UIs. If there is no ambiguity (e.g. SD core, or plugins themselves, where they know where the image will be referenced from), it is recommended to avoid this function.
Parameters
| string | $filename | An image filename, e.g. image.png |
Returns
string —A full URL to the image in question, e.g. http://www.example.com/Themes/default/images/sd_plugins/image.png
shd_init()
shd_init()
Initialises key values for SimpleDesk.
This function initialises certain key constructs for SimpleDesk, such as constants, that are used throughout SimpleDesk. It should be called first right up in Load.php anyway.
Calling multiple times is not significantly detrimental to performance; the function is aware if it has been called previously.
shd_is_allowed_to()
shd_is_allowed_to(mixed $permission, integer $dept)
Enforces a user having a given permission and returning to a fatal error message if not.
All fatal-level SimpleDesk-specific permissions should be checked with this function. Any other permission check that is not specifically SimpleDesk-related should use isAllowedTo instead. Note that this is a void function because should this fail, SMF execution will be halted.
Prior to 1.0, this function was in Subs-SimpleDesk.php
Parameters
| mixed | $permission | A string or array of strings naming a permission or permissions that wish to be examined. |
| integer | $dept | A number indicating a department that the user must the permission in, or 0 for not caring which department provided the user has that permission in at least one department. |
shd_list_get_files()
shd_list_get_files(integer $start, integer $items_per_page, string $sort, string $browse_type) : array
Retrieves the total number of attachments.
Parameters
| integer | $start | The starting position in the query. |
| integer | $items_per_page | The number of attachments per page to show. |
| string | $sort | A valid sort action as determined by our main function |
| string | $browse_type | shd_thumb if a thumbnail otherwise shd_attach. |
Returns
array —Attachment data.
shd_list_get_ip_message_count()
shd_list_get_ip_message_count(string $where, array $where_vars = array()) : integer
Returns the number of helpdesk replies found for track ip.
Parameters
| string | $where | a valid SQL WHERE options for filtering data. |
| array | $where_vars | Valid options to be passed to $smcFunc. |
Returns
integer —A total count of helpdesk replies matching the WHERE filter.
shd_load_action_log_entries()
shd_load_action_log_entries(integer $start, integer $items_per_page = 10, string $sort = 'la.log_time', string $order = 'DESC', string $clause = '') : array
Load the items from the helpdesk action log
It is subject to given parameters (start, number of items, order/sorting), parses the language strings and adds the parameter information provided.
Parameters
| integer | $start | Number of items into the log to start (for pagination). If -1, return everything. If nothing is given, fall back to 0, i.e the first log item. |
| integer | $items_per_page | How many items to load. Default to 10 items. |
| string | $sort | SQL clause to state which column(s) to order the data by. By default it orders by log_time. |
| string | $order | SQL clause to state whether the order is ascending or descending. Defaults to descending. |
| string | $clause | An SQL fragment that forms a WHERE clause to limit log items, e.g. to load a specific ticket or specific member's log items. |
Returns
array —A hash array of the log items, with the auto-incremented id being the key:
- id: Numeric identifier of the log item
- time: Formatted time of the event (as per usual for SMF, formatted for user's timezone)
- member: hash array:
- id: Id of the user that committed the action
- name: Name of the user
- link: Link to the profile of the user that committed the action
- ip: User IP address recorded when the action was carried out
- group: Name of the group of the user (uses primary group, failing that post count group)
- action: Raw name of the action (for use with collecting the image later)
- id_ticket: Numeric id of the ticket this action refers to
- id_msg: Numeric id of the individual reply this action refers to
- extra: Array of extra parameters for the log action
- action_text: Formatted text of the log item (parsed with parameters)
shd_load_admin_log_entries()
shd_load_admin_log_entries(integer $start, integer $items_per_page = 10, string $sort = 'la.log_time', string $order = 'DESC') : array
Load the items from the helpdesk action log
It is subject to given parameters (start, number of items, order/sorting), parses the language strings and adds the parameter information provided.
Parameters
| integer | $start | Number of items into the log to start (for pagination). If -1, return everything. If nothing is given, fall back to 0, i.e the first log item. |
| integer | $items_per_page | How many items to load. Default to 10 items. |
| string | $sort | SQL clause to state which column(s) to order the data by. By default it orders by log_time. |
| string | $order | SQL clause to state whether the order is ascending or descending. Defaults to descending. |
Returns
array —A hash array of the log items, with the auto-incremented id being the key:
- id: Numeric identifier of the log item
- time: Formatted time of the event (as per usual for SMF, formatted for user's timezone)
- member: hash array:
- id: Id of the user that committed the action
- name: Name of the user
- link: Link to the profile of the user that committed the action
- ip: User IP address recorded when the action was carried out
- group: Name of the group of the user (uses primary group, failing that post count group)
- action: Raw name of the action (for use with collecting the image later)
- id_ticket: Numeric id of the ticket this action refers to
- id_msg: Numeric id of the individual reply this action refers to
- extra: Array of extra parameters for the log action
- action_text: Formatted text of the log item (parsed with parameters)
shd_load_custom_fields()
shd_load_custom_fields(boolean $is_ticket = true, integer $ticketContext, $dept)
Loads any custom fields that are active
Parameters
| boolean | $is_ticket | (default true) Whether to load custom fields based on editing a ticket or a message. |
| integer | $ticketContext | The appropriate value to load for; if editing a ticket this represents the ticket id, if editing a reply this represents the message id, if empty this is a new instance of either so no need to attempt loading data. |
| $dept |
shd_load_language()
shd_load_language(string $langfile, string $override_lang = '')
Wrapper for loadLanguage to ensure English language files are always loaded regardless of user language settings as a fallback
As of 2.0 RC2, there is detection code in SMF to ensure the Modifications language file is always loaded, but the same detection is not applied to all language files. This ensures it will be for SD files.
Parameters
| string | $langfile | Name of a language file to load, typically SimpleDesk prefixed, though could be used for any SMF language file. |
| string | $override_lang | Name of a language to load as an override, rather than just the user's default. |
shd_load_relationships()
shd_load_relationships( $ticket)
Identifies the tickets related to a given ticket.
Queries the system for all tickets related to the specified (typically current) ticket, subject to current user's permissions, and populates $context.
The function populates $context['relationships_count'] with the number of relationships found, and $context['ticket_relationships'] contains an array of the following keys:
- parent: Current ticket is the parent of the discovered ticket
- child: Current ticket is a child of the discovered ticket
- linked: Current ticket is related to discovered ticket
- duplicated: Curent ticket is a duplicate of discovered ticket
Each of the keyed arrays is an indexed array (each index representing one ticket), of which those are hash arrays containing:
- id: id of the ticket
- display_id: zero padded display id of the ticket
- subject: ticket's name
- status: status of the discovered ticket (numeric)
- status_txt: status of the discovered ticket (textual)
Parameters
| $ticket |
shd_load_ticket()
shd_load_ticket(integer $ticket) : array
Attempts to load a given ticket's data.
This function permission-checks, and throws appropriate errors if no ticket is specified either directly or through URL, or if the ticket is not accessible either through deletion or lack of permissions.
Parameters
| integer | $ticket | The ticket to use; if none is specified, use the one from $_REQUEST['ticket'], which will have been processed into $context['ticket_id'] if it is available. |
Returns
array —A large hash map stating many ticket details
shd_load_user_perms()
shd_load_user_perms()
Defines user permissions, most importantly concerning ticket visibility
Populates specific parameters in $user_info, mostly to add {} abstract variables in $smcFunc['db_query'] data calls. The foremost one of these is {query_see_ticket}, an SQL clause constructed to ensure ticket visibility is maintained given the active user's permission set.
Prior to 1.1 this was in Subs-SimpleDesk.php
shd_load_user_prefs()
shd_load_user_prefs(integer|boolean $user) : array
Load the user preferences for the given user.
Parameters
| integer|boolean | $user | Normally, an int being the user id of the user whose preferences should be attempted to be loaded. If === false, return the list of default prefs (for the pref UI), or if 0 or omitted, load the current user. |
Returns
array —If $user === false, the list of options, their types and default values is returned. Otherwise, return an array of prefs (adjusted for this user)
shd_log_action()
shd_log_action(string $action, array $params, $do_last_update = true)
Adds an action to the helpdesk internal action log.
This function deals with adding items to the action log maintained by the helpdesk.
Parameters
| string | $action | Specifies the name of the action to log, which implies the image and language string (log_$action is the name of the image, and $txt['shdlog$action'] is the string used to express the action, as listed in {@link SimpleDeskLogAction.english.php}. Note that since 1.1, the list of actions is looked up against the options in Admin / Helpdesk / Options / Action Log Options as to whether they should be logged or not |
| array | $params | This is a list of named parameters in a hash array to be used in the language string later. |
| $do_last_update |
shd_main()
shd_main()
Begins SimpleDesk general processing.
Several things are done here, the results of which are unilaterally assumed by all other SimpleDesk functions.
- work out which departments are applicable, and which department we are currently in (as far as possible)
- set up general navigation
- see if the URL or POST data contains a ticket, if so sanitise and store that value
- see if a msg was specified in the URL, if so identify the relevant ticket
- add in the helpdesk CSS file
- identify the sub action to direct them to, then send them on their way.
shd_main_dept()
shd_main_dept()
Sets up viewing the list of departments.
$context['dept_list'] contains the list of departments that the user can see, key/value pair, array is ordered according to the ordering specified in the Departments administration area. The key for $context['dept_list'] is the department's id, with the array content being:
- id_dept - departmental id (numeric)
- dept_name - department's name
- tickets - an array containing three elements, open, closed and assigned - containing the counts thereof for each department for the current user.
- new - boolean whether this department has some new items to be read by the current user
The linktree is also modified to inclue the department list.
shd_main_helpdesk()
shd_main_helpdesk()
Display the main front page, showing tickets waiting for staff, waiting for user feedback and so on.
This function sets up multiple blocks to be shown to users, defines what columns these blocks should have and states the rules to be used in getting the data.
Each block has multiple parameters, and is stated in $context['ticket_blocks']:
- block_icon: which image to use in Themes/default/images/simpledesk for denoting the type of block; filename plus extension
- title: the text string to use as the block's heading
- where: an SQL clause denoting the rule for obtaining the items in this block
- display: whether the block should be processed and prepared for display
- count: the number of items in this block, for pagination; generally should be a call to [shd_count_helpdesk_tickets()](namespaces/default.html#function_shd_count_helpdesk_tickets)
- columns: an array of columns to display in this block, in the order they should be displayed, using the following options, derived from [shd_get_block_columns()](namespaces/default.html#function_shd_get_block_columns):
- ticket_id: the ticket's read status, privacy icon, and id
- ticket_name: name/link to the ticket
- starting_user: profile link to the user who opened the ticket
- replies: number of (visible) replies in the ticket
- allreplies: number of (all) replies in the ticket (includes deleted replies, which 'replies' does not)
- last_reply: the user who last replied
- status: the current ticket's status
- assigned: link to the profile of the user the ticket is assigned to, or 'Unassigned' if not assigned
- urgency: the current ticket's urgency
- updated: time of the last reply in the ticket; states Never if no replies
- actions: icons that may or may not relate to a given ticket; buttons for recycle, delete, unresolve live in this column
- required: whether the block is required to be displayed even if empty
- collapsed: whether the block should be compressed to a header with count of tickets or not (mostly for [shd_view_block()](namespaces/default.html#function_shd_view_block)'s benefit)
This function declares the following blocks:
- Assigned to me (staff only)
- New tickets (staff only)
- Pending with staff (for staff, this is just tickets with that status, for regular users this is both pending staff and new unreplied to tickets)
- Pending with user (both)
shd_members_allowed_to()
shd_members_allowed_to(mixed $permission, integer $dept) : array
Identifies all members who hold a given permission.
Currently lists of staff are generated by users who hold shd_staff permission. This function identifies those users through an internal lookup provided by SMF.
Prior to 1.0, this function was in Subs-SimpleDesk.php
Parameters
| mixed | $permission | A string naming a permission that members should hold. |
| integer | $dept | An integer indicating which department should be checked. If only confirmation that the user has the permission in at least one department without reference to any particular department, specify a department of 0. |
Returns
array —Array of zero or more user ids who hold the stated permission.
shd_modify_actionlog_options()
shd_modify_actionlog_options(boolean $return_config) : array
Provides configuration options for the action log.
- 'shd_disable_action_log' (checkbox) - if checked, no actions are added to the action log.
- 'shd_display_ticket_logs' (checkbox) - if checked, a ticket's specific log is displayed at the foot of the ticket.
- 'shd_logopt_newposts' (checkbox) - if checked, a ticket's being creation and subsequent replies will be logged.
- 'shd_logopt_editposts' (checkbox) - if checked, a ticket or its replies being edited will be logged.
- 'shd_logopt_resolve' (checkbox) - if checked, a ticket's being closed and/or reopened will be logged.
- 'shd_logopt_autoclose' (checkbox) - if checked, tickets being closed by the helpdesk due to age will be logged.
- 'shd_logopt_assign' (checkbox) - if checked, a ticket being assigned/reassigned/unassigned will be logged.
- 'shd_logopt_privacy' (checkbox) - if checked, ticket privacy changes will be logged.
- 'shd_logopt_urgency' (checkbox) - if checked, ticket urgency changes will be logged.
- 'shd_logopt_tickettopicmove' (checkbox) - if checked, ticket to topic moves and back will be logged.
- 'shd_logopt_cfchanges' (checkbox) - if checked, changes to custom fields will be logged.
- 'shd_logopt_delete' (checkbox) - if checked, ticket/reply deletions (not permadelete) will be logged.
- 'shd_logopt_restore' (checkbox) - if checked, ticket/reply restores will be logged.
- 'shd_logopt_permadelete' (checkbox) - if checked, permadeletes will be logged.
- 'shd_logopt_relationships' (checkbox) - if checked, ticket relationship changes will be logged.
- 'shd_logopt_move_dept' (checkbox) - if checked, ticket moves between departments will be logged.
- 'shd_logopt_monitor' (checkbox) - if checked, users adding/removing tickets to/from their monitor lists will be logged.
Parameters
| boolean | $return_config | Whether to return configuration items or not; this is provided solely for SMF ACP compatibility (it expects to pass bool true in to get a list of options) |
Returns
array —An array of items that make up the search options on the given admin page, each item is itself an array of (type, option name/language string, [other related information])
shd_modify_admin_options()
shd_modify_admin_options(boolean $return_config) : array
General administrative options for SimpleDesk.
- 'shd_maintenance_mode' (checkbox) - if checked, only forum adminstrators (group 1) and helpdesk admins can see the helpdesk
- 'shd_staff_ticket_self' (checkbox) - if checked, a ticket opened by a staff member can be assigned to them to action.
- 'shd_admins_not_assignable' (checkbox) - if checked, forum admins are not considered part of staff - a ticket cannot be assigned to them and they can't receive one-off notifications (since 2.0 only)
- 'shd_privacy_display' (dropdown) - whether to display privacy or not:
- smart (default): Display ticket privacy if it's likely to be relevant (if users can alter ticket privacy, and/or see private tickets AND the ticket is private, show it)
- always: Always display ticket privacy; likely to be confusing
- 'shd_disable_tickettotopic' (checkbox) - if checked, ticket to topic mode is entirely disabled.
- 'shd_disable_relationships' (checkbox) - if checked, relationships are entirely disabled.
Parameters
| boolean | $return_config | Whether to return configuration items or not; this is provided solely for SMF ACP compatibility (it expects to pass bool true in to get a list of options) |
Returns
array —An array of items that make up the search options on the given admin page, each item is itself an array of (type, option name/language string, [other related information])
shd_modify_display_options()
shd_modify_display_options(boolean $return_config) : array
Sets up display options for SimpleDesk.
- 'shd_staff_badge' (dropdown) - selects the type of badge(s) to display:
- nobadge (default): Display no badges, just a small staff icon for staff members
- staffbadge: Display nothing for normal users, and badge/stars for staff
- userbadge: Display nothing for staff and normal badge/staff for regular users
- bothbadge: Display regular badges/stars for both staff and users
- 'shd_display_avatar' (checkbox) - whether to display avatars in the replies area or not
- 'shd_ticketnav_style' (dropdown) - selects the type of navigation in the ticket area:
- sd (default): use the original SimpleDesk style, icons+text in the bar just above the main ticket area
- sdcompact: use the SimpleDesk icons, in the bar just above the main ticket area, but no captions
- smf: use an SMF style button-strip above the ticket menu
- 'shd_theme' (dropdown) - selects the theme id to be used in the helpdesk, or 0 for the forum default
- 'shd_hidemenuitem' (checkbox) - whether to show or hide the menu item, typically used with multiple departments
- 'shd_disable_unread' (checkbox) - if checked, the integration of outstanding helpdesk tickets into the unread page is disabled
Parameters
| boolean | $return_config | Whether to return configuration items or not; this is provided solely for SMF ACP compatibility (it expects to pass bool true in to get a list of options) |
Returns
array —An array of items that make up the search options on the given admin page, each item is itself an array of (type, option name/language string, [other related information])
shd_modify_notifications_options()
shd_modify_notifications_options(boolean $return_config) : array
Displays notifications options within SD ACP / Options / Notifications
- 'shd_notify_email' (text) - if specified, an email address to set as the reply-to address on any email notifications
- 'shd_notify_log' (checkbox) - if checked, a log will be kept of outgoing notification
- 'shd_notify_with_body' (checkbox) - if checked, the outgoing emails will have the email body where appropriate
- 'shd_notify_new_ticket' (checkbox) - if checked, staff have the option of being notified when a new ticket is posted
- 'shd_notify_new_reply_own' (checkbox) - if checked, users have the option to have notifications upon reply to any ticket they started
- 'shd_notify_new_reply_assigned' (checkbox) - if checked, staff have the option to select notifications upon reply to any ticket assigned to them
- 'shd_notify_new_reply_previous' (checkbox) - if checked, staff have the option to select notifications upon reply to any ticket they already replied to
- 'shd_notify_new_reply_any' (checkbox) - if checked, staff have the option to select notifications upon any reply to any ticket they can see
- 'shd_notify_assign_me' (checkbox) - if checked, staff have the option to have notifications sent to them when tickets are assigned to them
- 'shd_notify_assign_own' (checkbox) - if checked, users have the option to be notified when one of their tickets is assigned to a staff member
Parameters
| boolean | $return_config | Whether to return configuration items or not; this is provided solely for SMF ACP compatibility (it expects to pass bool true in to get a list of options) |
Returns
array —An array of items that make up the search options on the given admin page, each item is itself an array of (type, option name/language string, [other related information])
shd_modify_posting_options()
shd_modify_posting_options(boolean $return_config) : array
General posting options for SimpleDesk.
- 'shd_thank_you_post' (checkbox) - if checked, use $txt['shd_ticket_posted_body'] (in SimpleDesk.english.php) as a template of a message to display to the user thanking them for their ticket - and advising what's to come later.
- 'shd_thank_you_nonstaff' (checkbox) - if checked, when the above option is invoked, only display the message to non staff members when they create their tickets.
- 'shd_allow_wikilinks' (checkbox) - enable conversion of [[ticket:123]] into a regular link
- 'shd_allow_ticket_bbc' (checkbox) - one-stop enable/disable of bbcode in tickets (see [shd_format_text()](namespaces/default.html#function_shd_format_text) for where this is used)
- 'shd_allow_ticket_smileys' (checkbox) - one-stop enable/disable of smileys in tickets (see [shd_format_text()](namespaces/default.html#function_shd_format_text) for where this is used)
- 'shd_attachments_mode' (dropdown) - selects the presentation of attachments to users:
- ticket (default): treat attachments as if they are attached to the ticket overall; do not enforce max number per ticket
- reply: treat all attachments as attached to replies; enforce same limit per reply as with posts normally
- 'shd_bbc' (bbc) - enable/disable individual BBC tags around the helpdesk (see [shd_format_text()](namespaces/default.html#function_shd_format_text) for where this is used)
Parameters
| boolean | $return_config | Whether to return configuration items or not; this is provided solely for SMF ACP compatibility (it expects to pass bool true in to get a list of options) |
Returns
array —An array of items that make up the search options on the given admin page, each item is itself an array of (type, option name/language string, [other related information])
shd_modify_standalone_options()
shd_modify_standalone_options(boolean $return_config) : array
Configuration options for Standalone mode.
- 'shd_helpdesk_only' (checkbox) - if checked, Standalone mode is active.
- 'shd_disable_pm' (checkbox) - if checked, personal messages will not be available at all when SimpleDesk is in (active) Standalone mode
- 'shd_disable_mlist' (checkbox) - if checked, the memberlist will not be available at all when SimpleDesk is in (active) Standalone mode
Parameters
| boolean | $return_config | Whether to return configuration items or not; this is provided solely for SMF ACP compatibility (it expects to pass bool true in to get a list of options) |
Returns
array —An array of items that make up the search options on the given admin page, each item is itself an array of (type, option name/language string, [other related information])
shd_modify_ticket_post()
shd_modify_ticket_post( $msgOptions, $ticketOptions, $posterOptions) : boolean
Updates a ticket/reply item in the database.
This function allows modification of all post/ticket details - and can be used independently; it is possible (and even done in SimpleDesk) to update just a ticket or just a post from this function. All three parameters are by reference meaning they WILL be updated if things change. Note that this function is not validating that they are sensible values; it is up to the calling function to ascertain that.
Parameters
| $msgOptions | ||
| $ticketOptions | ||
| $posterOptions |
Returns
boolean —True on success, false on failure.
shd_movedept2()
shd_movedept2()
Handles the actual assignment form, validates it and carries it out.
Primarily this is just about receiving the form, making the same checks that shd_movedept() does and then logging the action before updating the database.
shd_no_expand_pageindex()
shd_no_expand_pageindex(string $base_url, $start, integer $max_value, integer $num_per_page, boolean $flexible_start = false) : string
Wrapper function for constructPageIndex to forcibly block the extensible .
.. item in page indexes
SimpleDesk uses SMF's core page index function in numerous places, but unlike SMF, it often places it in containers that have backgrounds driven by menu_block.png, meaning that they are often fixed in height. Under some circumstances layout can be broken, so this function forcibly ensures the block can never expand to force wrapping.
Parameters
| string | $base_url | Form of URL pageindex links should take, using $1%d to represent the start point identifier. |
| $start | ||
| integer | $max_value | Number of items in total to paginate for. |
| integer | $num_per_page | Number of items to be shown on a page. |
| boolean | $flexible_start | Whether a more flexible % option is to be used in the base URL. |
Returns
string —The constructed page index, without Javascript expander(s).
shd_parse_wikilinks()
shd_parse_wikilinks( $message, $smileys = array(), array $cache_id = array(), array $parse_tags = array())
Processes the incoming message for wiki-links.
Parameters
| $message | ||
| $smileys | ||
| array | $cache_id | Cache ids used by messages, currently not used. |
| array | $parse_tags | Tags to parse, currently not used. |
shd_postbox()
shd_postbox(string $id, string $message, array $buttons, string|integer $width = '90%')
Sets up the post box for tuckets
Parameters
| string | $id | The id of the post box |
| string | $message | The message for the post box |
| array | $buttons | Buttons on the post box |
| string|integer | $width | (optional) The width of the post box, can use percents, ems, px, etc. |
shd_prepare_ticket_context()
shd_prepare_ticket_context() : mixed
Callback function for the template to load messages.
The process set up by shd_view_ticket() and invoked within template_view_replies() is reasonably complex. shd_view_ticket() identifies what messages should be displayed on the current page of the ticket, and performs a query to load the ticket data. Instead, however, of retrieving every row directly into memory before passing to the template, it passes the query result, and the name of a handler function into $context, so the template can call to get an individual row at a time, which saves memory amongst other things.
With respect to shd_view_ticket(), the relevant items are $reply_request being defined and $context['get_replies'] being defined as the name of this function, and in \template_view_replies(), the reference is $reply = $context['get_replies']()
Returns
mixed —The function returns the "next" message reply's details, or simply false if no replies were available, or no further replies are available. Assuming a reply can be returned, it will be a hash array in the following format:
- id: numeric message id
- member: hash array containing details of the poster; normally the return value from SMF's loadMemberContext() function. A minimal set of details is prepared if the poster holds no current SMF account. Common values:
- name: User's name (falls back to the poster name specified in the replies table)
- id: User's id
- group: Name of the assigned group/post count group of the user
- link: HTML for a hyperlink to their profile
- email: Email address of the poster
- ip: IP address of the poster
- body: censored, parsed for smileys and bbcode (in {@link shd_format_text()})
- time: string of the time the reply was posted
- timestamp: internal stored timestamp attached to the reply
- is_staff: boolean value of whether the posting member is currently helpdesk staff
- can_edit: boolean value reflecting if this reply can be edited
- can_delete: boolean value reflecting if this reply can be deleted
- can_restore: boolean value reflecting if this reply can be restored
- ip_address: IP address used to post the message (not necessarily the user's normal IP address); if the user has moderate_forum_members permission, this returns a link to the track IP area, with the IP address as the link text, alternatively simply the IP address if not (is only displayed to helpdesk staff)
- modified: may not be declared, if it is, the message was modified some time after posting, and the following data items are in the hash array within:
- id: user id who edited the reply (not always available)
- time: formatted string of the time the post was edited
- timestamp: raw timestamp of the time the post was edited
- name: user name of the editing user; if we have a definite user id, this should contain the current name, falling back to the previously stored name
- link: if we have a known, valid user id for the post's editor, this will contain a link to their profile, with the link text using their current display name; alternatively it will contain a regular string which is the username stored with the edit.
shd_privacy_change_noajax()
shd_privacy_change_noajax()
Marks a ticket private/not private if the user isn't using Javascript.
Assuming the user can see the ticket and has suitable permissions, the privacy flag will be inverted for the ticket and updated, as well as updating the action log. If they cannot see the ticket, or do not have privacy-change permission, a fatal error will be generated.
Accessed through ?action=helpdesk;sa=privacychange;ticket=x;sessvar=sessid before directing back to the ticket page.
shd_profile_link()
shd_profile_link(string $name, integer $id) : string
Generates a profile link given user id and name.
SMF itself has loadMemberData() and loadMemberContext to perform this act, however those two functions are much larger and more complex than we need more often than not, especially when all we want/need is member name (and subsequently profile link)
Since profile links should be based on the view profile permission, we will need to establish that.
Parameters
| string | $name | The name to display. This should be a standard SMF type name, which means already sanitised for HTML. |
| integer | $id | The numeric id of the user we are linking to. |
Returns
string —Returns an HTML link to user profile if sufficient permission and both a name and id are supplied. Otherwise just the name is.
shd_recalc_ids()
shd_recalc_ids(integer $ticket) : array
Clean up tickets that have been modified by replies being altered through restore, delete, and possibly other operations.
Operations:
- Identify how many deleted and non deleted replies there are in the ticket.
- Identify the last non deleted reply in the ticket (if there are no undeleted replies, use the ticket post itself for cohesion)
- Update the ticket's record with the first and last posters, as well as the correct number of active and deleted replies, and whether there are any deleted replies on the ticket generally
Prior to SimpleDesk 1.1, this function was located in Sources/SimpleDesk-Delete.php.
Parameters
| integer | $ticket | The ticket id to recalculate. |
Returns
array —An array detailing the user id of the starter, the last replier and the number of active replies in a ticket.
shd_search_charset()
shd_search_charset() : array
Identify and return the character set parameters for searching.
Returns
array —An array of two items, the overall character set currently in use and the list of characters to be permitted in searches in the form of a regular expression character class.
shd_ticket_delete()
shd_ticket_delete()
Delete the given ticket, i.e move it to the recycling bin.
Accessed through ?action=helpdesk;sa=deleteticket;ticket=x;sessvar=sessid
Operations:
- Session check
- Check there's a ticket id
- Check the ticket exists and is visible to the current user
- Check permission to delete ticket matches (i.e. can delete any, or can delete own and this is one of ours)
- Update the ticket's status to deleted
- Log the deletion
- Clear the menu's Helpdesk active items cache
- return to the front page
shd_ticket_on_hold()
shd_ticket_on_hold(boolean $on_hold = false, $ticketOptions) : boolean
Set a ticket to on hold or restore to the proper status.
Parameters
| boolean | $on_hold | (default true) Whether this ticket should be on hold or not. |
| $ticketOptions |
Returns
boolean —True on success, false on failure.
shd_ticket_relation()
shd_ticket_relation()
Updates a ticket's relationships.
This function is responsible for adding, updating and removing relationships.
Accessed through ?action=helpdesk;sa=relation;ticket=x;linkticket=y;relation=[linked|duplicated|parent|child|delete];sessvar=sessid and will redirect back to the ticket once complete.
shd_ticket_resolve()
shd_ticket_resolve()
Marks a ticket resolved or unresolved.
This function identifies whether a given ticket is resolved or not, if not resolved, mark it resolved. If it was resolved reopen the ticket back to an appropriate status based on last respondent. In both cases, the action is logged in the action log. It is also unassigned from having a user on either closure or reopen.
Accessed through ?action=helpdesk;sa=resolve;ticket=x;sessvar=sessid before redirecting back to the ticket, or add ;home to the URL to have it redirect back to the home page.
shd_ticket_unread()
shd_ticket_unread()
Marks a ticket unread.
There are no permission checks made; other than that the user is who they claim to be. If a ticket is marked unread but they can't see it anyway, the consequence is that the database gets lighter.
Invoked through ?action=helpdesk;sa=unreadticket;ticket=x;sessvar=sessid before redirecting back to the main helpdesk page.
shd_tickettotopic2()
shd_tickettotopic2()
Receives the form for moving tickets to topics, and actually handles the move.
After checking permissions, and so on, begin to actually move posts.
This is done by invoking SMF's createPost function to make the new thread and repost all the ticket's posts as new thread posts using defaults for some settings.
Operations:
- check the user can see the board they are linking to
- move the ticket's text as the opening post
- update the ticket row if the post was modified before
- get the rest of the replies
- step through and post, updating for modified details
- send the notification PM if we're doing that
- update the attachments table
- update the action log
- remove the ticket from the DB
shd_topictoticket()
shd_topictoticket()
Load the form up for asking users whether to send a personal message (and what message) to the topic/ticket starter or not. Most of the rest of this function is about loading the data to make the page well-rounded (like the subject for breadcrumbs)
Validates the user permission and session, of course.
Accessed through action=helpdesk;sa=topictoticket;topic=x;sessvar=sessid
shd_topictoticket2()
shd_topictoticket2()
Handles moving a topic into the helpdesk.
After checking permissions, and so on, begin to actually move posts.
Broadly this is done using shd_create_ticket_post(), which has hooks specifically to deal with post modification times (written in specifically to ease this function's workload)
Operations:
- get the topic information (and checking topic access permission in the process)
- identify the status of the topic (new/with staff/with user)
- create the new ticket from these details
- assuming there are replies, query for them
- step through and repost
- send the notification PM if we're doing that
- update the attachments table
- update the action log
- remove the topic from the forum
shd_unregister_plugin()
shd_unregister_plugin()
Unregister a plugin, to be called from plugin uninstallers.
Expects $context['uninstall_plugin'] to have been defined, as an array with up to four keys:
- 'name' as a string of the plugin's name (required)
- 'sources' as an array of files to be purged from source file loaders (e.g. SDPluginMymod.php)
- 'languages' as an array of files to be purged from language loaders (e.g. SDPluginMymod)
- 'functions' as an array of functions to be purged from function calls (e.g. shd_mymod_helpdesk, shd_mymod_adminopts)
shd_urgency_change_noajax()
shd_urgency_change_noajax()
Updates a ticket's urgency up or down one level, if the user isn't using Javascript
Assuming the user can see the ticket and has suitable permissions, the urgency of the ticket will be updated and an action log entry added. If they cannot see the ticket, or do not have urgency-change permission (including higher urgency permission if necessary), a fatal error will be generated.
Accessed through ?action=helpdesk;sa=urgencychange;ticket=x;change=(increase|decrease);sessvar=sessid before directing back to the main helpdesk page.
shd_view_ticket()
shd_view_ticket()
Loads all the data and sets all the options for displaying a ticket.
This function does a lot of work in setting up a ticket to be displayed:
- Invokes shd_load_ticket() to get the principle data
- Creates $context['ticket'] to hold the data block, some of which is derived from the return of shd_load_ticket():
- id: regular numeric ticket id
- display_id: zero padded ticket id (e.g. 00001)
- subject: censored version of the subject
- first_msg: id of the opening post that forms the ticket body
- body: formatted (parsed for smileys and bbcode) version of the ticket post
- id_member: user id of the ticket's poster
- id_member_assigned: user id of the ticket's assigned user
- member: hash array of the ticket poster's details:
- id: their user id
- name: the name stated in the ticket post for that use
- link: link to the profile of the user
- assigned: hash array of the assignee of the ticket:
- id: their user id
- name: name of the assignee, or 'Unassigned'
- link: a full HTML link to their profile, or 'Unassigned' in red text
- assigned_self: boolean, whether the ticket is assigned to the current user or not
- ticket_opener: boolean, whether the current user is the user who opened this ticket
- urgency: hash array
- level: numeric identifier of current ticket urgency
- label: the HTML label of the urgency, including being in red for "Very High" or above
- increase: Boolean, whether the current ticket urgency can be increased given the current ticket state and user permissions
- decrease: Boolean, whether the current ticket urgency can be increased given the current ticket state and user permissions
- status: hash array
- level: numeric, current status identifier
- label: string representing the current status
- num_replies: the number of replies to the ticket so far
- deleted_replies: how many deleted replies in this ticket
- poster_time: formatted string containing the time the ticket was opened
- privacy: hash array
- label: current label to be used with the privacy item
- can_change: Boolean, whether the user's permission with this ticket allows us to edit the ticket privacy
- closed: Boolean, represents whether this ticket is closed (used a lot with the navigation menu)
- deleted: Boolean, represents whether this ticket is deleted (used a lot with the navigation menu)
- ip_address: IP address logged at the time the ticket was opened; if moderate_forum_members permission is available, this will be a link to the track IP area
- modified: if the ticket has been modified, also get the modified details:
- id: user id who edited the ticket (not always available)
- time: formatted string of the time the post was edited
- timestamp: raw timestamp of the time the post was edited
- name: user name of the editing user; if we have a definite user id, this should contain the current name, falling back to the previously stored name
- link: if we have a known, valid user id for the post's editor, this will contain a link to their profile, with the link text using their current display name; alternatively it will contain a regular string which is the username stored with the edit.
- display_recycle: Either holds the $txt identifier of the message to apply as a warning, or false if displaying of recycling stuff in this ticket isn't appropriate (either for permissions or just because of no deleted replies, or we're just in regular ticket view)
- define the page index with SMF's constructPageIndex
- query for all the ids of messages we might display, followed by querying for the message details themselves, pushing that query resource to $reply_request so we can use it in shd_view_replies() later
- load details of all the users applicable for posts in this page
- request all the visible attachments from [shd_display_load_attachments()](namespaces/default.html#function_shd_display_load_attachments)
- since we are viewing this ticket, mark it read
- set up the breadcrumb trail
- set up the ticket navigation menu
- call in the editor component from SimpleDesk-Post.php and friends, ready for Quick Reply
- invoke the different Javascript objects that are applicable on the page:
- privacy changer
- urgency changer
- quick reply / quote / go advanced
ssi_getSDTickets()
ssi_getSDTickets(string $query_where, array $query_where_params = array(), integer $query_limit, string $query_order = 'hdt.id_ticket ASC', $output_method = 'echo') : null|array
Gets tickets based on supplied criteria; this is a helper function not really intended to be called directly.
Parameters
| string | $query_where | SQL clauses to be supplied to the query in addition to {query_see_ticket} - note 'AND' is not required at the start. |
| array | $query_where_params | Key/value associative array to be injected into the query, related to $query_where. |
| integer | $query_limit | Number of items to limit the query to. |
| string | $query_order | The clause to order tickets by, defaults to tickets by order of creation. |
| $output_method |
Returns
null|array —An array of arrays, each primary item containing the following:
- id: Main ticket id
- display_id: Formatted ticket id in [0000x] format
- subject: Ticket subject
- short_subject: Shortened version of ticket subject
- href: Ticket href
- opener: array of details about the ticket starter:
- id: user id of the person who opened the ticket
- name: username of the person who opened the ticket
- link: link to the profile of the person who opened the ticket
- replier: array of details about the last person to reply to the ticket:
- id: user id of the last person to reply to the ticket
- name: username of the last person to reply to the ticket
- link: link to the profile of the last person to reply to the ticket
- assigned: array of details about the person who the ticket is assigned to:
- id: user id of the person who the ticket is assigned to
- name: username of the person who the ticket is assigned to or 'Unassigned' otherwise
- link: link to the profile of the person who the ticket is assigned to or 'Unassigned' otherwise
- num_replies: Number of replies in the ticket
- start_time: Formatted string of time the ticket was opened
- start_timestamp: Raw timestamp (adjusted for timezones) of ticket being opened
- last_time: Formatted string of time the ticket was last replied to
- last_timestamp: Raw timestamp (adjusted for timezones) of ticket's last reply
- private: Whether the ticket is private or not
- urgency_id: Number representing ticket urgency
- urgency_string: String representing ticket urgency
- status_id: Number representing ticket status
- status_text: String representing ticket status
- department: Number representing ticket department ID
ssi_staffAssignedTickets()
ssi_staffAssignedTickets(integer $assignee, integer|array $dept = array(), integer $limit = 10, string $output_method = 'echo') : null|array
Gets a list of the tickets currently open that are assigned to the current user (presumably staff, subject to ticket visibility).
Parameters
| integer | $assignee | The user id whose tickets whose assigned tickets you want to examine, defaults to the current user. |
| integer|array | $dept | An array of department ids whose tickets you want to examine, defaults to all departments. |
| integer | $limit | The number of tickets to limit to, default 10. |
| string | $output_method | Set to 'echo' for displaying content, set to 'array' to simply return data. |
Returns
null|array —An array of data, more details under the underlying function {@link ssi_getSDTickets()}
ssi_staffMembers()
ssi_staffMembers(boolean $honour_admin_setting = true, string $output_method = 'echo') : array
Gets a list of all staff members within the helpdesk.
Parameters
| boolean | $honour_admin_setting | Within the administration panel is the option to exclude forum admins from being considered staff (so can't assign tickets to them). If true (default), assume the outcome of that should be applied here too. |
| string | $output_method | Leave as default or explicitly set to 'echo' for this function to output a list of helpdesk staff members, set to 'array' to block output, and have the standard contents back. |
Returns
array —The return is always an array of members that are staff; contains many details about members since SMF's member context is loaded (including avatar, personal text and so on)
ssi_staffTicketsUrgency()
ssi_staffTicketsUrgency(integer $urgency, integer|array $dept = array(), integer $limit = 10, string $output_method = 'echo') : null|array
Gets a list of all tickets based on urgency criteria given (subject to ticket visibility)
Parameters
| integer | $urgency | The urgency of tickets you want to get. |
| integer|array | $dept | An array of department ids whose tickets you want to examine, defaults to all departments. |
| integer | $limit | The number of tickets to limit to, default 10. |
| string | $output_method | Set to 'echo' for displaying content, set to 'array' to simply return data. |
Returns
null|array —An array of data, more details under the underlying function {@link ssi_getSDTickets()}
ssi_userTickets()
ssi_userTickets(integer $started_by, array|integer $dept = array(), integer $limit = 10, string $output_method = 'echo') : null|array
Gets a list of the tickets currently open that are a given user's (subject to ticket visibility).
Parameters
| integer | $started_by | The user id whose tickets you want to examine, defaults to the current user. |
| array|integer | $dept | An array of department ids whose tickets you want to examine, defaults to all departments. |
| integer | $limit | The number of tickets to limit to, default 10. |
| string | $output_method | Set to 'echo' for displaying content, set to 'array' to simply return data. |
Returns
null|array —An array of data, more details under the underlying function {@link ssi_getSDTickets()}
template_assign()
template_assign()
Displays the list of possible users a ticket can have assigned.
Will have been populated by shd_assign() in SimpleDesk-Assign.php, adding into $context['member_list'].
This allows users to assign tickets to other users, or themselves, or to unassign a previously assigned ticket. Future versions will likely add further options here.
template_closedtickets()
template_closedtickets()
Display the helpdesk view of resolved tickets.
This function steps through the blocks defined in SimpleDesk.php to display all the block of closed items.
All the blocks here are defined in shd_closed_tickets() and data gathered in shd_helpdesk_listing().
template_main()
template_main()
Display the main helpdesk view of active tickets.
This function steps through the blocks defined in SimpleDesk.php to display all the blocks that potentially would be visible, noting whether blocks have been collapsed or not, and calling to the sub-subtemplates to output collapsed and noncollapsed blocks.
All the blocks here are defined in shd_main_helpdesk() (or shd_view_block() if viewing a single block) and data gathered in shd_helpdesk_listing().
template_quickreply()
template_quickreply()
Displays the quick reply/go advanced box
This function handles displaying of the templates that make up the Quick Reply / Go Advanced area, drawing on \SimpleDesk-Post.template.php for core posting templates.
Prior to 1.1 this was part of template_viewticket()
template_recyclebin()
template_recyclebin()
Display the helpdesk view of recycled and partly recycled tickets.
This function steps through the blocks defined in SimpleDesk.php to display all the blocks that would be related; the list of deleted tickets, and the list of tickets with deleted replies in.
All the blocks here are defined in shd_recycle_bin() and data gathered in shd_helpdesk_listing().
template_shd_action_log()
template_shd_action_log()
Display the action log.
Little real work is done in this template; mostly is just iterating through the already-processed contents of the action log as done by shd_admin_action_log().
template_shd_admin()
template_shd_admin()
Display the main information center for the administration panel.
This function handles output of data populated by shd_admin_info():
- upgraded SD version advisory
- latest news from SimpleDesk.net
- basic version check
- count of open/closed/recycled tickets in the helpdesk in total
- list of current helpdesk staff
- credits
template_shd_admin_log()
template_shd_admin_log()
Display the action log.
Little real work is done in this template; mostly is just iterating through the already-processed contents of the action log as done by shd_admin_action_log().
template_shd_display_nojs_above()
template_shd_display_nojs_above()
Displays a header that Javascript should be enabled while in the administration panel area of SimpleDesk.
The helpdesk is disabled to non admins while in maintenance mode, but this template is added to the template layers if the user is an admin and it's in maintenance mode.
template_shd_display_nojs_below()
template_shd_display_nojs_below()
Displays a footer that Javascript should be enabled while in the administration panel area of SimpleDesk.
This template is added to the template layers, because SMF requires a layer have both a layer before and after the main content.
template_shd_maintenance_above()
template_shd_maintenance_above()
Displays a header to admins while the helpdesk is in maintenance mode.
The helpdesk is disabled to non admins while in maintenance mode, but this template is added to the template layers if the user is an admin and it's in maintenance mode.
template_shd_maintenance_below()
template_shd_maintenance_below()
Displays a footer to admins while the helpdesk is in maintenance mode.
The helpdesk is disabled to non admins while in maintenance mode, but this template is added to the template layers if the user is an admin and it's in maintenance mode.
template_shd_menu_header()
template_shd_menu_header(string $header, string $string) : string
Makes a menu header clickable/sortable.
Within the ticket blocks, it is possible to sort the blocks by column, and do so in a way that is retained as you manipulate individual blocks. Since this is transient (not pushed to the database) it needs to be recorded in the URL over time.
Parameters
| string | $header | The identifier of the header to use here; related to {@link shd_helpdesk_listing()} |
| string | $string | The text string to use as the header text |
Returns
string —The fully formed HTML fragment for the link, text and hint image
template_shd_nojs_above()
template_shd_nojs_above()
Displays a header that Javascript should be enabled while in the administration panel area of SimpleDesk.
The helpdesk is disabled to non admins while in maintenance mode, but this template is added to the template layers if the user is an admin and it's in maintenance mode.
template_shd_post_nojs_above()
template_shd_post_nojs_above()
Displays a header that Javascript should be enabled while in the administration panel area of SimpleDesk.
The helpdesk is disabled to non admins while in maintenance mode, but this template is added to the template layers if the user is an admin and it's in maintenance mode.
template_shd_show_settings()
template_shd_show_settings()
Display options as set up by the options functions.
This is a modified version of the standard SMF template for displaying settings, mostly so we have access to a custom BBC template.
In short, SMF's functions call the relevant function in \SimpleDesk-Admin.php to gather which options should be displayed, store in $context, then pass it here.
The same template services all of the defined areas inside Admin: SimpleDesk: Options.
template_shd_tickettotopic()
template_shd_tickettotopic()
Display a list of requirements for moving a ticket to a topic.
When moving a ticket to the forum, certain information is required: the board to move to, whether to send the ticket starter a personal message (and if so, the contents of the message) and what to do in the event there are deleted replies to deal with. This function handles showing the form to the user.
template_ticket_block()
template_ticket_block()
Display an individual, non-collapsed block.
Each front-page template uses this function to display a given block of tickets. It handles displaying the menu header, including ticket count, followed by all the different column types as listed in shd_main_helpdesk(), then to iterate through the ticket details to display each row (provided by shd_helpdesk_listing().
template_ticketactionlog()
template_ticketactionlog()
Display the events on a ticket.
Displays all the non-post type events that apply to the current ticket, as a subset of the master action log. Data is gathered from shd_load_action_log_entries()
template_viewreplies()
template_viewreplies()
Display all the replies to a ticket.
This function deals simply with viewing of replies in a ticket, including deleted replies, which is initialised in shd_view_ticket() and data gathered through the shd_prepare_ticket_context() call back, which simply deals with a single reply at a time.
template_viewticket()
template_viewticket()
Display the main view of a ticket.
It is responsible for all the processing and display of the data gathered in shd_view_ticket() to the user, and in fact there is little to discuss other than simply displaying the ticket in given HTML.
It is also responsible for displaying attachments either to the ticket (in attachments-in-ticket mode) or to the first post (in attachments-in-replies mode), and calling upon the posting routines to set up display of 'advanced' mode in quick reply.
template_viewticketattach()
template_viewticketattach()
Display all the attachments to a ticket (in ticket view)
This function displays all the attachments in the current ticket while in ticket view, rather than when in replies view (which is handled by template_viewreplies() instead; this function was previously was part of template_viewticket().