StackUnderflow.js

<p> Table of Conents <ul> <li><a href="#intro">Introduction</a></li> <li><a href="#using">Getting Started with StackUnderflow.js</a></li> <li> <a href="#api">API Reference</a> <ul> <li><a href="#appId">stackunderflow.appId</a></li> <li><a href="#site">stackunderflow.site</a></li> <li><a href="#loaded">stackunderflow.loaded</a></li> <li><a href="#google">stackunderflow.googleQuestions</a></li> <li><a href="#getQuestions">stackunderflow.getQuestions</a></li> <li><a href="#searchQuestions">stackunderflow.searchQuestions</a></li> <li><a href="#getQuestionsWithTags">stackunderflow.getQuestionsWithTags</a></li> <li><a href="#getQuestionsByUser">stackunderflow.getQuestionsByUser</a></li> <li><a href="#renderQuestions">stackunderflow.render.questions</a></li> </ul> </li> <li><a href="#templating">HTML Templating</a></li> <li><a href="#css">Customizing CSS</a></li> </ul> </p> <div> <img src="http://infinity88.com/stackunderflow/stackunderflow.png" />StackUnderflow </div>

<a name="intro"></a>

<h1>Introduction</h1> <p> StackUnderflow.js is a lightweight JavaScript library that makes retrieving and rendering question summary information from StackExchange sites simple. It supports retrieving questions by Question ID, tags, keyword, and even by Google search results to enable you to search the body of questions, even though the StackExchange API does not support it (currently limited to 8 results). </p> <p> Also, because it is hosted and designed to be easily usable from anywhere, it couldn't be easier to get StackExchange data to display on your own websites. Some awesome examples of this capability: <ul> <li>Display questions that link to your blog.</li> <li>Display questions that link to the current blog article.</li> <li>Display questions related to keyword or tags on a bug tracking site.</li> <li>Display questions related to a feature directly from online documentation for your products.</li> </ul> <p>Here is StackUnderflow.js pulling in questions that link to my blog:</p> <img src="http://infinity88.com/stackunderflow/StackUnderflowScreen.png" alt="" /> </p>

<a name="using"></a>

<h1>Getting Started with StackUnderflow.js</h1> <p> Simply include the script and the default css on your page: <pre> &lt;link type="text/css" rel="Stylesheet" href="http://infinity88.com/stackunderflow/stackoverflow.min.css" /&gt; &lt;script type="text/javascript" src="http://infinity88.com/stackunderflow/stackunderflow-1.0.3.min.js"&gt;&lt;/script&gt; </pre> Then, you can immediately start using the API. It will take care of ensuring the document has fully loaded before rendering anything, should you choose to do that. <pre> &lt;script type="text/javascript"&gt; stackunderflow.getQuestionsWithTags("asp.net;viewstate").render("#results"); &lt;/script&gt; </pre> </p>

<a name="api"></a>

<h1>API Reference</h1> <p> StackUnderflow.js APIs let you search for StackExchange questions using any StackExchange site. You may get the raw data returned from StackExchange to do with what you want, but the real power comes from its render() function, which can render questions in the same familiar summary format you have seen on StackExchange sites already. The look for the rendering is completely customizable, either through CSS, a simple html templating language, or both. By default, the rendering will look like StackOverflow.com, but with your own sites background color. </p>

<a name="appId"></a>

<h2>stackunderflow.appId (optional)</h2> <p> This is a global setting that changes the appId used when querying StackExchange. By default, the key is the appId for StackUnderflow.js. You may wish to set it to your own StackExchange key for tracking and API limit reasons. <pre> stackunderflow.appId = "&lt;my app id&gt;"; </pre> </p>

<a name="site"></a>

<h2>stackunderflow.site (optional)</h2> <p> This is a global setting that sets the StackExchange site to query against. Set it to the home url for the site. For example, the default value is "http://stackoverflow.com". Do not include a trailing slash or any other information. <pre> stackunderflow.site = "http://superuser.com"; </pre> </p>

<a name="loaded"></a>

