diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Home.md | 8 | ||||
| -rw-r--r-- | doc/Intro-for-Developers.md | 105 | ||||
| -rw-r--r-- | doc/README.md | 38 | ||||
| -rw-r--r-- | doc/api_functions.md | 138 | ||||
| -rw-r--r-- | doc/dev-function-overview.md | 52 |
5 files changed, 340 insertions, 1 deletions
diff --git a/doc/Home.md b/doc/Home.md index f97f987da..0034c4aa9 100644 --- a/doc/Home.md +++ b/doc/Home.md @@ -20,13 +20,19 @@ Red Matrix Documentation and Resources * [Comanche Page Descriptions](help/Comanche) * [Plugins](help/Plugins) * [Developers](help/Developers) -* [Code](doc/html) +* [Intro for Developers](help/Intro-for-Developers.md) +* [API functions](help/api_functions.md) +* [Red Functions 101](help/dev-function-overview.md) +* [Code Reference (doxygen generated)](doc/html) * [To-Do list for the Red Documentation Project](help/To-Do) * [To-Do list for Developers](help/To-Do-Code) **External Resources** * [Main Website](https://github.com/friendica/red) +* [Plugin/Addon Website](https://github.com/friendica/red-addons) +* [Assets Website](https://github.com/friendica/red-assets) + * [Development Channel](http://zothub.com/channel/one) **About** diff --git a/doc/Intro-for-Developers.md b/doc/Intro-for-Developers.md new file mode 100644 index 000000000..bf74cb7c1 --- /dev/null +++ b/doc/Intro-for-Developers.md @@ -0,0 +1,105 @@ +File system layout: +=================== + +[addon] optional addons/plugins + +[boot.php] Every process uses this to bootstrap the application structure + +[doc] Help Files + +[images] core required images + +[include] The "model" in MVC - (back-end functions), also contains PHP "executables" for background processing + +[index.php] The front-end controller for web access + +[install] Installation and upgrade files and DB schema + +[js] core required javascript + +[library] Third party modules (must be license compatible) + +[mod] Controller modules based on URL pathname (e.g. http://sitename/foo loads mod/foo.php) + +[spec] protocol specifications + +[util] translation tools, main English string database and other miscellaneous utilities + +[version.inc] contains current version (auto-updated via cron for the master repository and distributed via git) + +[view] theming and language files + + +[view/(css,js,img,php,tpl)] default theme files + +[view/(en,it,es ...)] language strings and resources + +[view/theme/] individual named themes containing (css,js,img,php,tpl) over-rides + + +The Database: +============= + +* abook - contact table, replaces Friendica 'contact' +* account - service provider account +* addon - registered plugins +* attach - file attachments +* auth_codes - OAuth usage +* cache - TBD +* challenge - old DFRN structure, may re-use or may deprecate +* channel - replaces Friendica 'user' +* clients - OAuth usage +* config - main configuration storage +* event - Events +* fcontact - friend suggestion stuff +* ffinder - friend suggestion stuff +* fserver - obsolete +* fsuggest - friend suggestion stuff +* gcign - ignored friend suggestions +* gcontact - social graph storage, obsolete +* glink - social graph storage - obsolete +* group - privacy groups +* group_member - privacy groups +* hook - plugin hook registry +* hubloc - Red location storage, ties a location to an xchan +* intro - DFRN introductions, may be obsolete +* item - posts +* item_id - other identifiers on other services for posts +* mail - private messages +* manage - may be unused in Red, table of accounts that can "su" each other +* notify - notifications +* notify-threads - need to factor this out and use item thread info on notifications +* outq - Red output queue +* pconfig - personal (per channel) configuration storage +* photo - photo storage +* profile - channel profiles +* profile_check - DFRN remote auth use, may be obsolete +* queue - old Friendica queue, obsolete +* register - registrations requiring admin approval +* session - web session storage +* site - site table to find directory peers +* spam - unfinished +* term - item taxonomy (categories, tags, etc.) table +* tokens - OAuth usage +* verify - general purpose verification structure +* xchan - replaces 'gcontact', list of known channels in the universe +* xlink - "friends of friends" linkages derived from poco +* xprof - if this hub is a directory server, contains basic public profile info of everybody in the network +* xtag - if this hub is a directory server, contains tags or interests of everybody in the network + + +How to theme Red - by Olivier Migeot +==================================== + +This is a short documentation on what I found while trying to modify Red's appearance. + +First, you'll need to create a new theme. This is in /view/theme, and I chose to copy 'redbasic' since it's the only available for now. Let's assume I named it <theme>. + +Oh, and don't forget to rename the _init function in <theme>/php/theme.php to be <theme>_init() instead of redbasic_init(). + +At that point, if you need to add javascript or css files, add them to <theme>/js or <theme>/css, and then "register" them in <theme>_init() through head_add_js('file.js') and head_add_css('file.css'). + +Now you'll probably want to alter a template. These can be found in in /view/tpl OR view/<theme>/tpl. All you should have to do is copy whatever you want to tweak from the first place to your theme's own tpl directory. + + + diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 000000000..3fbfedae7 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,38 @@ +The Red Matrix +============== + +***"Connected Websites"*** + +The modern web is "missing" a few important pieces which would make it much more useful. Many corporations have stepped in with products to supply these missing pieces, but with a loss of freedom and privacy and increased **centralisation**. + +Centralisation is generally considered a bad thing in network design as the loss of one critical node or centralised service could seriously impact the entire network - possibly taking a long time to recover. Recognising this, the original web was based on decentralised services. Over the years, this fundamental design strength has been largely overlooked, as people congregate into centralised services which provide the missing pieces. + +These missing pieces are (in no particular order): + +- Secure and private "spam free" communications + +- Identity and "single-signon" across the entire network + +- Privacy controls and permissions which extend to the entire network + +- Directory services (like a phone book) + + + +The Red Matrix (sometimes referred to as just "Red") is a collection of web servers and services which provides these missing pieces, but within a decentralised identity and messaging framework (known as "Zot"). Red operates as an independent network within the larger internet where all the nodes or servers (we call them "hubs") are able to fully interact with each other in ways that are simply not possible using other services. Additionally the owners of each network hub have the ability to set their own rules with regard to communications privacy and data ownership, because each operates with complete independence. These hubs require only slightly more resources than a blog or content management system, and the software is being designed with the ability to natively incorporate both kinds of functionality, as well as cloud storage. + + + + +Whilst other decentralised communications networks exist, an additional weakness we've found in the implementation of these systems is the binding of network identity with the physical server where it resides; for example if you are "eric@example.website", your identity is often tied permanently to "example.website". We see this as a problem. Many hubs on the Indie Web are run by enthusiasts with varying skill levels and financial resources - and the technology is changing quite rapidly. Often the cost or workload involved in maintaining these services becomes a burden (or hardware fails) and people or entire social communities are left stranded when their server goes offline. Their identity no longer exists. They may have to "start over" building their social circle from scratch when this happens. In some cases communities are unable to recover from this kind of disruption and the entire community dissolves. + +We've been working on decentralisation for several years and have seen this happen time and time again. +Within the Red Matrix, identity is nomadic. It defines you and it belongs to you - and is not locked to a particular network address. You can take your identity, and all your friends and associates with you - to any other hub in the network, at any time. If your hub goes offline for any reason, you have the ability to relocate to any other hub and carry on as if nothing happened. You still have all your friends and associations. + + +The Red Matrix is free and open source distributed under the MIT license. + + +Currently the project is in "Developer Preview". A lot of work remains, but many important bits are functioning. Please connect with one of the developer channels ("Channel One" would be a good choice) if you are interested in helping us out. + +[Please help us change the world by providing a small donation.](http://pledgie.com/campaigns/18417) (Large donations are also graciously accepted).
\ No newline at end of file diff --git a/doc/api_functions.md b/doc/api_functions.md new file mode 100644 index 000000000..8c63770e6 --- /dev/null +++ b/doc/api_functions.md @@ -0,0 +1,138 @@ +Red Twitter API +=============== + +The "basic" Red web API is based on the Twitter API, as this provides instant compatibility with a huge number of third-party clients and applications without requiring any code changes on their part. It is also a super-set of the StatusNet version of the Twitter API, as this also has existing wide support. + +Red has a lot more capability that isn't exposed in the Twitter interfaces or where we are forced to "dumb-down" the API functions to work with the primitive Twitter/StatusNet communications and privacy model. So we plan to extend the Twitter API in ways that will allow Red-specific clients to make full use of Red features without being crippled. + +A dedicated Red API is also being developed to work with native data structures and permissions and which do not require translating to different privacy and permission models and storage formats. This will be described in other documents. The prefix for all of the native endpoints is 'api/red'. + +Red provides multiple channels accesible via the same login account. With Red, any API function which requires authentication will accept a parameter &channel={channel_nickname} - and will select that channel and make it current before executing the API command. By default, the default channel associated with an account is selected. + +Red also provides an extended permission model. In the absence of any Red specific API calls to set permissions, they will be set to the default permissions settings which are associated with the current channel. + +Red will probably never be able to support the Twitter 'api/friendships' functions fully because Red is not a social network and has no concept of "friendships" - it only recognises permissions to do stuff (or not do stuff as the case may be). + +Legend: T= Twitter, S= StatusNet, F= Friendica, R= Red, ()=Not yet working, J= JSON only (XML formats deprecated) + + + +Twitter API compatible functions: + +* api/account/verify_credentials T,S,F,R +* api/statuses/update T,S,F,R +* api/users/show T,S,F,R +* api/statuses/home_timeline T,S,F,R +* api/statuses/friends_timeline T,S,F,R +* api/statuses/public_timeline T,S,F,R +* api/statuses/show T,S,F,R +* api/statuses/retweet T,S,F,R +* api/statuses/destroy T,S,F,(R) +* api/statuses/mentions T,S,F,(R) +* api/statuses/replies T,S,F,(R) +* api/statuses/user_timeline T,S,F,(R) +* api/favorites T,S,F,(R) +* api/account/rate_limit_status T,S,F,R +* api/help/test T,S,F,R +* api/statuses/friends T,S,F,R +* api/statuses/followers T,S,F,R +* api/friends/ids T,S,F,R +* api/followers/ids T,S,F,R +* api/direct_messages/new T,S,F,(R) +* api/direct_messages/conversation T,S,F,(R) +* api/direct_messages/all T,S,F,(R) +* api/direct_messages/sent T,S,F,(R) +* api/direct_messages T,S,F,(R) +* api/oauth/request_token T,S,F,R +* api/oauth/access_token T,S,F,R + + +Twitter API functions supported by StatusNet but not currently by Friendica or Red + +* api/favorites T,S +* api/favorites/create T,S +* api/favorites/destroy T,S +* api/statuses/retweets_of_me T,S +* api/friendships/create T,S +* api/friendships/destroy T,S +* api/friendships/exists T,S +* api/friendships/show T,S +* api/account/update_location T,S +* api/account/update_profile_background_image T,S +* api/account/update_profile_image T,S +* api/blocks/create T,S +* api/blocks/destroy T,S + +Twitter API functions not currently supported by StatusNet + +* api/statuses/retweeted_to_me T +* api/statuses/retweeted_by_me T +* api/direct_messages/destroy T +* api/account/end_session T,(R) +* api/account/update_delivery_device T +* api/notifications/follow T +* api/notifications/leave T +* api/blocks/exists T +* api/blocks/blocking T +* api/lists T + + +Statusnet compatible extensions to the Twitter API supported in both Friendica and Red + +* api/statusnet/version S,F,R +* api/statusnet/config S,F,R + +Friendica API extensions to the Twitter API supported in both Friendica and Red + +* api/statuses/mediap F,R + + +Red specific API extensions to the Twitter API not supported in Friendica + +* api/account/logout R +* api/export/basic R,J +* api/friendica/config R +* api/red/config R +* api/friendica/version R +* api/red/version R + +* api/red/channel/export/basic R,J +* api/red/channel/stream R,J (currently post only) +* api/red/albums R,J +* api/red/photos R,J (option album=xxxx) + + +Red proposed API extensions to the Twitter API + +* api/statuses/edit (R),J +* api/statuses/permissions (R),J +* api/statuses/permissions/update (R),J +* api/statuses/ids (R),J # search for existing message_id before importing a foreign post +* api/files/show (R),J +* api/files/destroy (R),J +* api/files/update (R),J +* api/files/permissions (R),J +* api/files/permissions/update (R),J +* api/pages/show (R),J +* api/pages/destroy (R),J +* api/pages/update (R),J +* api/pages/permissions (R),J +* api/pages/permissions/update (R),J +* api/events/show (R),J +* api/events/update (R),J +* api/events/permissions (R),J +* api/events/permissions/update (R),J +* api/events/destroy (R),J +* api/photos/show (R),J +* api/photos/update (R),J +* api/photos/permissions (R),J +* api/photos/permissions/update (R),J +* api/albums/destroy (R),J +* api/albums/show (R),J +* api/albums/update (R),J +* api/albums/permissions (R),J +* api/albums/permissions/update (R),J +* api/albums/destroy (R),J +* api/friends/permissions (R),J + + diff --git a/doc/dev-function-overview.md b/doc/dev-function-overview.md new file mode 100644 index 000000000..445b4823b --- /dev/null +++ b/doc/dev-function-overview.md @@ -0,0 +1,52 @@ +Red development - some useful basic functions +============================================= + + + +* get_account_id() + +Returns numeric account_id if authenticated or 0. It is possible to be authenticated and not connected to a channel. + +* local_user() + +Returns authenticated numeric channel_id if authenticated and connected to a channel or 0. Sometimes referred to as $uid in the code. + +* remote_user() + +Returns authenticated string hash of Red global identifier, if authenticated via remote auth, or an empty string. + +* get_app() + +Returns the global app structure ($a). + +* App::get_observer() + +(App:: is usually assigned to the global $a), so $a->get_observer() or get_app()->get_observer() - returns an xchan structure representing the current viewer if authenticated (locally or remotely). + +* get_config($family,$key), get_pconfig($uid,$family,$key) + +Returns the config setting for $family and $key or false if unset. + +* set_config($family,$key,$value), set_pconfig($uid,$family,$key,$value) + +Sets the value of config setting for $family and $key to $value. Returns $value. The config versions operate on system-wide settings. The pconfig versions get/set the values for a specific integer uid (channel_id). + +* dbesc() + +Always escape strings being used in DB queries. This function returns the escaped string. Integer DB parameters should all be proven integers by wrapping with intval() + +* q($sql,$var1...) + +Perform a DB query with the SQL statement $sql. printf style arguments %s and %d are replaced with variable arguments, which should each be appropriately dbesc() or intval(). SELECT queries return an array of results or false if SQL or DB error. Other queries return true if the command was successful or false if it wasn't. + +* t($string) + +Returns the translated variant of $string for the current language or $string (default 'en' language) if the language is unrecognised or a translated version of the string does not exist. + +* x($var), $x($array,$key) + +Shorthand test to see if variable $var is set and is not empty. Tests vary by type. Returns false if $var or $key is not set. +If variable is set, returns 1 if has 'non-zero' value, otherwise returns 0. -- e.g. x('') or x(0) returns 0; + + + |