Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 113 lines (92 sloc) 9.966 kB
a55680b Spelling correction in README
holdensmagicalunicorn authored
1 jData is a shared localStorage object interface that can be accessed by any website on the internet and works on Firefox 3+, Webkit 3.1.2/3.2+ nightlies and IE8. Think of it as pseudo-globalStorage[""] but write access needs user confirmation. The API uses window.postMessage to communicate in a standard JSON format I have documented in the API reference. The jData Interface Library can simplify using the API greatly and has efficient callback management (postMessage is asynchronous so the callbacks are stored and used when the response is received, then they are deleted).
5689a90 @eligrey Better README
eligrey authored
2
0eff316 @eligrey Added API documentation to the README
eligrey authored
3 To manage your data stored by the official jData host, go to the [jData Manager.][1]
5689a90 @eligrey Better README
eligrey authored
4
0eff316 @eligrey Added API documentation to the README
eligrey authored
5 ## API
6
a55680b Spelling correction in README
holdensmagicalunicorn authored
7 The new jData API is much more robust than the previous jData API. The new API uses JSON for communication between client and host. For the API reference below, "foo" is the item being set, "bar" is the value for an item being set, and REQUEST_ID is just a random ID for the request. Every response includes a property named "jdata" set to true, to help the client figure out what what the response is to (in case there are multiple libraries sending different formats to iframes)
0eff316 @eligrey Added API documentation to the README
eligrey authored
8
9 If you send an optional request ID, the jData host will respond using the same ID, making it possible to identify what the response is a response to without having to guess.
10
11
12 * Setting a variable
13 * Request: `{id:REQUEST_ID, method: "set", item: "foo", value: "bar" }`
14 * Response: `{jdata: true, id:REQUEST_ID, response: true [or false if user denies set request]}`
15 * Removing a variable
16 * Request: `{id:REQUEST_ID, method: "remove", item: "foo" }`
17 * Response: `{jdata: true, id:REQUEST_ID, response: true [or false if user denies remove request]}`
18 * The response will always be true if the variable being requested to be removed is not set.
19 * Getting the value of a variable
20 * Request: `{id:REQUEST_ID, method: "get", item: "foo" }`
21 * Response: `{jdata: true, id:REQUEST_ID, response: "bar" [or null if variable not set]}`
22 * Requesting to become a trusted host
23 * Request: `{id:REQUEST_ID, method: "trust" }`
24 * Response: `{jdata: true, id:REQUEST_ID, response: true [or false if user denies trust request]}`
25 * The response will always be true (no confirmation prompt to the user) if the host is already a trusted host.
26 * Requesting to become an untrusted host (will always return true). You might only use this to give the user an option to remove you from the trustedHosts list without having to go to the management page.
27 * Request: `{id:REQUEST_ID, method: "untrust" }`
28 * Response: `{jdata: true, id:REQUEST_ID, response: true}`
29 * Getting every variable in the jData host's localStorage
30 * Request: `{id:REQUEST_ID, method: "list" }`
31 * Response: `{jdata: true, id:REQUEST_ID, response: ["foo", "some-other-variable", ect...]}`
32 * Getting amount of variables in the jData host's localStorage
33 * Request: `{id:REQUEST_ID, method: "length" }`
34 * Response: `{jdata: true, id:REQUEST_ID, response: integer that is the amount of variables in the localStorage}`
35
5689a90 @eligrey Better README
eligrey authored
36
ecb0a28 @eligrey Added jData Standard documentation to README
eligrey authored
37 ## Standard
38
39 *version 0.1.2*
40
41 This standard is a list of item names that should be used with jData.
42
43 * **jData Host **- Currently http://jdata.eligrey.com
44 * This can include a pathname, so example.com/jdata can be a valid **jData Host**.
45 * postMessage API: {**jData Host**}/api/postMessage
46 * Data management: {**jData Host**}/manage
47 * Data migration: {**jData Host**}/migrate
48 * Data migration to another jData host requires you allow your current jData host to become a trusted host in the jData host you are migrating to (will go back to untrusted after transition).
49 * **jData Origin** - {**jData Host's Protocol: + Domain + Non-standard port**}
50 * The size limit: Browsers will limit how much data can be stored in the jData website's localStorage object, so please do not set preferences that use anything near or over 1kb of data. jData is supposed to be a global resource that any website can access.
51 * All items are case-insensitive, as they will be converted to lowercase on being proccessed by jData. Any prompts for confirmation of modification of an item will preserve the case.
52 * Example: Setting "OpenID" on an untrusted host will ask if the user allows setting "OpenID" and will set "openid" if the user agrees. If you try to get "OpenID", "openid" is accessed and returned.
53 * Protected/Restricted Items: These items can not be directly modified or deleted. They may have a special method to modify them though.
54 * **trustedHosts**:Array - An array of hosts (including the protocol, ie. http://example.com, chrome://extensiondev) that do not need to ask for permission to set and delete items. A host can become a trusted host by issuing a trust request that gets accepted.
55 * Trusted hosts management functionality is included in the data management jData host page.
56 * Standard classes:
57 * **preference** - A user's preference about an item.
58 * **understand** - A user understands an item. (eg. **understand.language.javascript** => 'true' means they understand javascript)
59 * **is** - A user is something. (eg. **is.developer** => 'true' means the user is a developer)
60 * **fullname** - String containing first and last name separated by a space. Example: "personal.fullname" => "Elijah Grey"
61 * Use the word "username" instead of "user" where possible.
62 * {**domain name**} - For the following items, you are **only** allowed to store information that would be useful to other websites, as not to waste space in jData's quota on a user's browser. If you want to store data that's only useful to the domain, store it in your own site's localStorage.
63 * {**domain name**}|{**item**} - For website-specific data. Example: "digg.com|username" => "Sephr"
64 * **age** - Integer; age of user. Example: "age" => "15"
65 * **birthday** - A UTC formatted date of birth with year replaced by "BDAY". (just day and month) - Example: Monday, BDAY-11-24 UTC
66 * **birthdate** - A UTC formatted date of birth with year. (just day, month, and year) - Example: Monday, 2008-11-24 UTC
67 * **gender** - Gender of person. Either "male", "female", "other", or "n/a". - Case insensitive
68 * **address** Class
69 * **address.state** - State or province the user lives in.
70 * **address.zip** - Zip code of where the user lives.
71 * **address.country** - Country the user lives in.
72 * **surname** - Surname of person.
73 * **company** - Company a person works for.
74 * **contact.email** - Valid email address that may be used to contact user. - I don't recommend setting this due to spam but if you must, that is this is the recommended name.
75 * **contact.phone** - Phone number of user. - Same conditions as **contact.email**.
76 * **nickname** - Nickname
77 * **status** - String containing what the person is currently doing. Example: "status" => "Watching Movie: The Dark Knight". This would be best used in conjunction with a [Twitter][1]-esque webapp.
78 * **openid** - User's [OpenID address][2].
79 * **websites** - A person's websites. A JSON-encoded object that follows this format: `[{"Website 1":"URI"},{"Website 2":"URI"}]`. They should be listed in order of importance so if you must pick only one, pick the first one.
80 * **blogs** - Same as **websites** but for blogs only.
81 * **preference.sendUpdates** - A user's default preference on sending them updates about services they sign up to. Defaults to false;
82 * **understand.language.**{**language**} - (If the language has an ISO shortcode, use that instead, ie. English = en) A user understands the programming language. (case insensitive) Example: **understand.brainfuck** => 'false', or **understand.en**=> 'true'
83 * **understand.howto.**{**something**} - A user understands how to do something.
84 * **understand.**{**something**} - Understand something.
85 * **preference.jdata.manager** - URI of preferred jData manager. Use to link a user to their preferred jData manager and if you have your own, it would be a good idea to let them set it as default. Defaults to {**jData Website**}/manage
86 * **jdata.manager.backup**:boolean - Backup prefences if possible at jData Manager.
87 * **jdata.manager.backup.id** - A unique id for getting a backup. Should also be stored in a cookie because the only time you need a backup is when you lose the data localStorage data.
88 * **preference.filter** - JSON object with things that should be filtered. Example: {"explicit-images":true, "explicit-text":false}
89 * explicit-images:boolean - Filter explicit images
90 * explicit-text:Array|boolean - Filter explicit text specified in an array or if it is true, filter words that you think are explicit.
91 * ads:boolean - Filter advertisements. (I'm guessing this isn't ever going to be followed)
92 * **preference.design.colors**:Array - Case insensitive hex values starting with # in an array. Preferred colors to be seen in a website.
93 * **preference.design.colors.scheme** - Case insensitive. Website color scheme preference; either "light", "neutral", or "dark".
94 * **preference.searchEngine** - A person's preferred search engine. JSON encoded object that follows {"Engine Name":"URI"}. *%s* in the URI is replaced with the query.
95 * **is.developer**:boolean - The user is a developer (the kind that deals with code).
96 * **is.designer**:boolean - The user is a designer that designs UIs (the computer kind of designer, not a clothes designer). I will make a form sooner or later (or maby never) that enables you to change all of these values easily.
97
98 [1]: http://twitter.com/
99 [2]: http://openid.net/what/
100
101 ## Interface Library
102
103 I have also created a reference [Interface Library][2] that can be used with jData.
5689a90 @eligrey Better README
eligrey authored
104
aa3d121 @eligrey Added tracking image to README.
eligrey authored
105
106
b496b1b @eligrey Fixing tracking image for GitHub Flavored Markdown bug.
eligrey authored
107 ![Tracking image](//in.getclicky.com/212712ns.gif)
aa3d121 @eligrey Added tracking image to README.
eligrey authored
108
109
5689a90 @eligrey Better README
eligrey authored
110 [1]: http://jdata.eligrey.com/manage.php
ecb0a28 @eligrey Added jData Standard documentation to README
eligrey authored
111 [2]: http://github.com/eligrey/jil#readme
0eff316 @eligrey Added API documentation to the README
eligrey authored
112
Something went wrong with that request. Please try again.