<h2>stackunderflow.loaded(callback)</h2> <p> Registers a handler that is called when the DOM is loaded, after which it is safe to modify the DOM tree. Note that if the DOM has already loaded, the callback will be executed immediately, but not if the DOM was already loaded when StackUnderflow.js itself was first loaded (advanced scenario that is only important if you are loading StackUnderflow.js dynamically). <pre> stackunderflow.loaded(function() { // do stuff }); </pre> </p>

<a name="google"></a>

<h2>stackunderflow.googleQuestions([optional]term, [optional]complete(questions))</h2> <p> Searches the current StackExchange site with Google for questions containing the given search term, then loads the questions with the StackExchange API. <ul> <li><strong>term</strong> The query to search for. May be of any format you can search Google for, such as with quotes for hard matches on multiple words. If not given, the search term will be equal to the complete current page URL in quotes. This is useful, for example, to find StackExchange questions that link to the current page.</li> <li><strong>complete</strong> A function that is called when the results have been retrieved. A single parameter is given -- an instance of a <a href="http://api.stackoverflow.com/0.9/help/method?method=questions" target="_blank">questions result</a> as defined by the StackExchange API.</li> </ul> The return value is a context object that contains additional methods that operate on the future results. See the section on <i>chaining</i> for details. <pre> stackunderflow.googleQuestions("asp.net viewstate", function(result) { alert(result.questions.length); }); </pre> </p>

<a name="getQuestions"></a>

<h2>stackunderflow.getQuestions(questionIds, [optional]complete(questions))</h2> <p> Retrieves one or more questions from the StackExchange API. <ul> <li><strong>questionIds</strong> A string containing the list of questions to retrieve, or an array of question ids to retrieve multiple questions.</li> <li><strong>complete</strong> A function that is called when the results have been retrieved. A single parameter is given -- an instance of a <a href="http://api.stackoverflow.com/0.9/help/method?method=questions" target="_blank">questions result</a> as defined by the StackExchange API.</li> </ul> The return value is a context object that contains additional methods that operate on the future results. See the section on <i>chaining</i> for details. <pre> stackunderflow.getQuestions([2977508, 2977462], function(result) { alert(result.questions.length); }); </pre> </p>

<a name="searchQuestions"></a>

<h2>stackunderflow.searchQuestions([optional]intitle, [optional]tagged, [optional]notTagged, [optional]complete(questions))</h2> <p> Searches for questions from the StackExchange API. You may search by question title or tags (having or not having). Although the three search term parameters are all optional, you must specify at least one of the tree. <ul> <li><strong>intitle</strong> A string containing the search term to match against question titles.</li> <li><strong>tagged</strong> A semi-colon delimited list of tags. Matching questions must have one or more of the given tags.</li> <li><strong>nottagged</strong> A semi-colon delimited list of tags. Matching questions must not have any of the given tags.</li> <li><strong>complete</strong> A function that is called when the results have been retrieved. A single parameter is given -- an instance of a <a href="http://api.stackoverflow.com/0.9/help/method?method=questions" target="_blank">questions result</a> as defined by the StackExchange API.</li></ul> The return value is a context object that contains additional methods that operate on the future results. See the section on <i>chaining</i> for details. <pre> // find questions tagged 'asp.net' and 'javascript' but NOT 'jquery' stackunderflow.searchQuestions(null, "asp.net;javascript", "jquery", function(result) { alert(result.questions.length); }); </pre> </p>

<a name="getQuestionsWithTags"></a>

<h2>stackunderflow.getQuestionsWithTags(tags, [optional]onlyUnanswered, [optional]complete(questions))</h2> <p> Searches for questions with all the given tags from the StackExchange API. <ul> <li><strong>tags</strong> A semi-colon delimited list of tags. Matching questions must have ALL of the given tags.</li> <li><strong>onlyUnanswered</strong> boolean -- true if you would like to restrict the search to questions with no up-voted answers.</li> <li><strong>complete</strong> A function that is called when the results have been retrieved. A single parameter is given -- an instance of a <a href="http://api.stackoverflow.com/0.9/help/method?method=questions" target="_blank">questions result</a> as defined by the StackExchange API.</li></ul> The return value is a context object that contains additional methods that operate on the future results. See the section on <i>chaining</i> for details. <pre> // find unanswered questions about jQuery stackunderflow.getQuestionsWithTags("jquery", true, function(result) { alert(result.questions.length); }); </pre> </p>

<a name="getQuestionsByUser"></a>

<h2>stackunderflow.getQuestionsByUser(userIds, [optional]complete(questions))</h2> <p> Gets questions asked by the given user(s) by their user IDs. <ul> <li><strong>userIds</strong> A userId, an array of userIds, or a semi-colon delimited list of userIds.</li> <li><strong>complete</strong> A function that is called when the results have been retrieved. A single parameter is given -- an instance of a <a href="http://api.stackoverflow.com/0.9/help/method?method=questions" target="_blank">questions result</a> as defined by the StackExchange API.</li></ul> The return value is a context object that contains additional