SimpleDesk API v1.0 - Support files - Subs-SimpleDesk
Navigation
Search
This file handles key functions for SimpleDesk that can be called on every page load, such as the custom query function to handle ticket visibility, the counter for active tickets in the menu header, or the action log.
- since: 1.0
shd_db_query(string $identifier, string $db_string, array $db_values = array(), resource $connection = null)
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 {@link}.
- see: \shd_load_user_perms()
- since: 1.0
Parameter: $identifier
Expected type: string
SMF-style query identifier for database backend-specific replacements
Parameter: $db_string
Expected type: string
Standard SMF 2.0 style database query, including {query_see_ticket} if appropriate
Parameter: $db_values
Expected type: array
Default: array()
Standard SMF 2.0 style hash map of parameters to inject into the query
Parameter: $connection
Expected type: resource
Default: null
A database connection variable, if supplied, to override the one used by SMF by default
shd_load_user_perms()
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.
- see: \shd_db_query()
- since: 1.0
shd_get_active_tickets()
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 {@link} function.
- see: \shd_clear_active_tickets()
- since: 1.0
shd_clear_active_tickets(mixed $id)
{@link} 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.
- see: \shd_get_active_tickets()
- since: 1.0
Parameter: $id
Expected type: mixed
shd_log_action(string $action, array $params)
This function deals with adding items to the action log maintained by the helpdesk.
- see: \shd_load_action_log_entries()
- since: 1.0
Parameter: $action
Expected type: string
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['shd_log_$action'] is the string used to express the action, as listed in SimpleDesk-LogAction.english.php.
Parameter: $params
Expected type: array
This is a list of named parameters in a hash array to be used in the language string later.
shd_can_alter_urgency(int $urgency, bool $ticket_starter, bool $closed, bool $deleted)
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)
- see: \shd_urgency_change_noajax()
- since: 1.0
Parameter: $urgency
Expected type: int
The current urgency of a ticket as an integer
Parameter: $ticket_starter
Expected type: bool
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)
Parameter: $closed
Expected type: bool
Whether the ticket is currently closed or not
Parameter: $deleted
Expected type: bool
Whether the ticket is currently closed or not
shd_count_helpdesk_tickets(string $status = '', bool $is_staff = false)
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.
- since: 1.0
Parameter: $status
Expected type: string
Default: ''
The relevant count of tickets to return:
- 'open': All tickets currently open that the user can see
- 'assigned': All tickets assigned to the current user
- 'new': All the new tickets that the user can see
- 'staff': All the tickets currently with staff (varies for staff vs user; user count here includes 'new' tickets)
- 'with_user': All the tickets pending user comment
- 'closed': All the tickets the user can see that are resolved
- 'recycled': All the tickets the user can see that are currently in the recycle bin
- 'withdeleted': All the tickets that have at least one deleted reply
- '' or unspecified: Return the total of all tickets in the helpdesk (subject to visibility)
Parameter: $is_staff
Expected type: bool
Default: false
If the user in question is staff or not.
shd_load_ticket(int $ticket)
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.
- since: 1.0
Parameter: $ticket
Expected type: int
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.
shd_format_text(string $text, bool $smileys = true, string $cache = '')
Formatting is done according to the supplied settings and the master administration settings.
- since: 1.0
Parameter: $text
Expected type: string
Raw text with optional bbcode formatting
Parameter: $smileys
Expected type: bool
Default: true
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.
Parameter: $cache
Expected type: string
Default: ''
If specified, this will provide the cache'd id that SMF should use to cache the output if it is suitably large.
shd_allowed_to(mixed $permission)
All SimpleDesk-specific permissions should be checked with this function. Any other permission check that is not specifically SimpleDesk-related should use allowedTo instead.
- see: \shd_is_allowed_to
- since: 1.0
Parameter: $permission
Expected type: mixed
A string or array of strings naming a permission or permissions that wish to be examined
shd_is_allowed_to(mixed $permission)
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.
- see: \shd_allowed_to
- since: 1.0
Parameter: $permission
Expected type: mixed
A string or array of strings naming a permission or permissions that wish to be examined
shd_members_allowed_to(mixed $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.
- see: \shd_allowed_to
- since: 1.0
Parameter: $permission
Expected type: mixed
A string naming a permission that members should hold.
shd_profile_link(string $name, int $id)
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.
- since: 1.0
Parameter: $name
Expected type: string
The name to display. This should be a standard SMF type name, which means already sanitised for HTML.
Parameter: $id
Expected type: int
The numeric id of the user we are linking to.
shd_determine_status(string $action, int $starter_id, int $replier_id, int $replies = -1)
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.
- since: 1.0
Parameter: $action
Expected type: string
(required), represents the action carried out by the calling function Known values: new, resolve, unresolve, deleteticket, restoreticket, deletereply, restorereply, reply, merge, topictoticket (new is default)
Parameter: $starter_id
Expected type: int
Numeric id of the ticket's starter (should be provided)
Parameter: $replier_id
Expected type: int
Numeric id of the ticket's last reply author (should be provided)
Parameter: $replies
Expected type: int
Default: -1
Number of replies in the ticket (should be provided)
shd_no_expand_pageindex(string $base_url, int $start, int $max_value, int $num_per_page, bool $flexible_start = false)
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.
- since: 1.0
Parameter: $base_url
Expected type: string
Form of URL pageindex links should take, using $1%d to represent the start point identifier.
Parameter: $start
Expected type: int
Position to start. If not a multiple of the number per page, it will be forced to become a multiple.
Parameter: $max_value
Expected type: int
Number of items in total to paginate for.
Parameter: $num_per_page
Expected type: int
Number of items to be shown on a page.
Parameter: $flexible_start
Expected type: bool
Default: false
Whether a more flexible % option is to be used in the base URL.