CFIELD_PLACE_DETAILS
CFIELD_PLACE_DETAILS
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()
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(mixed $from_type) : array
This function takes a given type of field and indicates what possible types it could be changed to afterwards.
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. |
An array of CFIELD_TYPE constants indicating the possible field types it can be turned into.
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:
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( $action, array $extra)
Logs a change in our admin area.
$action | ||
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()
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( $return_config)
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.
$return_config |
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.
$permissionGroups | ||
$permissionList | ||
$leftPermissionGroups | ||
$hiddenPermissions | ||
$relabelPermissions |
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()
Returns the list of possible assignees for a ticket for AJAX assignment purposes.
Operations:
shd_ajax_assign2()
Action a new assignment via AJAX.
Operations:
shd_ajax_canned()
Collects a canned reply from the database and serves it via XML for insertion.
Operations:
shd_ajax_privacy()
Handles AJAX updates to privacy.
Receives a request via ?action=helpdesk;sa=ajax;op=privacy to flip the privacy setting.
Operations:
shd_ajax_quote()
Collects ticket post data for quoting posts through AJAX (i.e. inserting a quote live into the postbox)
Operations:
shd_ajax_urgency()
Handles AJAX updates to ticket urgency.
Receives request through ?action=helpdesk;sa=ajax;op=urgency;change=x where x is increase or decrease.
Operations:
shd_allowed_to(mixed $permission, mixed $dept) : boolean
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
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. |
mixed | $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. |
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( $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()
$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()
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()
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(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)
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(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.
integer | $dept | The department that is being affected by this change. Users who cannot see this department will not be affected. |
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'.
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(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.
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. |
Number of entries in the helpdesk action log table.
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.
Number of entries in the helpdesk action log table.
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.
string | $status | The relevant count of tickets to return:
|
boolean | $is_staff | If the user in question is staff or not. |
Number of applicable tickets.
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.
$msgOptions | ||
$ticketOptions | ||
$posterOptions |
True on success, false on failure.
shd_db_query(string $identifier, string $db_string, array $db_values = array(), resource $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().
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 | $connection | A database connection variable, if supplied, to override the one used by SMF by default |
Standard database query resource, suitable for processing with other $smcFunc['db_*'] functions
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.
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 an integer value that corresponds to the ticket's status, relating to one of the TICKET_STATUS states.
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.
$normal_buttons |
shd_display_load_attachments() : 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.
Builds an array within $contxt['ticket_attach'], as noted above. The individual data items per attachment are:
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:
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.
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. |
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() : 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.
A formatted string containing the language-specific version of "Helpdesk [x]" menu item with the x in bold
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.
string | $block | The block we are calling from:
|
An indexed array of the columns in the order they should be displayed.
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:
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. |
An indexed array of member ids that this ticket could be assigned to.
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.
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(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.
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. |
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(string $permission, integer $dept) : array
Identifies which SMF membergroups hold a given permission.
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. |
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(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.
string | $string | The string to take the hash of. |
$hash The 52 bit number as a string to prevent it being mashed by any more formatting.
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(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.
string | $filename | An image filename, e.g. image.png |
A full URL to the image in question, e.g. http://www.example.com/Themes/default/images/sd_plugins/image.png
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(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
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_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.
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. |
A hash array of the log items, with the auto-incremented id being the key:
shd_load_admin_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.
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. |
A hash array of the log items, with the auto-incremented id being the key:
shd_load_custom_fields(boolean $is_ticket = true, integer $ticketContext, $dept)
Loads any custom fields that are active
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(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.
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( $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:
Each of the keyed arrays is an indexed array (each index representing one ticket), of which those are hash arrays containing:
$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.
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. |
A large hash map stating many ticket details
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(mixed $user) : array
Load the user preferences for the given user.
mixed | $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. |
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(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.
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()
Begins SimpleDesk general processing.
Several things are done here, the results of which are unilaterally assumed by all other SimpleDesk functions.
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:
The linktree is also modified to inclue the department list.
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']:
This function declares the following blocks:
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
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. |
Array of zero or more user ids who hold the stated permission.
shd_modify_actionlog_options(boolean $return_config) : array
Provides configuration options for the action log.
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) |
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(boolean $return_config) : array
General administrative options for SimpleDesk.
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) |
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(boolean $return_config) : array
Sets up display options for SimpleDesk.
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) |
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(boolean $return_config) : array
Displays notifications options within SD ACP / Options / Notifications
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) |
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(boolean $return_config) : array
General posting options for SimpleDesk.
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) |
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(boolean $return_config) : array
Configuration options for Standalone mode.
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) |
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( $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.
$msgOptions | ||
$ticketOptions | ||
$posterOptions |
True on success, false on failure.
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(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.
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. |
The constructed page index, without Javascript expander(s).
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']()
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:
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(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.
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 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(integer $ticket) : array
Clean up tickets that have been modified by replies being altered through restore, delete, and possibly other operations.
Operations:
Prior to SimpleDesk 1.1, this function was located in Sources/SimpleDesk-Delete.php.
integer | $ticket | The ticket id to recalculate. |
An array detailing the user id of the starter, the last replier and the number of active replies in a ticket.
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:
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()
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()
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()
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:
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()
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:
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:
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()
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:
ssi_getSDTickets(string $query_where, array $query_where_params = array(), integer $query_limit, string $query_order = 'hdt.id_ticket ASC', $output_method = 'echo') : array
Gets tickets based on supplied criteria; this is a helper function not really intended to be called directly.
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 |
An array of arrays, each primary item containing the following:
ssi_staffAssignedTickets(integer $assignee, $dept = array(), integer $limit = 10, string $output_method = 'echo') : array
Gets a list of the tickets currently open that are assigned to the current user (presumably staff, subject to ticket visibility).
integer | $assignee | The user id whose tickets whose assigned tickets you want to examine, defaults to the current user. @param int $dept An array of department ids whose tickets you want to examine, defaults to all departments. |
$dept | ||
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. |
An array of data, more details under the underlying function {@link ssi_getSDTickets()}
ssi_staffMembers(boolean $honour_admin_setting = true, string $output_method = 'echo') : array
Gets a list of all staff members within the helpdesk.
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. |
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(integer $urgency, $dept = array(), integer $limit = 10, string $output_method = 'echo') : array
Gets a list of all tickets based on urgency criteria given (subject to ticket visibility)
integer | $urgency | The urgency of tickets you want to get. @param int $dept An array of department ids whose tickets you want to examine, defaults to all departments. |
$dept | ||
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. |
An array of data, more details under the underlying function {@link ssi_getSDTickets()}
ssi_userTickets(integer $started_by, $dept = array(), integer $limit = 10, string $output_method = 'echo') : array
Gets a list of the tickets currently open that are a given user's (subject to ticket visibility).
integer | $started_by | The user id whose tickets you want to examine, defaults to the current user. @param int $dept An array of department ids whose tickets you want to examine, defaults to all departments. |
$dept | ||
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. |
An array of data, more details under the underlying function {@link ssi_getSDTickets()}
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()
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()
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()
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()
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()
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()
Display the main information center for the administration panel.
This function handles output of data populated by shd_admin_info():
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()
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()
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()
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()
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(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.
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 |
The fully formed HTML fragment for the link, text and hint image
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()
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()
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()
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()
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()
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()
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()
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()
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().