Skip to content
Browse files

Added docs

  • Loading branch information...
1 parent 75adb0a commit c13286a6e8fc59b1e33b754aae3f849b91393625 @auchenberg auchenberg committed May 10, 2012
Showing with 483 additions and 0 deletions.
  1. +44 −0 docs/assets/data.json
  2. +13 −0 docs/assets/example2.js
  3. +35 −0 docs/assets/examples.js
  4. +128 −0 docs/assets/style.css
  5. +263 −0 docs/index.html
View
44 docs/assets/data.json
@@ -0,0 +1,44 @@
+[
+ {
+ "id": 1,
+ "name": "Kenneth Auchenberg",
+ "avatar": "http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif",
+ "type": "contact"
+ },
+ {
+ "id": 2,
+ "name": "Jon Froda",
+ "avatar": "http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif",
+ "type": "contact"
+ },
+ {
+ "id": 3,
+ "name": "Anders Pollas",
+ "avatar": "http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif",
+ "type": "contact"
+ },
+ {
+ "id": 4,
+ "name": "Kasper Hulthin",
+ "avatar": "http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif",
+ "type": "contact"
+ },
+ {
+ "id": 5,
+ "name": "Andreas Haugstrup",
+ "avatar": "http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif",
+ "type": "contact"
+ },
+ {
+ "id": 6,
+ "name": "Pete Lacey",
+ "avatar": "http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif",
+ "type": "contact"
+ },
+ {
+ "id": 7,
+ "name": "kenneth@auchenberg.dk",
+ "avatar": "http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif",
+ "type": "contact"
+ }
+]
View
13 docs/assets/example2.js
@@ -0,0 +1,13 @@
+$(function () {
+
+ $('textarea.mention-example2').mentionsInput({
+ onDataRequest:function (mode, query, callback) {
+ $.getJSON('assets/data.json', function(responseData) {
+ responseData = _.filter(responseData, function(item) { return item.name.toLowerCase().indexOf(query.toLowerCase()) > -1 });
+ callback.call(this, responseData);
+ });
+ }
+
+ });
+
+});
View
35 docs/assets/examples.js
@@ -0,0 +1,35 @@
+$(function () {
+
+ $('textarea.mention').mentionsInput({
+ onDataRequest:function (mode, query, callback) {
+ var data = [
+ { id:1, name:'Kenneth Auchenberg', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
+ { id:2, name:'Jon Froda', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
+ { id:3, name:'Anders Pollas', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
+ { id:4, name:'Kasper Hulthin', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
+ { id:5, name:'Andreas Haugstrup', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
+ { id:6, name:'Pete Lacey', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
+ { id:7, name:'kenneth@auchenberg.dk', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
+ { id:8, name:'Pete Awesome Lacey', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
+ { id:9, name:'Kenneth Hulthin', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' }
+ ];
+
+ data = _.filter(data, function(item) { return item.name.toLowerCase().indexOf(query.toLowerCase()) > -1 });
+
+ callback.call(this, data);
+ }
+ });
+
+ $('.get-syntax-text').click(function() {
+ $('textarea.mention').mentionsInput('val', function(text) {
+ alert(text);
+ });
+ });
+
+ $('.get-mentions').click(function() {
+ $('textarea.mention').mentionsInput('getMentions', function(data) {
+ alert(JSON.stringify(data));
+ });
+ }) ;
+
+});
View
128 docs/assets/style.css
@@ -0,0 +1,128 @@
+body {
+ background: #f6f6f6;
+ color: #192535;
+ font-family: 'pt sans', arial, helvetica, sans-serif;
+ font-size: 16px;
+ margin: 0;
+ padding: 0;
+}
+
+div.container {
+ font-size: 16px;
+ width: 720px;
+ padding: 50px 0 50px 50px;
+}
+
+div.container > p,
+div.container > li,
+div.container > ol {
+ margin: 16px 0 16px 0;
+ width: 550px;
+}
+
+div.examples {
+ width: 560px;
+}
+
+.examples .mentions-input-box {
+ margin-bottom: 10px;
+ font-size: 14px;
+}
+
+.examples .mentions-input-box textarea {
+ font-family: 'pt sans', arial, helvetica, sans-serif;
+ font-size: 14px;
+}
+
+
+a, a:visited {
+ padding: 0 2px;
+ text-decoration: none;
+ background: #eee;
+ color: #00639e;
+}
+
+a:active, a:hover {
+ color: #000;
+ background: #bacada;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ margin-top: 40px;
+ font-weight: normal;
+}
+
+h1 {
+ font-size: 56px;
+}
+
+h2 {
+ font-size: 24px;
+}
+
+b.header {
+ font-size: 18px;
+}
+
+span.alias {
+ font-size: 14px;
+ font-style: italic;
+ margin-left: 20px;
+}
+
+table {
+ margin: 16px 0;
+ padding: 0;
+}
+
+tr, td {
+ margin: 0;
+ padding: 0;
+ vertical-align: top;
+}
+
+td {
+ padding: 9px 15px 9px 0;
+}
+
+td.definition {
+ line-height: 18px;
+ font-size: 14px;
+}
+
+code, pre, tt {
+ font-family: Monaco, Consolas, "Lucida Console", monospace;
+ font-size: 12px;
+ line-height: 18px;
+ color: #294555;
+}
+
+code {
+ margin-left: 20px;
+}
+
+pre {
+ font-size: 12px;
+ padding: 2px 0 2px 12px;
+ border-left: 6px solid #99aabb;
+ margin: 0px 0 30px;
+}
+
+.button {
+ display: inline-block;
+ line-height: 24px;
+ margin-bottom: 4px;
+ font-weight: normal;
+ text-shadow: none;
+ padding: 1px 10px 1px 10px;
+ white-space: nowrap;
+ cursor: pointer;
+
+ border-radius: 5px;
+
+ background: #eaeaea;
+ background: -moz-linear-gradient(top, hsl(0, 0%, 96%), #eaeaea);
+ background: -webkit-gradient(linear, left top, left bottom, from(#f6f6f6), to(#eaeaea));
+ border: 1px solid #dcdcdc;
+ color: #525252;
+}
View
263 docs/index.html
@@ -0,0 +1,263 @@
+<!DOCTYPE HTML>
+<html>
+<head>
+ <title>jquery.mentionsInput</title>
+ <meta http-equiv="content-type" content="text/html;charset=UTF-8"/>
+ <meta http-equiv="X-UA-Compatible" content="chrome=1">
+ <link href='https://fonts.googleapis.com/css?family=PT+Sans&subset=latin' rel='stylesheet' type='text/css'>
+ <link href='assets/style.css' rel='stylesheet' type='text/css'>
+ <link href='../jquery.mentionsInput.css' rel='stylesheet' type='text/css'>
+
+ <script src='https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js' type='text/javascript'></script>
+ <script src='http://documentcloud.github.com/underscore/underscore-min.js' type='text/javascript'></script>
+</head>
+<body>
+
+<div class="container">
+
+<h1>jquery.mentionsInput</h1>
+
+<p>
+ <a>jquery.mentionsInput</a> is a small, but awesome UI component that allows you to "@mention" someone in a text message, just like you are used to on Facebook or Twitter.
+</p>
+
+<p>This project is written by <a href="http://twitter.com/auchenberg">Kenneth Auchenberg</a>, and started as an internal project at <a href="http://podio.com">Podio</a>, but has then been open sourced to give it a life in the community. </p>
+
+<p><a href="https://twitter.com/share" class="twitter-share-button" data-url="http://podio.github.com/jquery-mentions-input/" data-via="auchenberg" data-lang="en">Tweet</a></p>
+
+<h2>Examples</h2>
+
+<p>Basic example (<a href="assets/examples.js">source</a>)</p>
+
+<div class="examples">
+ <textarea class='mention' placeholder='Try to mention me, by typing @ken'></textarea>
+ <a class="button get-syntax-text">Get marked-up value</a>
+ <a class="button get-mentions">Get mentions collection</a>
+</div>
+
+
+<p>AJAX example. (Getting data by AJAX, and filter in callback - <a href="assets/example2.js">source</a>)</p>
+
+<div class="examples">
+ <textarea class='mention-example2' placeholder='Try to mention me, by typing @ken'></textarea>
+</div>
+
+<h2>Download and source</h2>
+<p>You can grab the latest source from the repository on GitHub by clicking here: <a href="https://github.com/podio/jquery-mentions-input">https://github.com/podio/jquery-mentions-input</a>.</p>
+
+<h2>Getting started</h2>
+
+<ol>
+ <li>
+ Add a script reference to jquery.mentionsInput.js:<br/>
+ <pre>&lt;script src=&#39;jquery.mentionsInput.js&#39; type=&#39;text/javascript&#39;&gt;&lt;/script&gt;</pre>
+ </li>
+ <li>
+ Add a bit of markup: <br/>
+ <pre>&lt;textarea class=&#39;mention&#39;&gt;</pre>
+ </li>
+ <li>
+ <p>Initialise the mentionsInput: <br/>
+ <pre>
+$('textarea.mention').mentionsInput({
+ onDataRequest:function (mode, query, callback) {
+ var data = [
+ { id:1, name:'Kenneth Auchenberg', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
+ { id:2, name:'Jon Froda', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
+ { id:3, name:'Anders Pollas', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
+ { id:4, name:'Kasper Hulthin', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
+ { id:5, name:'Andreas Haugstrup', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
+ { id:6, name:'Pete Lacey', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' }
+ ];
+
+ data = _.filter(data, function(item) { return item.name.toLowerCase().indexOf(query.toLowerCase()) > -1 });
+
+ callback.call(this, data);
+ }
+});
+ </pre>
+ </p>
+
+ <p>
+ Bam, you are in business.
+ </p>
+ </li>
+</ol>
+
+<h2>Configuration</h2>
+<p>jquery.mentionsInput does have a number of extra configuration options which you may change to customise the way it behaves.</p>
+
+<p>The meaning of the options and their default values are listed below. </p>
+
+<table>
+ <tr>
+ <td><b>onDataRequest</b></td>
+ <td><tt>function(mode, query, callback)</tt></td>
+ <td class="definition">
+ This function is a callback function which is used to provide data for the autocomplete. When a search starts
+ this function is called with following arguments: 'search', the query (what's been typed), and a callback function which needs to be called inside onDataRequest with a data collection to be searched on as a first argument.
+ </td>
+ </tr>
+ <tr>
+ <td><b>triggerChar</b></td>
+ <td><tt>@</tt></td>
+ <td class="definition">
+ Trigger character which triggers the mentions search, when the character has been typed into the
+ mentions input field.
+ </td>
+ </tr>
+ <tr>
+ <td><b>minChars</b></td>
+ <td><tt>2</tt></td>
+ <td class="definition">
+ The minimum amount of characters after the trigger character necessary to perform a search.
+ </td>
+ </tr>
+ <tr>
+ <td><b>showAvatars</b></td>
+ <td><tt>true&nbsp;|&nbsp;false</tt></td>
+ <td class="definition">
+ Toggles whether or not items within the autocomplete-dropdown will be rendered with an icon/avatar.
+ </td>
+ </tr>
+ <tr>
+ <td><b>classes</b></td>
+ <td><tt>object</tt></td>
+ <td class="definition">
+ Object which contains classes used in the layout as key/value pairs.
+ </td>
+ </tr>
+ <tr>
+ <td><b>templates</b></td>
+ <td><tt>object</tt></td>
+ <td class="definition">
+ Object which contains templates used to render the layout as key/value pairs.
+ </td>
+ </tr>
+</table>
+
+<h2>Methods</h2>
+
+<p>jquery.mentionsInput does expose a number of public methods, you can call on an instance. </p>
+
+<table>
+ <tr>
+ <td><b>init</b></td>
+ <td></td>
+ <td class="definition">
+ Initialises the mentionsInput component on a specific element.
+ </td>
+ </tr>
+ <tr>
+ <td><b>reset</b></td>
+ <td></td>
+ <td class="definition">
+ Resets the component, clears all mentions.
+ </td>
+ </tr>
+ <tr>
+ <td><b>val(callback)</b></td>
+ <td></td>
+ <td class="definition">
+ An async method which accepts a callback function and returns a value of the input field (including markup) as a first parameter of this function. <br/><br/> This is the value you want to send to your server.
+ </td>
+ </tr>
+ <tr>
+ <td><b>getMentions(callback)</b></td>
+ <td></td>
+ <td class="definition">
+ An async method which accepts a callback function and returns a collection of mentions as hash objects as a first parameter.
+ </td>
+ </tr>
+</table>
+
+<h2>Query data structure</h2>
+
+<p>When the component is preforming a "query" on the data specified through the onDataRequest-callback, it's expecting a specific data structure to be returned. </p>
+<pre>
+{
+ 'id' : 1,
+ 'name' : 'Kenneth Auchenberg',
+ 'avatar': 'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif',
+ 'icon' : 'icon-16 icon-person',
+ 'type' : 'contact'
+}
+</pre>
+
+<p>"avatar" property is a URL used for image avatars when "showAvatars"-option is enabled </p>
+<p>"icon" property is a className used for avatars when "showAvatars"-option is disabled</p>
+<p>"type" property specifies an object type which is used in the marked-up version of the mentions result</p>
+
+
+<h2>Markup format</h2>
+<p>When mentions are being added to the input, a marked-up version of the value is generated, to allow the mentions to be extracted, parsed and stored later. </p>
+<pre>
+ This is a message for @[name](type:id)
+</pre>
+<p>Like:</p>
+<pre>
+ This is a message for @[Kenneth Auchenberg](contact:1)
+</pre>
+
+
+<h2>Browser support</h2>
+<p>jquery.mentionsInput has been tested in Firefox 6+, Chrome 15+, and Internet Explorer 8+. </p>
+<p>Please let us know if you see anything weird. And no, we will no make it work for older browsers. Period. </p>
+
+<h2>Dependencies</h2>
+<p>jquery.mentionsInput is written as a jQuery extension, so it naturally requires <a href="http://jquery.com">jQuery (1.6+)</a>. In addition to jQuery, it also depends on <a href="http://documentcloud.github.com/underscore/">underscore.js (1.2+)</a>, which is used to simplify stuff a bit.</p>
+
+<p>The component is also using the new HTML5 "input" event. This means older browsers like IE8 need a polyfill which emulates the event (it is bundled).</p>
+
+<p>The component itself is implemented as a small independent function, so it can easily be ported to frameworks other than jQuery. </p>
+
+<p>Furthermore all utility functions have been centralized in the utils-object, which can be replaced with references if you already got functions like htmlEncode, etc. </p>
+
+<p>To make the component grow and shrink to fit it’s content, you can include <a href="http://www.unwrongest.com/projects/elastic">jquery.elastic.js</a></p>
+
+<h2>License</h2>
+<p>MIT License - <a href="http://www.opensource.org/licenses/mit-license.php">http://www.opensource.org/licenses/mit-license.php</a></p>
+
+<h2>Change Log</h2>
+
+<p>
+ <b class="header">1.0.1</b><br/>
+ <ul>
+ <li>Removed elastic-option since it wasn't really working without it. <a href="https://github.com/podio/jquery-mentions-input/issues/1"> https://github.com/podio/jquery-mentions-input/issues/1</a>)</li>
+ <li>Fixed issue with space on search queries. (<a href="https://github.com/podio/jquery-mentions-input/issues/24"> https://github.com/podio/jquery-mentions-input/issues/24</a>)</li>
+ </ul>
+</p>
+
+<p>
+ <b class="header">1.0.0</b><br/>
+ <ul>
+ <li>Initial release.</li>
+ </ul>
+</p>
+
+ </div>
+
+ <script src='../lib/jquery.events.input.js' type='text/javascript'></script>
+ <script src='../lib/jquery.elastic.js' type='text/javascript'></script>
+ <script src='../jquery.mentionsInput.js' type='text/javascript'></script>
+ <script src='assets/examples.js' type='text/javascript'></script>
+ <script src='assets/example2.js' type='text/javascript'></script>
+
+ <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="//platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script>
+
+ <script type="text/javascript">
+
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-27763738-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+
+ </script>
+
+</body>
+</html>

0 comments on commit c13286a

Please sign in to comment.
Something went wrong with that request. Please try again.