Skip to content

Helper Functions

Jump to bottom
Shubham Jain edited this page Jun 4, 2019 · 2 revisions

SOX Helper Functions

Below is a list of all the helper functions SOX provides. Please prefer using these over implementing any of these actions yourself.

If you need help, clarification, or want to discuss any of these functions, please drop a line in the Gitter chat, or make a new issue!

  • sox.debug(message, [message2, message3, ...]): does console.debug to the console, prepended with SOX: . Only logs if user has enabled debugging
  • sox.log(message, [message2, message3, ...]): does console.log, prepended with SOX:
  • sox.warn(message, [message2, message3, ...]): does console.warn, prepended with SOX:
  • sox.error(message, [message2, message3, ...]): does console.error, prepended with SOX:
  • sox.loginfo(message, [message2, message3, ...]): does console.info, prepended with SOX:
  • sox.settings.accessToken: returns the user's access token; you shouldn't need to use this, becaues the sox.helpers.getFromAPI() function (below) should allow you to use the API with the access token itself

  • sox.helpers.getFromAPI(details, callback): sends a AJAX GET request to the API using the details in the details object:

    • endpoint (required): the Stack Exchange API endpoint that you want to query
    • sitename (required): the Stack Exchange site you want to query against (tip: sox.site.url will be the current site's sitename)
    • childEndpoint (optional): the sub-endpoint that you want to query. This is only applicable to some endpoints, such as /posts/{ids}/revisions -- revisions is the childEndpoint in this case
    • ids (optional): a single ID (string or integer), or array of IDs (strings or integers)
    • limit (optional): the maximum page size you want to return (defaults to Stack Exchange's default of 30)
    • filter (optional): the Stack Exchange API filter that you want to use (this is strongly recommended, to reduce load on SE's side and to reduce the size of requests made for users)
    • sort (optional): the attribute you want to sort by (defaults to creation)
    • order (optional): in what order you want to order the sort attribute by (defaults to desc)

    There are some more details keys that you can provide, relating to caching of the API response:

    • useCache (optional): whether you want to cache the results or not (defaults to true)
    • featureId (required if caching is desired): the name of the function that you are calling the method from. This is used to store cached data together with the feature that requested the data (i.e. cached API data cannot be shared with other features)
    • cacheDuration (optional): the number of minutes you want to cache the data for (defaults to 3 minutes)

    The method requests data as required; if some of the ids provided are already cached, it will combine the API response with the cached data.

    The method can be thought of as returning the items array the Stack Exchange API would return (i.e. without the outer object containing details like the quota).

    The data is returned by calling the callback with the data as the single parameter.

  • sox.helpers.observe(targets, elements, callback): sets up a MutationObserver to watch targets and call callback (passing the mutated elements) if it detects an element changing whose selector matches the jQuery selector in the elementsstring.

    • targets (required): a single Element or an array of Elements
    • elements (required): a string containing a jQuery selector that you want to be notified on changes for
    • callback (required): a function that will be called with the mutated element as the single parameter, if a mutation is detected

  • sox.helpers.getIDFromAnchor(anchor): returns the ID from a Stack Exchange link, or null if not found.

  • sox.helpers.getSiteNameFromAnchor(anchor): returns the sitename from a Stack Exchange link, or null if not found.

  • sox.site.id: get the current site ID
  • sox.site.name: get the current site's name
  • sox.site.type: get the current site's type (beta/main/meta/chat)
  • sox.site.url: get the current page's hostname (e.g. meta.stackexchange.com)
  • sox.site.href: get the current page's URL (e.g. https://meta.stackexchange.com/questions/blah/blah)
  • sox.location.on(location): returns true if the current page's URL matches a given location string (internally uses indexOf)
  • sox.location.onUserProfile: returns true if the user is currently on a user profile
  • sox.location.onQuestion: returns true if the user is currently on a question page
  • sox.location.match(matchPattern): returns true if the current page matches a given [matchPattern'](https://developer.chrome.com/extensions/match_patterns). SE1.0` is a special pattern which checks for whether the current site is either Area51 or the main Stack Exchange site.
  • sox.user.id: returns the current user's ID
  • sox.user.rep: returns the current' user's reputation level
  • sox.user.name: returns the current user's username
  • sox.user.loggedIn: returns true if the user is logged in
  • sox.user.hasPrivilege(privilege): returns true if the current user has enough reputation to have a certain privilege (this is a string, and is the privilege name you see on the main privileges page)

Clone this wiki locally