Skip to content

Contributing

Jump to bottom
ᔕᖺᘎᕊ edited this page Jul 16, 2018 · 13 revisions

Thank you for considering to contribute to SOX!

Please follow the following steps when adding a new feature:

  • Write a function that implements the feature
  • Add it to the bottom of the features object in sox.features.js. It's name should be in camelCase
  • Add the feature to sox.features.info.json. Please put it under the most fitting category (eg. under Appearance). The following fields must be included:
  • name: the camelCase ID of the function you added to sox.features.js
  • desc: a short description of the feature you're adding, which will be displayed in the control panel
  • meta: a URL linking to a meta post if that is where you got the idea from/were trying to fix, or ""
  • match: a string of comma-separated match patterns for URLs where the feature should run on
  • exclude: a string of comma-separated match patterns for URLs where the feature should run on, or ""
  • Any CSS should be added to sox.css, with a comment before it indicating which feature it is for. CSS rules should ideally be prepended with the function ID (the camelCase name).

##Helper functions

SOX has various helper functions and getters you can use to get information:

  • 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(type, id, sitename, filter, callback, sortby): sends a AJAX GET request to the API with the type type with id id (comma seperated if more than one) on site sitename, passing the data back to callback. sortby is optional.

  • sox.helpers.observe(elements, callback, toObserve): sets up a MutationObserver to call callback (passing the mutated elements) if any element in the jQuery elements object is mutated. toObserve is optional and can be used to specify which part of the page to watch for mutations in

  • 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

  • sox.site.href: get the current page's URL

  • sox.site.apiParameter(siteName): get the site parameter for a given siteName (retrieved with sox.site.name)

  • sox.site.CurrentApiParameter(siteName): returns the current site's API parameter

  • 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)

##Testing locally

To test locally, simply create a userscript which //@require's the local version of your files. Here's a template that you can modify to work for your system:

// ==UserScript==
// @name         Local SOX
// @match        *://*.stackoverflow.com/*
// @match        *://*.stackexchange.com/*
// @match        *://*.superuser.com/*
// @match        *://*.serverfault.com/*
// @match        *://*.askubuntu.com/*
// @match        *://*.stackapps.com/*
// @match        *://*.mathoverflow.net/*
// @match        *://github.com/soscripted/*
// @match        *://soscripted.github.io/sox/*
// @exclude      *://data.stackexchange.com/*
// @exclude      *://api.stackexchange.com/*

// @require      https://code.jquery.com/jquery-3.3.1.min.js
// @require      https://code.jquery.com/ui/1.12.1/jquery-ui.min.js
// @require      https://api.stackexchange.com/js/2.0/all.js
// @require      https://cdnjs.cloudflare.com/ajax/libs/jquery-timeago/1.5.3/jquery.timeago.min.js

// @require      file:///C:/User/Github/sox/sox.common.js
// @require      file:///C:/User/Github/sox/sox.github.js
// @require      file:///C:/User/Github/sox/sox.dialog.js
// @require      file:///C:/User/Github/sox/sox.enhanced_editor.js
// @require      file:///C:/User/Github/sox/sox.features.js
// @require      file:///C:/User/Github/sox/sox.user.js

// @resource     css file:///C:/User/Github/sox/sox.css
// @resource     dialog file:///C:/User/Github/sox/sox.dialog.html
// @resource     featuresJSON file:///C:/User/Github/sox/sox.features.info.json
// @resource     common file:///C:/User/Github/sox/sox.common.info.json

// @grant        GM_setValue
// @grant        GM_getValue
// @grant        GM_deleteValue
// @grant        GM_getResourceText
// @grant        GM_addStyle
// @grant        GM_info
// ==/UserScript==

Make sure Tampermonkey/Greasemonkey has been allowed access to local file URLs!

Clone this wiki locally