From 713a34c68e242c5bee927f3de41fffaeb2842bf1 Mon Sep 17 00:00:00 2001 From: Andrew Manning Date: Sun, 27 Nov 2016 08:34:23 -0700 Subject: Restructured main table of contents to link to fewer pages with more content. The admin, dev, and member guides are single pages each having a table of contents at the top that is represented in condensed form in the main navigation sidebar. Section links are used to navigate between content sections for simplicity and fewer page loads. --- doc/developer/developer_guide.html | 473 +++++++++++++++++++++++++++++++++++++ 1 file changed, 473 insertions(+) create mode 100644 doc/developer/developer_guide.html (limited to 'doc/developer') diff --git a/doc/developer/developer_guide.html b/doc/developer/developer_guide.html new file mode 100644 index 000000000..34779a7e8 --- /dev/null +++ b/doc/developer/developer_guide.html @@ -0,0 +1,473 @@ +

Table of Contents +

+ +

Who is a Hubzilla developer? Should I read this?

+ +

Anyone who contributes to making Hubzilla better is a developer. There are many different and important ways you can contribute to this amazing technology, even if you do not know how to write code. The software itself is only a part of the Hubzilla project. You can contribute by

+ +

Software developers are of course welcomed; there are so many great ideas to implement and not enough people to make them all a reality! The Hubzilla code base is an advanced and mature system, but the platform is still very flexible and responsive to new ideas.

+ +

This document will help you get started learning and contributing to Hubzilla.

+ +

Versioning system

+ +

The versioning system is similar to the popular semantic versioning but less stringent. Given x.y.z, x changes yearly. y changes for "stable" monthly builds, and z increments when there are interface changes. We maintain our date and build numbers for medium grain version control (commits within a certain date range) and of course git revs for fine grained control.

+ +

Git repository branches

+ +

There are two official branches of the Hubzilla git repo.

+ +

Developer tools and workflows

+ +

Hub Snapshots

+ +

The Hub Snapshots page provides instructions and scripts for taking complete +snapshots of a hub to support switching between consistent and completely known +states. This is useful to prevent situations where the content or database schema +might be incompatible with the code.

+ +

Translations

+ +

Our translations are managed through Transifex. If you wish to help out translating Hubzilla to another language, sign up on transifex.com, visit https://www.transifex.com/projects/p/red-matrix/ and request to join one of the existing language teams or create a new one. Notify one of the core developers when you have a translation update which requires merging, or ask about merging it yourself if you're comfortable with git and PHP. We have a string file called 'messages.po' which is gettext compliant and a handful of email templates, and from there we automatically generate the application's language files.

+ +

Translation Process

+ +

The strings used in the UI of Hubzilla is translated at [Transifex][1] and then +included in the git repository at github. If you want to help with translation +for any language, be it correcting terms or translating Hubzilla to a +currently not supported language, please register an account at transifex.com +and contact the Redmatrix translation team there.

+ +

Translating Hubzilla is simple. Just use the online tool at transifex. If you +don't want to deal with git & co. that is fine, we check the status of the +translations regularly and import them into the source tree at github so that +others can use them.

+ +

We do not include every translation from transifex in the source tree to avoid +a scattered and disturbed overall experience. As an uneducated guess we have a +lower limit of 50% translated strings before we include the language. This +limit is judging only by the amount of translated strings under the assumption +that the most prominent strings for the UI will be translated first by a +translation team. If you feel your translation useable before this limit, +please contact us and we will probably include your teams work in the source +tree.

+ +

If you want to get your work into the source tree yourself, feel free to do so +and contact us with and question that arises. The process is simple and +Hubzilla ships with all the tools necessary.

+ +

The location of the translated files in the source tree is + /view/LNG-CODE/ +where LNG-CODE is the language code used, e.g. de for German or fr for French. +For the email templates (the *.tpl files) just place them into the directory +and you are done. The translated strings come as a "hmessages.po" file from +transifex which needs to be translated into the PHP file Hubzilla uses. To do +so, place the file in the directory mentioned above and use the "po2php" +utility from the util directory of your Hubzilla installation.

+ +

Assuming you want to convert the German localization which is placed in +view/de/hmessages.po you would do the following.

+ +

  1. Navigate at the command prompt to the base directory of your +Hubzilla installation

    2. +

  2. Execute the po2php script, which will place the translation +in the hstrings.php file that is used by Hubzilla.

    + +

    $> php util/po2php.php view/de/hmessages.po

    + +

    The output of the script will be placed at view/de/hstrings.php where +froemdoca os expecting it, so you can test your translation mmediately.

    3. +

  3. Visit your Hubzilla page to check if it still works in the language you +just translated. If not try to find the error, most likely PHP will give +you a hint in the log/warnings.about the error.

    + +

    For debugging you can also try to "run" the file with PHP. This should +not give any output if the file is ok but might give a hint for +searching the bug in the file.

    + +

    $> php view/de/hstrings.php

    4. +

  4. commit the two files with a meaningful commit message to your git +repository, push it to your fork of the Hubzilla repository at github and +issue a pull request for that commit.

    5. +

Utilities

+ +

Additional to the po2php script there are some more utilities for translation +in the "util" directory of the Hubzilla source tree. If you only want to +translate Hubzilla into another language you wont need any of these tools most +likely but it gives you an idea how the translation process of Hubzilla +works.

+ +

For further information see the utils/README file.

+ +

Known Problems

+ +

To-be-organized information

+ +

Here is how you can join us.

+ +

First, get yourself a working git package on the system where you will be +doing development.

+ +

Create your own github account.

+ +

You may fork/clone the Red repository from https://github.com/redmatrix/hubzilla.git.

+ +

Follow the instructions provided here: http://help.github.com/fork-a-repo/ +to create and use your own tracking fork on github

+ +

Then go to your github page and create a "Pull request" when you are ready +to notify us to merge your work.

+ +

Important

+ +

Please pull in any changes from the project repository and merge them with your work before issuing a pull request. We reserve the right to reject any patch which results in a large number of merge conflicts. This is especially true in the case of language translations - where we may not be able to understand the subtle differences between conflicting versions.

+ +

Also - test your changes. Don't assume that a simple fix won't break something else. If possible get an experienced Red developer to review the code.

+ +

Licensing

+ +

All code contributed to the project falls under the MIT license, unless otherwise specified. We will accept third-party code which falls under MIT, BSD and LGPL, but copyleft licensing (GPL, and AGPL) is only permitted in addons. It must be possible to completely remove the GPL (copyleft) code from the main project without breaking anything.

+ +

Coding Style

+ +

In the interests of consistency we adopt the following code styling. We may accept patches using other styles, but where possible please try to provide a consistent code style. We aren't going to argue or debate the merits of this style, and it is irrelevant what project 'xyz' uses. This is not project 'xyz'. This is a baseline to try and keep the code readable now and in the future.

+ +

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

+ +

[library] Third party modules (must be license compatible)

+ +

[mod] Controller modules based on URL pathname (e.g. #^[url=http://sitename/foo]http://sitename/foo[/url] loads mod/foo.php)

+ +

[mod/site/] site-specific mod overrides, excluded from git

+ +

[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:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TableDescription
abconfigcontact table, replaces Friendica 'contact'
abook
accountservice provider account
addon
addressbookchanges
addressbooks
app
atoken
attach
auth_codes
cache
cal
calendarchanges
calendarinstances
calendarobjects
calendars
calendarsubscriptions
cards
channel
chat
chatpresence
chatroom
clients
config
conv
dreport
event
group_member
groupmembers
groups
hook
hubloc
iconfig
issue
item
item_id
likes
locks
mail
menu
menu_item
notify
obj
outq
pconfigpersonal (per channel) configuration storage
photo
poll
poll_elm
principals
profdef
profext
profile
profile_check
propertystorage
register
schedulingobjects
session
shares
sign
site
source
sys_perms
term
tokens
updates
users
verify
vote
xchan
xchat
xconfig
xign
xlink
xperm
xprof
xtag
* abook - contact table, replaces Friendica 'contact'
+* account - service provider account
+* addon - registered plugins
+* app - peronal app data
+* attach - file attachments
+* auth_codes - OAuth usage
+* cache - OEmbed cache
+* channel - replaces Friendica 'user'
+* chat - chat room content
+* chatpresence - channel presence information for chat
+* chatroom - data for the actual chat room
+* clients - OAuth usage
+* config - main configuration storage
+* conv - Diaspora private messages
+* event - Events
+* fcontact - friend suggestion stuff
+* ffinder - friend suggestion stuff
+* fserver - obsolete
+* fsuggest - friend suggestion stuff
+* groups - privacy groups
+* group_member - privacy groups
+* hook - plugin hook registry
+* hubloc - Red location storage, ties a location to an xchan
+* item - posts
+* item_id - other identifiers on other services for posts
+* likes - likes of 'things'
+* mail - private messages
+* menu - channel menu data
+* menu_item - items uses by channel menus
+* notify - notifications
+* notify-threads - need to factor this out and use item thread info on notifications
+* obj - object data for things (x has y)
+* outq - output queue
+* pconfig - personal (per channel) configuration storage
+* photo - photo storage
+* poll - data for polls
+* poll_elm - data for poll elements
+* profdef - custom profile field definitions
+* profext - custom profile field data
+* profile - channel profiles
+* profile_check - DFRN remote auth use, may be obsolete
+* register - registrations requiring admin approval
+* session - web session storage
+* shares - shared item information
+* sign - Diaspora signatures.  To be phased out.
+* site - site table to find directory peers
+* source - channel sources data
+* spam - unfinished
+* sys_perms - extensible permissions for the sys channel
+* term - item taxonomy (categories, tags, etc.) table
+* tokens - OAuth usage
+* updates - directory sync updates
+* verify - general purpose verification structure
+* vote - vote data for polls
+* xchan - replaces 'gcontact', list of known channels in the universe
+* xchat - bookmarked chat rooms
+* xconfig - as pconfig but for channels with no local account
+* 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 Hubzilla

+ +

This is a short documentation on what I found while trying to modify Hubzilla'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 .

+ +

Oh, and don't forget to rename the _init function in /php/theme.php to be _init() instead of redbasic_init().

+ +

At that point, if you need to add javascript or css files, add them to /js or /css, and then "register" them in _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//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.

+ +

We're pretty relaxed when it comes to developers. We don't have a lot of rules. Some of us are over-worked and if you want to help we're happy to let you help. That said, attention to a few guidelines will make the process smoother and make it easier to work together. We have developers from across the globe with different abilities and different cultural backgrounds and different levels of patience. Our primary rule is to respect others. Sometimes this is hard and sometimes we have very different opinions of how things should work, but if everybody makes an effort, we'll get along just fine.

+ +

Here is how you can join us.

+ +

First, get yourself a working git package on the system where you will be +doing development.

+ +

Create your own github account.

+ +

You may fork/clone the Red repository from [url=https://github.com/redmatrix/hubzilla.git]https://github.com/redmatrix/hubzilla.git[/url]

+ +

Follow the instructions provided here: [url=http://help.github.com/fork-a-repo/]http://help.github.com/fork-a-repo/[/url] +to create and use your own tracking fork on github

+ +

Then go to your github page and create a "Pull request" when you are ready +to notify us to merge your work.

+ +

Translations

+ +

Our translations are managed through Transifex. If you wish to help out translating the $Projectname to another language, sign up on transifex.com, visit [url=https://www.transifex.com/projects/p/red-matrix/]https://www.transifex.com/projects/p/red-matrix/[/url] and request to join one of the existing language teams or create a new one. Notify one of the core developers when you have a translation update which requires merging, or ask about merging it yourself if you're comfortable with git and PHP. We have a string file called 'messages.po' which is gettext compliant and a handful of email templates, and from there we automatically generate the application's language files.

+ +

Important

+ +

Please pull in any changes from the project repository and merge them with your work before issuing a pull request. We reserve the right to reject any patch which results in a large number of merge conflicts. This is especially true in the case of language translations - where we may not be able to understand the subtle differences between conflicting versions.

+ +

Also - test your changes. Don't assume that a simple fix won't break something else. If possible get an experienced Red developer to review the code.

+ +

Further documentation can be found at the Github wiki pages at: [url=https://github.com/friendica/red/wiki]https://github.com/friendica/red/wiki[/url]

+ +

Licensing

+ +

All code contributed to the project falls under the MIT license, unless otherwise specified. We will accept third-party code which falls under MIT, BSD and LGPL, but copyleft licensing (GPL, and AGPL) is only permitted in addons. It must be possible to completely remove the GPL (copyleft) code from the main project without breaking anything.

+ +

Concensus Building

+ +

Code changes which fix an obvious bug are pretty straight-forward. For instance if you click "Save" and the thing you're trying to save isn't saved, it's fairly obvious what the intended behaviour should be. Often when developing feature requests, it may affect large numbers of community members and it's possible that other members of the community won't agree with the need for the feature, or with your proposed implementation. They may not see something as a bug or a desirable feature.

+ +

We encourage consensus building within the community when it comes to any feature which might be considered controversial or where there isn't unanimous decision that the proposed feature is the correct way to accomplish the task. The first place to pitch your ideas is to [url=https://zothub.com/channel/one]Channel One[/url]. Others may have some input or be able to point out facets of your concept which might be problematic in our environment. But also, you may encounter opposition to your plan. This doesn't mean you should stop and/or ignore the feature. Listen to the concerns of others and try and work through any implementation issues.

+ +

There are places where opposition cannot be resolved. In these cases, please consider making your feature optional or non-default behaviour that must be specifically enabled. This technique can often be used when a feature has significant but less than unanimous support. Those who desire the feature can turn it on and those who don't want it - will leave it turned off.

+ +

If a feature uses other networks or websites and or is only seen as desirable by a small minority of the community, consider making the functionality available via an addon or plugin. Once again, those who don't desire the feature won't need to install it. Plugins are relatively easy to create and "hooks" can be easily added or modified if the current hooks do not do what is needed to allow your plugin to work.

+ +

Coding Style

+ +

In the interests of consistency we adopt the following code styling. We may accept patches using other styles, but where possible please try to provide a consistent code style. We aren't going to argue or debate the merits of this style, and it is irrelevant what project 'xyz' uses. This is not project 'xyz'. This is a baseline to try and keep the code readable now and in the future.

+ + + \ No newline at end of file -- cgit v1.2.3 From b32bce9be22ca9c0c2b47e4a43282e9289c236ff Mon Sep 17 00:00:00 2001 From: Andrew Manning Date: Tue, 29 Nov 2016 22:08:19 -0500 Subject: Major changes to accordion nav menu. Table of contents auto-generated below the loaded page. Removed manual TOCs from individual pages. TOC uses jQuery plugin Sticky to remain visible when it would scroll out of view. --- doc/developer/developer_guide.html | 3 --- 1 file changed, 3 deletions(-) (limited to 'doc/developer') diff --git a/doc/developer/developer_guide.html b/doc/developer/developer_guide.html index 34779a7e8..77d622221 100644 --- a/doc/developer/developer_guide.html +++ b/doc/developer/developer_guide.html @@ -1,6 +1,3 @@ -

Table of Contents -

-

Who is a Hubzilla developer? Should I read this?

Anyone who contributes to making Hubzilla better is a developer. There are many different and important ways you can contribute to this amazing technology, even if you do not know how to write code. The software itself is only a part of the Hubzilla project. You can contribute by

-- cgit v1.2.3 From d17abedc7de4d43b0495a1be6210b311e58bfe69 Mon Sep 17 00:00:00 2001 From: Andrew Manning Date: Wed, 7 Dec 2016 22:25:50 -0500 Subject: Convert about sections back to bbcode, update some formatting. --- doc/developer/api_zot.md | 521 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 521 insertions(+) create mode 100644 doc/developer/api_zot.md (limited to 'doc/developer') diff --git a/doc/developer/api_zot.md b/doc/developer/api_zot.md new file mode 100644 index 000000000..26af72298 --- /dev/null +++ b/doc/developer/api_zot.md @@ -0,0 +1,521 @@ +Zot API +======= + +The API endpoints detailed below are relative to `api/z/1.0`, meaning that if an +API is listed as `channel/stream` the full API URL is +`[baseurl]/api/z/1.0/channel/stream` + +channel/export/basic +================================================================================ + +Export channel data + + +channel/stream +================================================================================ + +Fetch conversation items + + +files +================================================================================ + +List file storage + +filemeta +================================================================================ +Export file metadata for any uploaded file + + +filedata +================================================================================ + +Export file contents for any uploaded file + + +file/export +================================================================================ + +file +================================================================================ + +albums +================================================================================ + +List photo albums + + +photos +================================================================================ + +list photo metadata + + +photo +================================================================================ + + +group +================================================================================ + +`GET /api/z/1.0/group` + +Description: list privacy groups + +Returns: DB tables of all privacy groups. + +To use with API group_members, provide either 'group_id' from the id element returned in this call, or 'group_name' from the gname returned in this call. + + + [ + + { + "id": "1", + "hash": "966c946394f3e2627bbb8a55026b5725e582407098415c02f85232de3f3fde76Friends", + "uid": "2", + "visible": "0", + "deleted": "0", + "gname": "Friends" + }, + { + "id": "2", + "hash": "852ebc17f8c3ed4866f2162e384ded0f9b9d1048f93822c0c84196745f6eec66Family", + "uid": "2", + "visible": "1", + "deleted": "0", + "gname": "Family" + }, + { + "id": "3", + "hash": "cc3cb5a7f9818effd7c7c80a58b09a189b62efa698a74319117babe33ee30ab9Co-workers", + "uid": "2", + "visible": "0", + "deleted": "0", + "gname": "Co-workers" + } + ] + +group_members +================================================================================ + +`GET /api/z/1.0/group_members` + +Required: + +group_id or group_name + + +Returns: + +group_member+abook+xchan (DB join) for each member of the privacy group + + + [ + + { + "id": "1", + "uid": "2", + "gid": "1", + "xchan": "pgcJx1IQjuPkx8aI9qheJlBMZzJz-oTPjHy3h5pWlOVOriBO_cSiUhhqwhuZ74TYJ8_ECO3pPiRMWC0q8YPCQg", + "abook_id": "2", + "abook_account": "1", + "abook_channel": "2", + "abook_xchan": "pgcJx1IQjuPkx8aI9qheJlBMZzJz-oTPjHy3h5pWlOVOriBO_cSiUhhqwhuZ74TYJ8_ECO3pPiRMWC0q8YPCQg", + "abook_my_perms": "218555", + "abook_their_perms": "0", + "abook_closeness": "0", + "abook_created": "2016-01-02 21:16:26", + "abook_updated": "2016-01-02 21:16:26", + "abook_connected": "0000-00-00 00:00:00", + "abook_dob": "0000-00-00 00:00:00", + "abook_flags": "0", + "abook_blocked": "0", + "abook_ignored": "0", + "abook_hidden": "0", + "abook_archived": "0", + "abook_pending": "0", + "abook_unconnected": "0", + "abook_self": "1", + "abook_feed": "0", + "abook_profile": "", + "abook_incl": "", + "abook_excl": "", + "abook_instance": "", + "xchan_hash": "pgcJx1IQjuPkx8aI9qheJlBMZzJz-oTPjHy3h5pWlOVOriBO_cSiUhhqwhuZ74TYJ8_ECO3pPiRMWC0q8YPCQg", + "xchan_guid": "lql-1VnxtiO4-WF0h72wLX1Fu8szzHDOXgQaTbELwXW77k8AKFfh-hYr70vqMrc3SSvWN-Flrc5HFhRTWB7ICw", + "xchan_guid_sig": "PafvEL0VpKfxATxlCqDjfOeSIMdmpr3iU7X-Sysa1h5LzDpjSXsjO37tYZL-accb1M5itLlfnW5epkTa5I4flsW21zSY1A2jCuBQUTLLGV7rNyyBy7lgqJUFvAMRx0TfXzP9lcaPqlM9T1tA6jfWOsOmkdzwofGeXBnsjGfjsO2xdGYe6vwjOU0DSavukvzDMnOayB9DekpvDnaNBTxeGLM45Skzr7ZEMcNF7TeXMbnvpfLaALYEKeQs9bGH-UgAG8fBWgzVAzeBfx_XSR1rdixjyiZGP0kq0h35SlmMPcEjliodOBFwMXqpXFB7Ibp4F6o6te2p2ErViJccQVG8VNKB6SbKNXY6bhP5zVcVsJ-vR-p4xXoYJJvzTN7yTDsGAXHOLF4ZrXbo5yi5gFAlIrTLAF2EdWQwxSGyLRWKxG8PrDkzEzX6cJJ0VRcLh5z6OI5QqQNdeghPZbshMFMJSc_ApCPi9_hI4ZfctCIOi3T6bdgTNKryLm5fhy_eqjwLAZTGP-aUBgLZpb1mf2UojBn6Ey9cCyq-0T2RWyk-FcIcbV4qJ-p_8oODqw13Qs5FYkjLr1bGBq82SuolkYrXEwQClxnrfKa4KYc2_eHAXPL01iS9zVnI1ySOCNJshB97Odpooc4wk7Nb2Fo-Q6THU9zuu0uK_-JbK7IIl6go2qA", + "xchan_pubkey": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA18JB76lyP4zzL/y7BCej\neJnfZIWZNtM3MZvI1zEVMWmmwOS+u/yH8oPwyaDk4Y/tnj8GzMPj1lCGVRcd8EJa\nNrCMd50HODA5EsJtxpsOzRcILYjOcTtIAG1K4LtKqELi9ICAaFp0fNfa+Jf0eCek\nvPusx2/ORhy+o23hFoSMhL86o2gmaiRnmnA3Vz4ZMG92ieJEDMXt9IA1EkIqS4y5\nBPZfVPLD1pv8iivj+dtN1XjwplgjUbtxmU0/Ej808nHppscRIqx/XJ0XZU90oNGw\n/wYoK2EzJlPbRsAkwNqoFrAYlr5HPpn4BJ2ebFYQgWBUraD7HwS5atsQEaxGfO21\nlUP0+lDg9t3CXvudDj0UG1jiEKbVIGA+4aG0GN2DSC5AyRq/GRxqyay5W2vQbAZH\nyvxPGrZFO24I65g3pjhpjEsLqZ4ilTLQoLMs0drCIcRm5RxMUo4s/LMg16lT4cEk\n1qRtk2X0Sb1AMQQ2uRXiVtWz77QHMONEYkf6OW4SHbwcv5umvlv69NYEGfCcbgq0\nAV7U4/BWztUz/SWj4r194CG43I9I8dmaEx9CFA/XMePIAXQUuABfe1QMOR6IxLpq\nTHG1peZgHQKeGz4aSGrhQkZNNoOVNaZoIfcvopxcHDTZLigseEIaPPha4WFYoKPi\nUPbZ5o8gTLc750uzrnb2jwcCAwEAAQ==\n-----END PUBLIC KEY-----\n", + "xchan_photo_mimetype": "image/png", + "xchan_photo_l": "https://xyz.macgirvin.com/photo/profile/l/2", + "xchan_photo_m": "https://xyz.macgirvin.com/photo/profile/m/2", + "xchan_photo_s": "https://xyz.macgirvin.com/photo/profile/s/2", + "xchan_addr": "teller@xyz.macgirvin.com", + "xchan_url": "https://xyz.macgirvin.com/channel/teller", + "xchan_connurl": "https://xyz.macgirvin.com/poco/teller", + "xchan_follow": "https://xyz.macgirvin.com/follow?f=&url=%s", + "xchan_connpage": "", + "xchan_name": "Teller", + "xchan_network": "zot", + "xchan_instance_url": "", + "xchan_flags": "0", + "xchan_photo_date": "2016-10-19 01:26:50", + "xchan_name_date": "2016-01-02 21:16:26", + "xchan_hidden": "0", + "xchan_orphan": "0", + "xchan_censored": "0", + "xchan_selfcensored": "0", + "xchan_system": "0", + "xchan_pubforum": "0", + "xchan_deleted": "0" + }, + { + "id": "12", + "uid": "2", + "gid": "1", + "xchan": "xuSMUYxw1djBB97qXsbrBN1nzJH_gFwQL6pS4zIy8fuusOfBxNlMiVb4h_q5tOEvpE7tYf1EsryjNciMuPIj5w", + "abook_id": "24", + "abook_account": "1", + "abook_channel": "2", + "abook_xchan": "xuSMUYxw1djBB97qXsbrBN1nzJH_gFwQL6pS4zIy8fuusOfBxNlMiVb4h_q5tOEvpE7tYf1EsryjNciMuPIj5w", + "abook_my_perms": "218555", + "abook_their_perms": "218555", + "abook_closeness": "80", + "abook_created": "2016-01-27 00:48:43", + "abook_updated": "2016-12-04 17:16:58", + "abook_connected": "2016-12-04 17:16:58", + "abook_dob": "0001-01-01 00:00:00", + "abook_flags": "0", + "abook_blocked": "0", + "abook_ignored": "0", + "abook_hidden": "0", + "abook_archived": "0", + "abook_pending": "0", + "abook_unconnected": "0", + "abook_self": "0", + "abook_feed": "0", + "abook_profile": "debb5236efb1626cfbad33ccb49892801e5f844aa04bf81f580cfa7d13204819", + "abook_incl": "", + "abook_excl": "", + "abook_instance": "", + "xchan_hash": "xuSMUYxw1djBB97qXsbrBN1nzJH_gFwQL6pS4zIy8fuusOfBxNlMiVb4h_q5tOEvpE7tYf1EsryjNciMuPIj5w", + "xchan_guid": "d5EMLlt1tHHZ0dANoA7B5Wq9UgXoWcFS9-gXOkL_AAejcPApoQRyxfHTuu8DoTbUaO-bYmX5HPuWuK9PHyqNmA", + "xchan_guid_sig": "CVWEMRPtzI1YcHfnnWHTuv3H964OAmSElgUfxMoX6RdQdxNpqb_POirpVuyP8s3W17mVCfO5V9IAjkg5iKcqCk6YcvOD_egmMy-AnM9TC1kKndQHw55CunD82Q8K_xBNSXkSROizcNkKh9DVLjJPFjW1AqtI4njkZ3EMgrWqnbFRM1qPToUoCY9zM3tEMHoAD9YX1zP90wl40LzfN-dtcNWpSBbiz9owou62uzLbN7mrCwKOMlXLjwwGswRnxIsEnb3O-FXOs8hs0mArKe9snq1-BKeD16LyzxgwlpVLElzIJZGEZGtMdIJgeRzKuBvPjsOIpQ1yAkuOpFJ3nGCM-IPOIIjAmyVl5zD3xPVcxxpZlJRn5fG1Y-gnqTgsrEQCA7M6XPWQdrdHU4akZfyUyFJDhv3uM-jon9VzrYTBw68R0WA-1Z8WafEHA4qh5OWAj85lUarwhr7iTiEckH51ypPCPs6VbT6Pw7yMaxfjFOcipashQagx0tfOlDhE5dQANOXKASFtH1J9-CZY2MQdLPQ6u54d5whuHKMGaJ0V68pnmZ2rOn7g344Ah2WCJrm17jj60QsRMorqRFj7GMdPIA1XB8Wrk88MuYOe3Dhyuu6ZWKI7YTWJS690ZVkKUqAiNHqj0W86DtaiPUc_mmGR0fHl4Gksnko3WmCFv9q2X2E", + "xchan_pubkey": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAoj2xCJktBA8Ww7Hp+ZNL\nrNuQpo8UB/bfvRkIy+yua3xpF1TuXcnAH61kyRz8vXgOu/l2CyxQbIoaGslCV5Sy\n8JKeNXe+IilUdSSEjMIwCPfSPsYnMHsSnHWmPmclvJwEtQUKOZmW5mMuVBvXy7D2\njomFwc69AYphdyys6eQ7Dcn6+FRBiQbyMprZ5lxyVW+O4DuXVNa3ej2ebx0gCJZ4\ntTIlBoKwEey91dY+FyKVFjdwfNczpmL7LgmZXqcVx+MG3mYgibwdVMiXVj5X06cs\nV9hJ5Xi+Aklsv/UWJtjw9FVt7y9TLptnhh4Ra6T/MDmnBBIAkOR7P/X8cRv078MT\nl0IMsP0RJcDEtTLtwHFVtDs6p52KDFqclKWbqmxmxqV3OTPVYtArRGIzgnJi/5ur\nHRr5G6Cif7QY3UowsIOf78Qvy28LwSbdymgBAWwPPKIviXWxGO+9kMWdmPSUQrWy\nK0+7YA9P9fBUFfn9Hc+p8SJQmQ6OAqLwrDGiPSOlGaNrbEqwqLGgIpXwK+lEFcFJ\n3SPOjJRWdR2whlMxvpwX+39+H7dWN3vSa3Al4/Sq7qW8yW2rYwf+eGyp4Z0lRR+8\nJxFMCwZkSw5g14YdlikAPojv5V1c6KuA5ieg8G1hwyONV7A4JHPyEdPt0W0TZi6C\nCOVkPaC3xGrguETZpJfVpwUCAwEAAQ==\n-----END PUBLIC KEY-----\n", + "xchan_photo_mimetype": "image/png", + "xchan_photo_l": "https://xyz.macgirvin.com/photo/9da63aa910ea14e1501ee1a749d181a6-4", + "xchan_photo_m": "https://xyz.macgirvin.com/photo/9da63aa910ea14e1501ee1a749d181a6-5", + "xchan_photo_s": "https://xyz.macgirvin.com/photo/9da63aa910ea14e1501ee1a749d181a6-6", + "xchan_addr": "cloner@xyz.macgirvin.com", + "xchan_url": "http://abc.macgirvin.com/channel/cloner", + "xchan_connurl": "http://abc.macgirvin.com/poco/cloner", + "xchan_follow": "https://xyz.macgirvin.com/follow?f=&url=%s", + "xchan_connpage": "", + "xchan_name": "Karen", + "xchan_network": "zot", + "xchan_instance_url": "", + "xchan_flags": "0", + "xchan_photo_date": "2016-03-31 19:59:20", + "xchan_name_date": "2016-01-26 23:23:42", + "xchan_hidden": "0", + "xchan_orphan": "0", + "xchan_censored": "0", + "xchan_selfcensored": "0", + "xchan_system": "0", + "xchan_pubforum": "0", + "xchan_deleted": "0" + } + + ] + + +xchan +================================================================================ + +An xchan is a global location independent channel and is the primary record for a network +identity. It may refer to channels on other websites, networks, or services. + +`GET /api/z/1.0/xchan` + +Required: one of [ address, hash, guid ] as GET parameters + +Returns a portable xchan structure + +Example: https://xyz.macgirvin.com/api/z/1.0/xchan?f=&address=mike@macgirvin.com + +Returns: + + { + "hash": "jr54M_y2l5NgHX5wBvP0KqWcAHuW23p1ld-6Vn63_pGTZklrI36LF8vUHMSKJMD8xzzkz7s2xxCx4-BOLNPaVA", + "guid": "sebQ-IC4rmFn9d9iu17m4BXO-kHuNutWo2ySjeV2SIW1LzksUkss12xVo3m3fykYxN5HMcc7gUZVYv26asx-Pg", + "guid_sig": "Llenlbl4zHo6-g4sa63MlQmTP5dRCrsPmXHHFmoCHG63BLq5CUZJRLS1vRrrr_MNxr7zob_Ykt_m5xPKe5H0_i4pDj-UdP8dPZqH2fqhhx00kuYL4YUMJ8gRr5eO17vsZQ3XxTcyKewtgeW0j7ytwMp6-hFVUx_Cq08MrXas429ZrjzaEwgTfxGnbgeQYQ0R5EXpHpEmoERnZx77VaEahftmdjAUx9R4YKAp13pGYadJOX5xnLfqofHQD8DyRHWeMJ4G1OfWPSOlXfRayrV_jhnFlZjMU7vOdQwHoCMoR5TFsRsHuzd-qepbvo3pzvQZRWnTNu6oPucgbf94p13QbalYRpBXKOxdTXJrGdESNhGvhtaZnpT9c1QVqC46jdfP0LOX2xrVdbvvG2JMWFv7XJUVjLSk_yjzY6or2VD4V6ztYcjpCi9d_WoNHruoxro_br1YO3KatySxJs-LQ7SOkQI60FpysfbphNyvYMkotwUFI59G08IGKTMu3-GPnV1wp7NOQD1yzJbGGEGSEEysmEP0SO9vnN45kp3MiqbffBGc1r4_YM4e7DPmqOGM94qksOcLOJk1HNESw2dQYWxWQTBXPfOJT6jW9_crGLMEOsZ3Jcss0XS9KzBUA2p_9osvvhUKuKXbNztqH0oZIWlg37FEVsDs_hUwUJpv2Ar09k4", + "pubkey": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA7QCwvuEIwCHjhjbpz3Oc\ntyei/Pz9nDksNbsc44Cm8jxYGMXsTPFXDZYCcCB5rcAhPPdZSlzaPkv4vPVcMIrw\n5cdX0tvbwa3rNTng6uFE7qkt15D3YCTkwF0Y9FVZiZ2Ko+G23QeBt9wqb9dlDN1d\nuPmu9BLYXIT/JXoBwf0vjIPFM9WBi5W/EHGaiuqw7lt0qI7zDGw77yO5yehKE4cu\n7dt3SakrXphL70LGiZh2XGoLg9Gmpz98t+gvPAUEotAJxIUqnoiTA8jlxoiQjeRK\nHlJkwMOGmRNPS33awPos0kcSxAywuBbh2X3aSqUMjcbE4cGJ++/13zoa6RUZRObC\nZnaLYJxqYBh13/N8SfH7d005hecDxWnoYXeYuuMeT3a2hV0J84ztkJX5OoxIwk7S\nWmvBq4+m66usn6LNL+p5IAcs93KbvOxxrjtQrzohBXc6+elfLVSQ1Rr9g5xbgpub\npSc+hvzbB6p0tleDRzwAy9X16NI4DYiTj4nkmVjigNo9v2VPnAle5zSam86eiYLO\nt2u9YRqysMLPKevNdj3CIvst+BaGGQONlQalRdIcq8Lin+BhuX+1TBgqyav4XD9K\nd+JHMb1aBk/rFLI9/f2S3BJ1XqpbjXz7AbYlaCwKiJ836+HS8PmLKxwVOnpLMbfH\nPYM8k83Lip4bEKIyAuf02qkCAwEAAQ==\n-----END PUBLIC KEY-----\n", + "photo_mimetype": "image/jpeg", + "photo_l": "https://xyz.macgirvin.com/photo/350b74555c04429148f2e12775f6c403-4", + "photo_m": "https://xyz.macgirvin.com/photo/350b74555c04429148f2e12775f6c403-5", + "photo_s": "https://xyz.macgirvin.com/photo/350b74555c04429148f2e12775f6c403-6", + "address": "mike@macgirvin.com", + "url": "https://macgirvin.com/channel/mike", + "connurl": "https://macgirvin.com/poco/mike", + "follow": "https://macgirvin.com/follow?f=&url=%s", + "connpage": "https://macgirvin.com/connect/mike", + "name": "Mike Macgirvin", + "network": "zot", + "instance_url": "", + "flags": "0", + "photo_date": "2012-12-06 05:06:11", + "name_date": "2012-12-06 04:59:13", + "hidden": "1", + "orphan": "0", + "censored": "0", + "selfcensored": "0", + "system": "0", + "pubforum": "0", + "deleted": "0" + } + +item/update +================================================================================ + +Create or update an item (post, activity, webpage, etc.) + +Usage: `POST /api/z/1.0/item/update` + +Description: item/update posts an item (typically a conversation item or post, but can be any item) using form input. + + +Required: + +- body + + text/bbcode contents by default. + + +Optional: + +- $_FILES['media'] + + uploaded media file to include with post + +- title + + title of post/item + +- contact_allow + + array of xchan.xchan_hash allowed to view this item + +- group_allow + + array of group.hash allowed to view this item + +- contact_deny + + array of xchan.xchan_hash not allowed to view this item + +- group_deny + + array of group.hash not allowed to view this item + +- coord + + geographic coordinates + +- location + + freefrom location + +- expire + + datetime this post will expire or be removed + +- mimetype + + mimetype if not text/bbcode + +- parent + + item.id of parent to this post (makes it a comment) + +- parent_mid + + alternate form of parent using message_id + +- remote_xchan + + xchan.xchan_hash of this message author if not the channel owner + +- consensus + + boolean set to true if this is a consensus or voting item (default false) + +- nocomment + + boolean set to true if comments are to be disabled (default false) + +- origin + + do not use this without reading the code + +- namespace + + persistent identity for a remote network or service + +- remote_id + + message_id of this resource on a remote network or service + +- message_id + + message_id of this item (leave unset to generate one) + +- created + + datetime of message creation + +- post_id + + existing item.id if this is an edit operation + +- app + + application or network name to display with item + +- categories + + comma separated categories for this item + +- webpage + + item.page_type if not 0 + +- pagetitle + + for webpage and design elements, the 'page name' + +- layout_mid + + item.mid of layout for this design element + +- plink + + permalink for this item if different than the default + +- verb + + activitystream verb for this item/activity + +- obj_type + + activitystream object type for this item/activity + + + +Example: + + curl -u mychannel:mypassword https://xyz.macgirvin.com/api/z/1.0/item/update -d body="hello world" + + +Returns: + + + { + + "success": true, + "item_id": "2245", + "item": { + "id": "2245", + "mid": "14135cdecf6b8e3891224e4391748722114da6668eebbcb56fe4667b60b88249@xyz.macgirvin.com", + "aid": "1", + "uid": "2", + "parent": "2245", + "parent_mid": "14135cdecf6b8e3891224e4391748722114da6668eebbcb56fe4667b60b88249@xyz.macgirvin.com", + "thr_parent": "14135cdecf6b8e3891224e4391748722114da6668eebbcb56fe4667b60b88249@xyz.macgirvin.com", + "created": "2016-12-03 20:00:12", + "edited": "2016-12-03 20:00:12", + "expires": "0001-01-01 00:00:00", + "commented": "2016-12-03 20:00:12", + "received": "2016-12-03 20:00:12", + "changed": "2016-12-03 20:00:12", + "comments_closed": "0001-01-01 00:00:00", + "owner_xchan": "pgcJx1IQjuPkx8aI9qheJlBMZzJz-oTPjHy3h5pWlOVOriBO_cSiUhhqwhuZ74TYJ8_ECO3pPiRMWC0q8YPCQg", + "author_xchan": "pgcJx1IQjuPkx8aI9qheJlBMZzJz-oTPjHy3h5pWlOVOriBO_cSiUhhqwhuZ74TYJ8_ECO3pPiRMWC0q8YPCQg", + "source_xchan": "", + "mimetype": "text/bbcode", + "title": "", + "body": "hello world", + "html": "", + "app": "", + "lang": "", + "revision": "0", + "verb": "http://activitystrea.ms/schema/1.0/post", + "obj_type": "http://activitystrea.ms/schema/1.0/note", + "obj": "", + "tgt_type": "", + "target": "", + "layout_mid": "", + "postopts": "", + "route": "", + "llink": "https://xyz.macgirvin.com/display/14135cdecf6b8e3891224e4391748722114da6668eebbcb56fe4667b60b88249@xyz.macgirvin.com", + "plink": "https://xyz.macgirvin.com/channel/mychannel/?f=&mid=14135cdecf6b8e3891224e4391748722114da6668eebbcb56fe4667b60b88249@xyz.macgirvin.com", + "resource_id": "", + "resource_type": "", + "attach": "", + "sig": "sa4TOQNfHtV13HDZ1tuQGWNBpZp-nWhT2GMrZEmelXxa_IvEepD2SEsCTWOBqM8OKPJLfNy8_i-ORXjrOIIgAa_aT8cw5vka7Q0C8L9eEb_LegwQ_BtH0CXO5uT30e_8uowkwzh6kmlVg1ntD8QqrGgD5jTET_fMQOIw4gQUBh40GDG9RB4QnPp_MKsgemGrADnRk2vHO7-bR32yQ0JI-8G-eyeqGaaJmIwkHoi0vXsfjZtU7ijSLuKEBWboNjKEDU89-vQ1c5Kh1r0pmjiDk-a5JzZTYShpuhVA-vQgEcADA7wkf4lJZCYNwu3FRwHTvhSMdF0nmyv3aPFglQDky38-SAXZyQSvd7qlABHGCVVDmYrYaiq7Dh4rRENbAUf-UJFHPCVB7NRg34R8HIqmOKq1Su99bIWaoI2zuAQEVma9wLqMoFsluFhxX58KeVtlCZlro7tZ6z619-dthS_fwt0cL_2dZ3QwjG1P36Q4Y4KrCTpntn9ot5osh-HjVQ01h1I9yNCj6XPgYJ8Im3KT_G4hmMDFM7H9RUrYLl2o9XYyiS2nRrf4aJHa0UweBlAY4zcQG34bw2AMGCY53mwsSArf4Hs3rKu5GrGphuwYX0lHa7XEKMglwBWPWHI49q7-oNWr7aWwn1FnfaMfl4cQppCMtKESMNRKm_nb9Dsh5e0", + "diaspora_meta": "", + "location": "", + "coord": "", + "public_policy": "", + "comment_policy": "contacts", + "allow_cid": "", + "allow_gid": "", + "deny_cid": "", + "deny_gid": "", + "item_restrict": "0", + "item_flags": "0", + "item_private": "0", + "item_origin": "1", + "item_unseen": "0", + "item_starred": "0", + "item_uplink": "0", + "item_consensus": "0", + "item_wall": "1", + "item_thread_top": "1", + "item_notshown": "0", + "item_nsfw": "0", + "item_relay": "0", + "item_mentionsme": "0", + "item_nocomment": "0", + "item_obscured": "0", + "item_verified": "1", + "item_retained": "0", + "item_rss": "0", + "item_deleted": "0", + "item_type": "0", + "item_hidden": "0", + "item_unpublished": "0", + "item_delayed": "0", + "item_pending_remove": "0", + "item_blocked": "0" + } + + } + +item/full +================================================================================ + +Get all data associated with an item + +abook +================================================================================ + +Connections + +abconfig +================================================================================ + +Connection metadata (such as permissions) + +perm_allowed +================================================================================ + +Check a permission for a given xchan -- cgit v1.2.3 From c989a94916c8428f71aa52e12dd02b376f85aa3a Mon Sep 17 00:00:00 2001 From: Andrew Manning Date: Thu, 8 Dec 2016 20:33:03 -0500 Subject: Convert consolidated pages back to BBcode and Markdown where possible --- doc/developer/developer_guide.html | 470 ------------------------------------- doc/developer/developer_guide.md | 422 +++++++++++++++++++++++++++++++++ 2 files changed, 422 insertions(+), 470 deletions(-) delete mode 100644 doc/developer/developer_guide.html create mode 100644 doc/developer/developer_guide.md (limited to 'doc/developer') diff --git a/doc/developer/developer_guide.html b/doc/developer/developer_guide.html deleted file mode 100644 index 77d622221..000000000 --- a/doc/developer/developer_guide.html +++ /dev/null @@ -1,470 +0,0 @@ -

Who is a Hubzilla developer? Should I read this?

- -

Anyone who contributes to making Hubzilla better is a developer. There are many different and important ways you can contribute to this amazing technology, even if you do not know how to write code. The software itself is only a part of the Hubzilla project. You can contribute by

- -
  • translating text to your language so that people around the world have the opportunity to use Hubzilla
    • -
  • promoting Hubzilla and spreading awareness of the platform through blog posts, articles, and word-of-mouth
    • -
  • creating artwork and graphics for project assets such as icons and marketing material
    • -
  • supporting project infrastructure like the project website and demo servers
    • -

Software developers are of course welcomed; there are so many great ideas to implement and not enough people to make them all a reality! The Hubzilla code base is an advanced and mature system, but the platform is still very flexible and responsive to new ideas.

- -

This document will help you get started learning and contributing to Hubzilla.

- -

Versioning system

- -

The versioning system is similar to the popular semantic versioning but less stringent. Given x.y.z, x changes yearly. y changes for "stable" monthly builds, and z increments when there are interface changes. We maintain our date and build numbers for medium grain version control (commits within a certain date range) and of course git revs for fine grained control.

- -

Git repository branches

- -

There are two official branches of the Hubzilla git repo.

- -
  • The stable version is maintained on the master branch. The latest commit in this branch is considered to be suitable for production hubs.
    • -
  • Experimental development occurs on the dev branch, which is merged into master when it is deemed tested and stable enough.
    • -

Developer tools and workflows

- -

Hub Snapshots

- -

The Hub Snapshots page provides instructions and scripts for taking complete -snapshots of a hub to support switching between consistent and completely known -states. This is useful to prevent situations where the content or database schema -might be incompatible with the code.

- -

Translations

- -

Our translations are managed through Transifex. If you wish to help out translating Hubzilla to another language, sign up on transifex.com, visit https://www.transifex.com/projects/p/red-matrix/ and request to join one of the existing language teams or create a new one. Notify one of the core developers when you have a translation update which requires merging, or ask about merging it yourself if you're comfortable with git and PHP. We have a string file called 'messages.po' which is gettext compliant and a handful of email templates, and from there we automatically generate the application's language files.

- -

Translation Process

- -

The strings used in the UI of Hubzilla is translated at [Transifex][1] and then -included in the git repository at github. If you want to help with translation -for any language, be it correcting terms or translating Hubzilla to a -currently not supported language, please register an account at transifex.com -and contact the Redmatrix translation team there.

- -

Translating Hubzilla is simple. Just use the online tool at transifex. If you -don't want to deal with git & co. that is fine, we check the status of the -translations regularly and import them into the source tree at github so that -others can use them.

- -

We do not include every translation from transifex in the source tree to avoid -a scattered and disturbed overall experience. As an uneducated guess we have a -lower limit of 50% translated strings before we include the language. This -limit is judging only by the amount of translated strings under the assumption -that the most prominent strings for the UI will be translated first by a -translation team. If you feel your translation useable before this limit, -please contact us and we will probably include your teams work in the source -tree.

- -

If you want to get your work into the source tree yourself, feel free to do so -and contact us with and question that arises. The process is simple and -Hubzilla ships with all the tools necessary.

- -

The location of the translated files in the source tree is - /view/LNG-CODE/ -where LNG-CODE is the language code used, e.g. de for German or fr for French. -For the email templates (the *.tpl files) just place them into the directory -and you are done. The translated strings come as a "hmessages.po" file from -transifex which needs to be translated into the PHP file Hubzilla uses. To do -so, place the file in the directory mentioned above and use the "po2php" -utility from the util directory of your Hubzilla installation.

- -

Assuming you want to convert the German localization which is placed in -view/de/hmessages.po you would do the following.

- -

  1. Navigate at the command prompt to the base directory of your -Hubzilla installation

    2. -

  2. Execute the po2php script, which will place the translation -in the hstrings.php file that is used by Hubzilla.

    - -

    $> php util/po2php.php view/de/hmessages.po

    - -

    The output of the script will be placed at view/de/hstrings.php where -froemdoca os expecting it, so you can test your translation mmediately.

    3. -

  3. Visit your Hubzilla page to check if it still works in the language you -just translated. If not try to find the error, most likely PHP will give -you a hint in the log/warnings.about the error.

    - -

    For debugging you can also try to "run" the file with PHP. This should -not give any output if the file is ok but might give a hint for -searching the bug in the file.

    - -

    $> php view/de/hstrings.php

    4. -

  4. commit the two files with a meaningful commit message to your git -repository, push it to your fork of the Hubzilla repository at github and -issue a pull request for that commit.

    5. -

Utilities

- -

Additional to the po2php script there are some more utilities for translation -in the "util" directory of the Hubzilla source tree. If you only want to -translate Hubzilla into another language you wont need any of these tools most -likely but it gives you an idea how the translation process of Hubzilla -works.

- -

For further information see the utils/README file.

- -

Known Problems

- -
  • Hubzilla uses the language setting of the visitors browser to determain the -language for the UI. Most of the time this works, but there are some known -quirks.
    • -
  • the early translations are based on the friendica translations, if you -some rough translations please let us know or fix them at Transifex.
    • -

To-be-organized information

- -

Here is how you can join us.

- -

First, get yourself a working git package on the system where you will be -doing development.

- -

Create your own github account.

- -

You may fork/clone the Red repository from https://github.com/redmatrix/hubzilla.git.

- -

Follow the instructions provided here: http://help.github.com/fork-a-repo/ -to create and use your own tracking fork on github

- -

Then go to your github page and create a "Pull request" when you are ready -to notify us to merge your work.

- -

Important

- -

Please pull in any changes from the project repository and merge them with your work before issuing a pull request. We reserve the right to reject any patch which results in a large number of merge conflicts. This is especially true in the case of language translations - where we may not be able to understand the subtle differences between conflicting versions.

- -

Also - test your changes. Don't assume that a simple fix won't break something else. If possible get an experienced Red developer to review the code.

- -

Licensing

- -

All code contributed to the project falls under the MIT license, unless otherwise specified. We will accept third-party code which falls under MIT, BSD and LGPL, but copyleft licensing (GPL, and AGPL) is only permitted in addons. It must be possible to completely remove the GPL (copyleft) code from the main project without breaking anything.

- -

Coding Style

- -

In the interests of consistency we adopt the following code styling. We may accept patches using other styles, but where possible please try to provide a consistent code style. We aren't going to argue or debate the merits of this style, and it is irrelevant what project 'xyz' uses. This is not project 'xyz'. This is a baseline to try and keep the code readable now and in the future.

- -

  • All comments should be in English.

    • -

  • We use doxygen to generate documentation. This hasn't been consistently applied, but learning it and using it are highly encouraged.

    • -

  • Indentation is accomplished primarily with tabs using a tab-width of 4.

    • -

  • String concatenation and operators should be separated by whitespace. e.g. "$foo = $bar . 'abc';" instead of "$foo=$bar.'abc';"

    • -

  • Generally speaking, we use single quotes for string variables and double quotes for SQL statements. "Here documents" should be avoided. Sometimes using double quoted strings with variable replacement is the most efficient means of creating the string. In most cases, you should be using single quotes.

    • -

  • Use whitespace liberally to enhance readability. When creating arrays with many elements, we will often set one key/value pair per line, indented from the parent line appropriately. Lining up the assignment operators takes a bit more work, but also increases readability.

    • -

  • Generally speaking, opening braces go on the same line as the thing which opens the brace. They are the last character on the line. Closing braces are on a line by themselves.

    • -

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

- -

[library] Third party modules (must be license compatible)

- -

[mod] Controller modules based on URL pathname (e.g. #^[url=http://sitename/foo]http://sitename/foo[/url] loads mod/foo.php)

- -

[mod/site/] site-specific mod overrides, excluded from git

- -

[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:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TableDescription
abconfigcontact table, replaces Friendica 'contact'
abook
accountservice provider account
addon
addressbookchanges
addressbooks
app
atoken
attach
auth_codes
cache
cal
calendarchanges
calendarinstances
calendarobjects
calendars
calendarsubscriptions
cards
channel
chat
chatpresence
chatroom
clients
config
conv
dreport
event
group_member
groupmembers
groups
hook
hubloc
iconfig
issue
item
item_id
likes
locks
mail
menu
menu_item
notify
obj
outq
pconfigpersonal (per channel) configuration storage
photo
poll
poll_elm
principals
profdef
profext
profile
profile_check
propertystorage
register
schedulingobjects
session
shares
sign
site
source
sys_perms
term
tokens
updates
users
verify
vote
xchan
xchat
xconfig
xign
xlink
xperm
xprof
xtag
* abook - contact table, replaces Friendica 'contact'
-* account - service provider account
-* addon - registered plugins
-* app - peronal app data
-* attach - file attachments
-* auth_codes - OAuth usage
-* cache - OEmbed cache
-* channel - replaces Friendica 'user'
-* chat - chat room content
-* chatpresence - channel presence information for chat
-* chatroom - data for the actual chat room
-* clients - OAuth usage
-* config - main configuration storage
-* conv - Diaspora private messages
-* event - Events
-* fcontact - friend suggestion stuff
-* ffinder - friend suggestion stuff
-* fserver - obsolete
-* fsuggest - friend suggestion stuff
-* groups - privacy groups
-* group_member - privacy groups
-* hook - plugin hook registry
-* hubloc - Red location storage, ties a location to an xchan
-* item - posts
-* item_id - other identifiers on other services for posts
-* likes - likes of 'things'
-* mail - private messages
-* menu - channel menu data
-* menu_item - items uses by channel menus
-* notify - notifications
-* notify-threads - need to factor this out and use item thread info on notifications
-* obj - object data for things (x has y)
-* outq - output queue
-* pconfig - personal (per channel) configuration storage
-* photo - photo storage
-* poll - data for polls
-* poll_elm - data for poll elements
-* profdef - custom profile field definitions
-* profext - custom profile field data
-* profile - channel profiles
-* profile_check - DFRN remote auth use, may be obsolete
-* register - registrations requiring admin approval
-* session - web session storage
-* shares - shared item information
-* sign - Diaspora signatures.  To be phased out.
-* site - site table to find directory peers
-* source - channel sources data
-* spam - unfinished
-* sys_perms - extensible permissions for the sys channel
-* term - item taxonomy (categories, tags, etc.) table
-* tokens - OAuth usage
-* updates - directory sync updates
-* verify - general purpose verification structure
-* vote - vote data for polls
-* xchan - replaces 'gcontact', list of known channels in the universe
-* xchat - bookmarked chat rooms
-* xconfig - as pconfig but for channels with no local account
-* 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 Hubzilla

- -

This is a short documentation on what I found while trying to modify Hubzilla'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 .

- -

Oh, and don't forget to rename the _init function in /php/theme.php to be _init() instead of redbasic_init().

- -

At that point, if you need to add javascript or css files, add them to /js or /css, and then "register" them in _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//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.

- -

We're pretty relaxed when it comes to developers. We don't have a lot of rules. Some of us are over-worked and if you want to help we're happy to let you help. That said, attention to a few guidelines will make the process smoother and make it easier to work together. We have developers from across the globe with different abilities and different cultural backgrounds and different levels of patience. Our primary rule is to respect others. Sometimes this is hard and sometimes we have very different opinions of how things should work, but if everybody makes an effort, we'll get along just fine.

- -

Here is how you can join us.

- -

First, get yourself a working git package on the system where you will be -doing development.

- -

Create your own github account.

- -

You may fork/clone the Red repository from [url=https://github.com/redmatrix/hubzilla.git]https://github.com/redmatrix/hubzilla.git[/url]

- -

Follow the instructions provided here: [url=http://help.github.com/fork-a-repo/]http://help.github.com/fork-a-repo/[/url] -to create and use your own tracking fork on github

- -

Then go to your github page and create a "Pull request" when you are ready -to notify us to merge your work.

- -

Translations

- -

Our translations are managed through Transifex. If you wish to help out translating the $Projectname to another language, sign up on transifex.com, visit [url=https://www.transifex.com/projects/p/red-matrix/]https://www.transifex.com/projects/p/red-matrix/[/url] and request to join one of the existing language teams or create a new one. Notify one of the core developers when you have a translation update which requires merging, or ask about merging it yourself if you're comfortable with git and PHP. We have a string file called 'messages.po' which is gettext compliant and a handful of email templates, and from there we automatically generate the application's language files.

- -

Important

- -

Please pull in any changes from the project repository and merge them with your work before issuing a pull request. We reserve the right to reject any patch which results in a large number of merge conflicts. This is especially true in the case of language translations - where we may not be able to understand the subtle differences between conflicting versions.

- -

Also - test your changes. Don't assume that a simple fix won't break something else. If possible get an experienced Red developer to review the code.

- -

Further documentation can be found at the Github wiki pages at: [url=https://github.com/friendica/red/wiki]https://github.com/friendica/red/wiki[/url]

- -

Licensing

- -

All code contributed to the project falls under the MIT license, unless otherwise specified. We will accept third-party code which falls under MIT, BSD and LGPL, but copyleft licensing (GPL, and AGPL) is only permitted in addons. It must be possible to completely remove the GPL (copyleft) code from the main project without breaking anything.

- -

Concensus Building

- -

Code changes which fix an obvious bug are pretty straight-forward. For instance if you click "Save" and the thing you're trying to save isn't saved, it's fairly obvious what the intended behaviour should be. Often when developing feature requests, it may affect large numbers of community members and it's possible that other members of the community won't agree with the need for the feature, or with your proposed implementation. They may not see something as a bug or a desirable feature.

- -

We encourage consensus building within the community when it comes to any feature which might be considered controversial or where there isn't unanimous decision that the proposed feature is the correct way to accomplish the task. The first place to pitch your ideas is to [url=https://zothub.com/channel/one]Channel One[/url]. Others may have some input or be able to point out facets of your concept which might be problematic in our environment. But also, you may encounter opposition to your plan. This doesn't mean you should stop and/or ignore the feature. Listen to the concerns of others and try and work through any implementation issues.

- -

There are places where opposition cannot be resolved. In these cases, please consider making your feature optional or non-default behaviour that must be specifically enabled. This technique can often be used when a feature has significant but less than unanimous support. Those who desire the feature can turn it on and those who don't want it - will leave it turned off.

- -

If a feature uses other networks or websites and or is only seen as desirable by a small minority of the community, consider making the functionality available via an addon or plugin. Once again, those who don't desire the feature won't need to install it. Plugins are relatively easy to create and "hooks" can be easily added or modified if the current hooks do not do what is needed to allow your plugin to work.

- -

Coding Style

- -

In the interests of consistency we adopt the following code styling. We may accept patches using other styles, but where possible please try to provide a consistent code style. We aren't going to argue or debate the merits of this style, and it is irrelevant what project 'xyz' uses. This is not project 'xyz'. This is a baseline to try and keep the code readable now and in the future.

- -

  • All comments should be in English.

    • -

  • We use doxygen to generate documentation. This hasn't been consistently applied, but learning it and using it are highly encouraged.

    • -

  • Indentation is accomplished primarily with tabs using a tab-width of 4.

    • -

  • String concatenation and operators should be separated by whitespace. e.g. "$foo = $bar . 'abc';" instead of "$foo=$bar.'abc';"

    • -

  • Generally speaking, we use single quotes for string variables and double quotes for SQL statements. "Here documents" should be avoided. Sometimes using double quoted strings with variable replacement is the most efficient means of creating the string. In most cases, you should be using single quotes.

    • -

  • Use whitespace liberally to enhance readability. When creating arrays with many elements, we will often set one key/value pair per line, indented from the parent line appropriately. Lining up the assignment operators takes a bit more work, but also increases readability.

    • -

  • Generally speaking, opening braces go on the same line as the thing which opens the brace. They are the last character on the line. Closing braces are on a line by themselves.

    • -

  • Some functions take arguments in argc/argv style like main() in C or function args in bash or Perl. Urls are broken up within a module. e.g, given "http://example.com/module/arg1/arg2", then $this->argc will be 3 (integer) and $this->argv will contain: [0] => 'module', [1] => 'arg1', [2] => 'arg2'. There will always be one argument. If provided a naked domain URL, $this->argv[0] is set to "home".

    • -
- \ No newline at end of file diff --git a/doc/developer/developer_guide.md b/doc/developer/developer_guide.md new file mode 100644 index 000000000..3c0f7294d --- /dev/null +++ b/doc/developer/developer_guide.md @@ -0,0 +1,422 @@ +## Who is a Hubzilla developer? Should I read this? + +Anyone who contributes to making Hubzilla better is a developer. There are many different and important ways you can contribute to this amazing technology, _even if you do not know how to write code_. The software itself is only a part of the Hubzilla project. You can contribute by + +* translating text to your language so that people around the world have the opportunity to use Hubzilla +* promoting Hubzilla and spreading awareness of the platform through blog posts, articles, and word-of-mouth +* creating artwork and graphics for project assets such as icons and marketing material +* supporting project infrastructure like the project website and demo servers + +_Software_ developers are of course welcomed; there are so many great ideas to implement and not enough people to make them all a reality! The Hubzilla code base is an advanced and mature system, but the platform is still very flexible and responsive to new ideas. + +This document will help you get started learning and contributing to Hubzilla. + +## Versioning system + +The versioning system is similar to the popular semantic versioning but less stringent. Given x.y.z, x changes yearly. y changes for "stable" monthly builds, and z increments when there are interface changes. We maintain our date and build numbers for medium grain version control (commits within a certain date range) and of course git revs for fine grained control. + +## Git repository branches + +There are two official branches of the Hubzilla git repo. + +* The stable version is maintained on the **master** branch. The latest commit in this branch is considered to be suitable for production hubs. +* Experimental development occurs on the **dev** branch, which is merged into **master** when it is deemed tested and stable enough. + +## Developer tools and workflows + +### Hub Snapshots + +The [[Hub Snapshots]] page provides instructions and scripts for taking complete +snapshots of a hub to support switching between consistent and completely known +states. This is useful to prevent situations where the content or database schema +might be incompatible with the code. + +## Translations + +Our translations are managed through Transifex. If you wish to help out translating Hubzilla to another language, sign up on transifex.com, visit [https://www.transifex.com/projects/p/red-matrix/](https://www.transifex.com/projects/p/red-matrix/) and request to join one of the existing language teams or create a new one. Notify one of the core developers when you have a translation update which requires merging, or ask about merging it yourself if you're comfortable with git and PHP. We have a string file called 'messages.po' which is gettext compliant and a handful of email templates, and from there we automatically generate the application's language files. + +### Translation Process + +The strings used in the UI of Hubzilla is translated at [Transifex][1] and then +included in the git repository at github. If you want to help with translation +for any language, be it correcting terms or translating Hubzilla to a +currently not supported language, please register an account at transifex.com +and contact the Redmatrix translation team there. + +Translating Hubzilla is simple. Just use the online tool at transifex. If you +don't want to deal with git & co. that is fine, we check the status of the +translations regularly and import them into the source tree at github so that +others can use them. + +We do not include every translation from transifex in the source tree to avoid +a scattered and disturbed overall experience. As an uneducated guess we have a +lower limit of 50% translated strings before we include the language. This +limit is judging only by the amount of translated strings under the assumption +that the most prominent strings for the UI will be translated first by a +translation team. If you feel your translation useable before this limit, +please contact us and we will probably include your teams work in the source +tree. + +If you want to get your work into the source tree yourself, feel free to do so +and contact us with and question that arises. The process is simple and +Hubzilla ships with all the tools necessary. + +The location of the translated files in the source tree is + /view/LNG-CODE/ +where LNG-CODE is the language code used, e.g. de for German or fr for French. +For the email templates (the *.tpl files) just place them into the directory +and you are done. The translated strings come as a "hmessages.po" file from +transifex which needs to be translated into the PHP file Hubzilla uses. To do +so, place the file in the directory mentioned above and use the "po2php" +utility from the util directory of your Hubzilla installation. + +Assuming you want to convert the German localization which is placed in +view/de/hmessages.po you would do the following. + +1. Navigate at the command prompt to the base directory of your + Hubzilla installation + +2. Execute the po2php script, which will place the translation + in the hstrings.php file that is used by Hubzilla. + + $> php util/po2php.php view/de/hmessages.po + + The output of the script will be placed at view/de/hstrings.php where + froemdoca os expecting it, so you can test your translation mmediately. + +3. Visit your Hubzilla page to check if it still works in the language you + just translated. If not try to find the error, most likely PHP will give + you a hint in the log/warnings.about the error. + + For debugging you can also try to "run" the file with PHP. This should + not give any output if the file is ok but might give a hint for + searching the bug in the file. + + $> php view/de/hstrings.php + +4. commit the two files with a meaningful commit message to your git + repository, push it to your fork of the Hubzilla repository at github and + issue a pull request for that commit. + +### Utilities + +Additional to the po2php script there are some more utilities for translation +in the "util" directory of the Hubzilla source tree. If you only want to +translate Hubzilla into another language you wont need any of these tools most +likely but it gives you an idea how the translation process of Hubzilla +works. + +For further information see the utils/README file. + +### Known Problems + +* Hubzilla uses the language setting of the visitors browser to determain the + language for the UI. Most of the time this works, but there are some known + quirks. +* the early translations are based on the friendica translations, if you + some rough translations please let us know or fix them at Transifex. + +## To-be-organized information + +**Here is how you can join us.** + +First, get yourself a working git package on the system where you will be +doing development. + +Create your own github account. + +You may fork/clone the Red repository from [https://github.com/redmatrix/hubzilla.git](https://github.com/redmatrix/hubzilla.git). + +Follow the instructions provided here: [http://help.github.com/fork-a-repo/](http://help.github.com/fork-a-repo/) +to create and use your own tracking fork on github + +Then go to your github page and create a "Pull request" when you are ready +to notify us to merge your work. + + +**Important** + +Please pull in any changes from the project repository and merge them with your work **before** issuing a pull request. We reserve the right to reject any patch which results in a large number of merge conflicts. This is especially true in the case of language translations - where we may not be able to understand the subtle differences between conflicting versions. + +Also - **test your changes**. Don't assume that a simple fix won't break something else. If possible get an experienced Red developer to review the code. + + +**Licensing** + +All code contributed to the project falls under the MIT license, unless otherwise specified. We will accept third-party code which falls under MIT, BSD and LGPL, but copyleft licensing (GPL, and AGPL) is only permitted in addons. It must be possible to completely remove the GPL (copyleft) code from the main project without breaking anything. + +**Coding Style** + +In the interests of consistency we adopt the following code styling. We may accept patches using other styles, but where possible please try to provide a consistent code style. We aren't going to argue or debate the merits of this style, and it is irrelevant what project 'xyz' uses. This is not project 'xyz'. This is a baseline to try and keep the code readable now and in the future. + +* All comments should be in English. + +* We use doxygen to generate documentation. This hasn't been consistently applied, but learning it and using it are highly encouraged. + +* Indentation is accomplished primarily with tabs using a tab-width of 4. + +* String concatenation and operators should be separated by whitespace. e.g. "$foo = $bar . 'abc';" instead of "$foo=$bar.'abc';" + +* Generally speaking, we use single quotes for string variables and double quotes for SQL statements. "Here documents" should be avoided. Sometimes using double quoted strings with variable replacement is the most efficient means of creating the string. In most cases, you should be using single quotes. + +* Use whitespace liberally to enhance readability. When creating arrays with many elements, we will often set one key/value pair per line, indented from the parent line appropriately. Lining up the assignment operators takes a bit more work, but also increases readability. + +* Generally speaking, opening braces go on the same line as the thing which opens the brace. They are the last character on the line. Closing braces are on a line by themselves. + + +**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 + +[library] Third party modules (must be license compatible) + +[mod] Controller modules based on URL pathname (e.g. #^[url=http://sitename/foo]http://sitename/foo[/url] loads mod/foo.php) + +[mod/site/] site-specific mod overrides, excluded from git + +[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:** + + +| Table | Description | +|-------------------------|--------------------------------------------------------| +| abconfig | contact table, replaces Friendica 'contact' | +| abook | | +| account | service provider account | +| addon | | +| addressbookchanges | | +| addressbooks | | +| app | | +| atoken | | +| attach | | +| auth_codes | | +| cache | | +| cal | | +| calendarchanges | | +| calendarinstances | | +| calendarobjects | | +| calendars | | +| calendarsubscriptions | | +| cards | | +| channel | | +| chat | | +| chatpresence | | +| chatroom | | +| clients | | +| config | | +| conv | | +| dreport | | +| event | | +| group_member | | +| groupmembers | | +| groups | | +| hook | | +| hubloc | | +| iconfig | | +| issue | | +| item | | +| item_id | | +| likes | | +| locks | | +| mail | | +| menu | | +| menu_item | | +| notify | | +| obj | | +| outq | | +| pconfig | personal (per channel) configuration storage | +| photo | | +| poll | | +| poll_elm | | +| principals | | +| profdef | | +| profext | | +| profile | | +| profile_check | | +| propertystorage | | +| register | | +| schedulingobjects | | +| session | | +| shares | | +| sign | | +| site | | +| source | | +| sys_perms | | +| term | | +| tokens | | +| updates | | +| users | | +| verify | | +| vote | | +| xchan | | +| xchat | | +| xconfig | | +| xign | | +| xlink | | +| xperm | | +| xprof | | +| xtag | | + + + * abook - contact table, replaces Friendica 'contact' + * account - service provider account + * addon - registered plugins + * app - peronal app data + * attach - file attachments + * auth_codes - OAuth usage + * cache - OEmbed cache + * channel - replaces Friendica 'user' + * chat - chat room content + * chatpresence - channel presence information for chat + * chatroom - data for the actual chat room + * clients - OAuth usage + * config - main configuration storage + * conv - Diaspora private messages + * event - Events + * fcontact - friend suggestion stuff + * ffinder - friend suggestion stuff + * fserver - obsolete + * fsuggest - friend suggestion stuff + * groups - privacy groups + * group_member - privacy groups + * hook - plugin hook registry + * hubloc - Red location storage, ties a location to an xchan + * item - posts + * item_id - other identifiers on other services for posts + * likes - likes of 'things' + * mail - private messages + * menu - channel menu data + * menu_item - items uses by channel menus + * notify - notifications + * notify-threads - need to factor this out and use item thread info on notifications + * obj - object data for things (x has y) + * outq - output queue + * pconfig - personal (per channel) configuration storage + * photo - photo storage + * poll - data for polls + * poll_elm - data for poll elements + * profdef - custom profile field definitions + * profext - custom profile field data + * profile - channel profiles + * profile_check - DFRN remote auth use, may be obsolete + * register - registrations requiring admin approval + * session - web session storage + * shares - shared item information + * sign - Diaspora signatures. To be phased out. + * site - site table to find directory peers + * source - channel sources data + * spam - unfinished + * sys_perms - extensible permissions for the sys channel + * term - item taxonomy (categories, tags, etc.) table + * tokens - OAuth usage + * updates - directory sync updates + * verify - general purpose verification structure + * vote - vote data for polls + * xchan - replaces 'gcontact', list of known channels in the universe + * xchat - bookmarked chat rooms + * xconfig - as pconfig but for channels with no local account + * 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 Hubzilla** + +This is a short documentation on what I found while trying to modify Hubzilla'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 . + +Oh, and don't forget to rename the _init function in /php/theme.php to be _init() instead of redbasic_init(). + +At that point, if you need to add javascript or css files, add them to /js or /css, and then "register" them in _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//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. + + +We're pretty relaxed when it comes to developers. We don't have a lot of rules. Some of us are over-worked and if you want to help we're happy to let you help. That said, attention to a few guidelines will make the process smoother and make it easier to work together. We have developers from across the globe with different abilities and different cultural backgrounds and different levels of patience. Our primary rule is to respect others. Sometimes this is hard and sometimes we have very different opinions of how things should work, but if everybody makes an effort, we'll get along just fine. + +**Here is how you can join us.** + +First, get yourself a working git package on the system where you will be +doing development. + +Create your own github account. + +You may fork/clone the Red repository from [url=https://github.com/redmatrix/hubzilla.git]https://github.com/redmatrix/hubzilla.git[/url] + +Follow the instructions provided here: [url=http://help.github.com/fork-a-repo/]http://help.github.com/fork-a-repo/[/url] +to create and use your own tracking fork on github + +Then go to your github page and create a "Pull request" when you are ready +to notify us to merge your work. + +**Translations** + +Our translations are managed through Transifex. If you wish to help out translating the $Projectname to another language, sign up on transifex.com, visit [url=https://www.transifex.com/projects/p/red-matrix/]https://www.transifex.com/projects/p/red-matrix/[/url] and request to join one of the existing language teams or create a new one. Notify one of the core developers when you have a translation update which requires merging, or ask about merging it yourself if you're comfortable with git and PHP. We have a string file called 'messages.po' which is gettext compliant and a handful of email templates, and from there we automatically generate the application's language files. + + +**Important** + +Please pull in any changes from the project repository and merge them with your work **before** issuing a pull request. We reserve the right to reject any patch which results in a large number of merge conflicts. This is especially true in the case of language translations - where we may not be able to understand the subtle differences between conflicting versions. + +Also - **test your changes**. Don't assume that a simple fix won't break something else. If possible get an experienced Red developer to review the code. + +Further documentation can be found at the Github wiki pages at: [url=https://github.com/friendica/red/wiki]https://github.com/friendica/red/wiki[/url] + +**Licensing** + +All code contributed to the project falls under the MIT license, unless otherwise specified. We will accept third-party code which falls under MIT, BSD and LGPL, but copyleft licensing (GPL, and AGPL) is only permitted in addons. It must be possible to completely remove the GPL (copyleft) code from the main project without breaking anything. + +**Concensus Building** + +Code changes which fix an obvious bug are pretty straight-forward. For instance if you click "Save" and the thing you're trying to save isn't saved, it's fairly obvious what the intended behaviour should be. Often when developing feature requests, it may affect large numbers of community members and it's possible that other members of the community won't agree with the need for the feature, or with your proposed implementation. They may not see something as a bug or a desirable feature. + +We encourage consensus building within the community when it comes to any feature which might be considered controversial or where there isn't unanimous decision that the proposed feature is the correct way to accomplish the task. The first place to pitch your ideas is to [url=https://zothub.com/channel/one]Channel One[/url]. Others may have some input or be able to point out facets of your concept which might be problematic in our environment. But also, you may encounter opposition to your plan. This doesn't mean you should stop and/or ignore the feature. Listen to the concerns of others and try and work through any implementation issues. + +There are places where opposition cannot be resolved. In these cases, please consider making your feature **optional** or non-default behaviour that must be specifically enabled. This technique can often be used when a feature has significant but less than unanimous support. Those who desire the feature can turn it on and those who don't want it - will leave it turned off. + +If a feature uses other networks or websites and or is only seen as desirable by a small minority of the community, consider making the functionality available via an addon or plugin. Once again, those who don't desire the feature won't need to install it. Plugins are relatively easy to create and "hooks" can be easily added or modified if the current hooks do not do what is needed to allow your plugin to work. + + +**Coding Style** + +In the interests of consistency we adopt the following code styling. We may accept patches using other styles, but where possible please try to provide a consistent code style. We aren't going to argue or debate the merits of this style, and it is irrelevant what project 'xyz' uses. This is not project 'xyz'. This is a baseline to try and keep the code readable now and in the future. + +* All comments should be in English. + +* We use doxygen to generate documentation. This hasn't been consistently applied, but learning it and using it are highly encouraged. + +* Indentation is accomplished primarily with tabs using a tab-width of 4. + +* String concatenation and operators should be separated by whitespace. e.g. "$foo = $bar . 'abc';" instead of "$foo=$bar.'abc';" + +* Generally speaking, we use single quotes for string variables and double quotes for SQL statements. "Here documents" should be avoided. Sometimes using double quoted strings with variable replacement is the most efficient means of creating the string. In most cases, you should be using single quotes. + +* Use whitespace liberally to enhance readability. When creating arrays with many elements, we will often set one key/value pair per line, indented from the parent line appropriately. Lining up the assignment operators takes a bit more work, but also increases readability. + +* Generally speaking, opening braces go on the same line as the thing which opens the brace. They are the last character on the line. Closing braces are on a line by themselves. + +* Some functions take arguments in argc/argv style like main() in C or function args in bash or Perl. Urls are broken up within a module. e.g, given "http://example.com/module/arg1/arg2", then $this->argc will be 3 (integer) and $this->argv will contain: [0] => 'module', [1] => 'arg1', [2] => 'arg2'. There will always be one argument. If provided a naked domain URL, $this->argv[0] is set to "home". \ No newline at end of file -- cgit v1.2.3 From cafa5217ed3824c142b44b8b8e5bcb484ffea6fe Mon Sep 17 00:00:00 2001 From: Andrew Manning Date: Thu, 8 Dec 2016 21:41:04 -0500 Subject: Condense sticky nav TOC to h1 only. Add deep TOC to top of each page. Adjust developer guide headings. --- doc/developer/developer_guide.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'doc/developer') diff --git a/doc/developer/developer_guide.md b/doc/developer/developer_guide.md index 3c0f7294d..7ec76714f 100644 --- a/doc/developer/developer_guide.md +++ b/doc/developer/developer_guide.md @@ -1,4 +1,4 @@ -## Who is a Hubzilla developer? Should I read this? +# Who is a Hubzilla developer? Should I read this? Anyone who contributes to making Hubzilla better is a developer. There are many different and important ways you can contribute to this amazing technology, _even if you do not know how to write code_. The software itself is only a part of the Hubzilla project. You can contribute by @@ -11,31 +11,31 @@ _Software_ developers are of course welcomed; there are so many great ideas to i This document will help you get started learning and contributing to Hubzilla. -## Versioning system +# Versioning system The versioning system is similar to the popular semantic versioning but less stringent. Given x.y.z, x changes yearly. y changes for "stable" monthly builds, and z increments when there are interface changes. We maintain our date and build numbers for medium grain version control (commits within a certain date range) and of course git revs for fine grained control. -## Git repository branches +# Git repository branches There are two official branches of the Hubzilla git repo. * The stable version is maintained on the **master** branch. The latest commit in this branch is considered to be suitable for production hubs. * Experimental development occurs on the **dev** branch, which is merged into **master** when it is deemed tested and stable enough. -## Developer tools and workflows +# Developer tools and workflows -### Hub Snapshots +## Hub Snapshots The [[Hub Snapshots]] page provides instructions and scripts for taking complete snapshots of a hub to support switching between consistent and completely known states. This is useful to prevent situations where the content or database schema might be incompatible with the code. -## Translations +# Translations Our translations are managed through Transifex. If you wish to help out translating Hubzilla to another language, sign up on transifex.com, visit [https://www.transifex.com/projects/p/red-matrix/](https://www.transifex.com/projects/p/red-matrix/) and request to join one of the existing language teams or create a new one. Notify one of the core developers when you have a translation update which requires merging, or ask about merging it yourself if you're comfortable with git and PHP. We have a string file called 'messages.po' which is gettext compliant and a handful of email templates, and from there we automatically generate the application's language files. -### Translation Process +## Translation Process The strings used in the UI of Hubzilla is translated at [Transifex][1] and then included in the git repository at github. If you want to help with translation @@ -98,7 +98,7 @@ view/de/hmessages.po you would do the following. repository, push it to your fork of the Hubzilla repository at github and issue a pull request for that commit. -### Utilities +## Utilities Additional to the po2php script there are some more utilities for translation in the "util" directory of the Hubzilla source tree. If you only want to @@ -108,7 +108,7 @@ works. For further information see the utils/README file. -### Known Problems +## Known Problems * Hubzilla uses the language setting of the visitors browser to determain the language for the UI. Most of the time this works, but there are some known @@ -116,7 +116,7 @@ For further information see the utils/README file. * the early translations are based on the friendica translations, if you some rough translations please let us know or fix them at Transifex. -## To-be-organized information +# To-be-organized information **Here is how you can join us.** -- cgit v1.2.3 From 82d09c288d3bdf88facd6a4c82d2a309efd7d3a1 Mon Sep 17 00:00:00 2001 From: zotlabs Date: Fri, 9 Dec 2016 13:29:41 -0800 Subject: bring back a few of the doc edits from overlapping checkins --- doc/developer/api_zot.md | 241 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 237 insertions(+), 4 deletions(-) (limited to 'doc/developer') diff --git a/doc/developer/api_zot.md b/doc/developer/api_zot.md index 26af72298..2458da8b2 100644 --- a/doc/developer/api_zot.md +++ b/doc/developer/api_zot.md @@ -14,13 +14,121 @@ Export channel data channel/stream ================================================================================ -Fetch conversation items +Fetch channel conversation items + +network/stream +================================================================================ + +Fetch network conversation items + files ================================================================================ -List file storage +List file storage (attach DB) + +GET /api/z/1.0/files + + +Options: + + - hash + return only entries matching hash (exactly) + + - filename + return only entries matching filename (substring) + + - filetype + return only entries matching filetype/mimetype (substring) + + - start + start at record (default 0) + + - records + number of records to return or 0 for unlimited + + + +Example: + +curl -u mychannel:mypassword https://xyz.macgirvin.com/api/z/1.0/files -d filetype=multipart/mixed + + +Returns: + + { + + "success": true, + "results": [ + { + "id": "1", + "aid": "1", + "uid": "2", + "hash": "44ee8b2a1a7f36dea07b93b7747a2383a1bc0fdd08339e8928bfcbe45f65d939", + "filename": "Profile Photos", + "filetype": "multipart/mixed", + "filesize": "0", + "revision": "0", + "folder": "", + "os_storage": "1", + "is_dir": "1", + "is_photo": "0", + "flags": "0", + "created": "2016-01-02 21:51:17", + "edited": "2016-01-02 21:51:17", + "allow_cid": "", + "allow_gid": "", + "deny_cid": "", + "deny_gid": "" + }, + { + "id": "12", + "aid": "1", + "uid": "2", + "hash": "71883f1fc64af33889229cbc79c5a056deeec5fc277d765f182f19073e1b2998", + "filename": "Cover Photos", + "filetype": "multipart/mixed", + "filesize": "0", + "revision": "0", + "folder": "", + "os_storage": "1", + "is_dir": "1", + "is_photo": "0", + "flags": "0", + "created": "2016-01-15 00:24:33", + "edited": "2016-01-15 00:24:33", + "allow_cid": "", + "allow_gid": "", + "deny_cid": "", + "deny_gid": "" + }, + { + "id": "16", + "aid": "1", + "uid": "2", + "hash": "f48f7ec3278499d1dd86b72c3207beaaf4717b07df5cc9b373f14d7aad2e1bcd", + "filename": "2016-01", + "filetype": "multipart/mixed", + "filesize": "0", + "revision": "0", + "folder": "", + "os_storage": "1", + "is_dir": "1", + "is_photo": "0", + "flags": "0", + "created": "2016-01-22 03:24:55", + "edited": "2016-01-22 03:26:57", + "allow_cid": "", + "allow_gid": "", + "deny_cid": "", + "deny_gid": "" + } + ] + } + + + filemeta ================================================================================ @@ -30,7 +138,69 @@ Export file metadata for any uploaded file filedata ================================================================================ -Export file contents for any uploaded file +Provides the ability to download a file from cloud storage in chunks + +GET /api/z/1.0/filedata + + +Required: + + - file_id + attach.hash of desired file ('begins with' match) + + +Optional: + + - start + starting byte of returned data in file (counting from 0) + + - length + length (prior to base64 encoding) of chunk to download + + +Returns: + + attach (DB) structure with base64 encoded 'content' comprised of the desired chunk + + + +Example: + + https://xyz.macgirvin.com/api/z/1.0/filedata?f=&file_id=9f5217770fd&start=0&length=48 + +Returns: + + { + + "attach": { + "id": "107", + "aid": "1", + "uid": "2", + "hash": "9f5217770fd55d563bd77f84d534d8e119a187514bbd391714626cd9c0e60207", + "creator": "pgcJx1IQjuPkx8aI9qheJlBMZzJz-oTPjHy3h5pWlOVOriBO_cSiUhhqwhuZ74TYJ8_ECO3pPiRMWC0q8YPCQg", + "filename": "pcxtopbm.c", + "filetype": "application/octet-stream", + "filesize": "3934", + "revision": "0", + "folder": "", + "flags": "0", + "is_dir": "0", + "is_photo": "0", + "os_storage": "1", + "os_path": "", + "display_path": "", + "content": "LyogcGN4dG9wYm0uYyAtIGNvbnZlcnQgUEMgcGFpbnRicnVzaCAoLnBjeCkgZmls", + "created": "2016-07-24 23:13:01", + "edited": "2016-07-24 23:13:01", + "allow_cid": "", + "allow_gid": "", + "deny_cid": "", + "deny_gid": "", + "start": 0, + "length": 48 + } + + } file/export @@ -42,7 +212,70 @@ file albums ================================================================================ -List photo albums +Description: list photo albums + +GET /api/z/1.0/albums + + +Output: + + text - textual name + + total - number of photos in this album + + url - web URL + + urlencode - textual name, urlencoded + + bin2hex - textual name using bin2hex (which is used in the web URL link) + + +Example: + + + { + + "success": true, + "albums": [ + { + "text": "/", + "total": "2", + "url": "https://xyz.macgirvin.com/photos/hubzilla/album/", + "urlencode": "", + "bin2hex": "" + }, + { + "text": "2016-01", + "total": "6", + "url": "https://xyz.macgirvin.com/photos/hubzilla/album/323031362d3031", + "urlencode": "2016-01", + "bin2hex": "323031362d3031" + }, + { + "text": "2016-02", + "total": "7", + "url": "https://xyz.macgirvin.com/photos/hubzilla/album/323031362d3032", + "urlencode": "2016-02", + "bin2hex": "323031362d3032" + }, + { + "text": "Cover Photos", + "total": "5", + "url": "https://xyz.macgirvin.com/photos/hubzilla/album/436f7665722050686f746f73", + "urlencode": "Cover+Photos", + "bin2hex": "436f7665722050686f746f73" + }, + { + "text": "Profile Photos", + "total": "26", + "url": "https://xyz.macgirvin.com/photos/hubzilla/album/50726f66696c652050686f746f73", + "urlencode": "Profile+Photos", + "bin2hex": "50726f66696c652050686f746f73" + } + ] + + } + photos -- cgit v1.2.3 From d4ab74b25eeccef4701f05a56165268e7a17038c Mon Sep 17 00:00:00 2001 From: Andrew Manning Date: Mon, 19 Dec 2016 22:12:08 -0500 Subject: Move headings down to start at H3 at Mario's direction --- doc/developer/api_zot.md | 77 +++++++++++++++++++--------------------- doc/developer/developer_guide.md | 22 ++++++------ 2 files changed, 48 insertions(+), 51 deletions(-) (limited to 'doc/developer') diff --git a/doc/developer/api_zot.md b/doc/developer/api_zot.md index 2458da8b2..d46cc8860 100644 --- a/doc/developer/api_zot.md +++ b/doc/developer/api_zot.md @@ -1,30 +1,27 @@ -Zot API -======= +### Zot API The API endpoints detailed below are relative to `api/z/1.0`, meaning that if an API is listed as `channel/stream` the full API URL is `[baseurl]/api/z/1.0/channel/stream` -channel/export/basic -================================================================================ +### channel/export/basic Export channel data -channel/stream -================================================================================ +### channel/stream Fetch channel conversation items -network/stream -================================================================================ +### network/stream + Fetch network conversation items -files -================================================================================ +### files + List file storage (attach DB) @@ -130,13 +127,13 @@ Returns: -filemeta -================================================================================ +### filemeta + Export file metadata for any uploaded file -filedata -================================================================================ +### filedata + Provides the ability to download a file from cloud storage in chunks @@ -203,14 +200,14 @@ Returns: } -file/export -================================================================================ +### file/export + -file -================================================================================ +### file + + +### albums -albums -================================================================================ Description: list photo albums @@ -278,18 +275,18 @@ Example: -photos -================================================================================ +### photos + list photo metadata -photo -================================================================================ +### photo + -group -================================================================================ +### group + `GET /api/z/1.0/group` @@ -328,8 +325,8 @@ To use with API group_members, provide either 'group_id' from the id element ret } ] -group_members -================================================================================ +### group_members + `GET /api/z/1.0/group_members` @@ -461,8 +458,8 @@ group_member+abook+xchan (DB join) for each member of the privacy group ] -xchan -================================================================================ +### xchan + An xchan is a global location independent channel and is the primary record for a network identity. It may refer to channels on other websites, networks, or services. @@ -506,8 +503,8 @@ Returns: "deleted": "0" } -item/update -================================================================================ +### item/update + Create or update an item (post, activity, webpage, etc.) @@ -733,22 +730,22 @@ Returns: } -item/full -================================================================================ +### item/full + Get all data associated with an item -abook -================================================================================ +### abook + Connections -abconfig -================================================================================ +### abconfig + Connection metadata (such as permissions) -perm_allowed -================================================================================ +### perm_allowed + Check a permission for a given xchan diff --git a/doc/developer/developer_guide.md b/doc/developer/developer_guide.md index 7ec76714f..fa50de8a1 100644 --- a/doc/developer/developer_guide.md +++ b/doc/developer/developer_guide.md @@ -1,4 +1,4 @@ -# Who is a Hubzilla developer? Should I read this? +### Who is a Hubzilla developer? Should I read this? Anyone who contributes to making Hubzilla better is a developer. There are many different and important ways you can contribute to this amazing technology, _even if you do not know how to write code_. The software itself is only a part of the Hubzilla project. You can contribute by @@ -11,31 +11,31 @@ _Software_ developers are of course welcomed; there are so many great ideas to i This document will help you get started learning and contributing to Hubzilla. -# Versioning system +### Versioning system The versioning system is similar to the popular semantic versioning but less stringent. Given x.y.z, x changes yearly. y changes for "stable" monthly builds, and z increments when there are interface changes. We maintain our date and build numbers for medium grain version control (commits within a certain date range) and of course git revs for fine grained control. -# Git repository branches +### Git repository branches There are two official branches of the Hubzilla git repo. * The stable version is maintained on the **master** branch. The latest commit in this branch is considered to be suitable for production hubs. * Experimental development occurs on the **dev** branch, which is merged into **master** when it is deemed tested and stable enough. -# Developer tools and workflows +### Developer tools and workflows -## Hub Snapshots +#### Hub Snapshots -The [[Hub Snapshots]] page provides instructions and scripts for taking complete +The [hub snapshots](/help/admin/hub_snapshots) page provides instructions and scripts for taking complete snapshots of a hub to support switching between consistent and completely known states. This is useful to prevent situations where the content or database schema might be incompatible with the code. -# Translations +### Translations Our translations are managed through Transifex. If you wish to help out translating Hubzilla to another language, sign up on transifex.com, visit [https://www.transifex.com/projects/p/red-matrix/](https://www.transifex.com/projects/p/red-matrix/) and request to join one of the existing language teams or create a new one. Notify one of the core developers when you have a translation update which requires merging, or ask about merging it yourself if you're comfortable with git and PHP. We have a string file called 'messages.po' which is gettext compliant and a handful of email templates, and from there we automatically generate the application's language files. -## Translation Process +#### Translation Process The strings used in the UI of Hubzilla is translated at [Transifex][1] and then included in the git repository at github. If you want to help with translation @@ -98,7 +98,7 @@ view/de/hmessages.po you would do the following. repository, push it to your fork of the Hubzilla repository at github and issue a pull request for that commit. -## Utilities +#### Utilities Additional to the po2php script there are some more utilities for translation in the "util" directory of the Hubzilla source tree. If you only want to @@ -108,7 +108,7 @@ works. For further information see the utils/README file. -## Known Problems +#### Known Problems * Hubzilla uses the language setting of the visitors browser to determain the language for the UI. Most of the time this works, but there are some known @@ -116,7 +116,7 @@ For further information see the utils/README file. * the early translations are based on the friendica translations, if you some rough translations please let us know or fix them at Transifex. -# To-be-organized information +### To-be-organized information **Here is how you can join us.** -- cgit v1.2.3 From 7a9fab8f57901cdb53a6dadf36370ce13beb05cd Mon Sep 17 00:00:00 2001 From: Andrew Manning Date: Thu, 22 Dec 2016 21:40:59 -0500 Subject: Continuing to revise and rearrange content for clarity and reduced redundancy. --- doc/developer/api_zot.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) (limited to 'doc/developer') diff --git a/doc/developer/api_zot.md b/doc/developer/api_zot.md index d46cc8860..d75012818 100644 --- a/doc/developer/api_zot.md +++ b/doc/developer/api_zot.md @@ -1,3 +1,43 @@ +### What is Zot? + +Zot is the revolutionary protocol that powers $Projectname, providing **communications**, **identity management**, and **access control** across a fully **decentralised** network of independent websites, often called "the grid". The resulting platform is a robust system that supports privacy and security while enabling the kind of rich web services typically seen only in centralized, proprietary solutions. + +#### Communications + +Communications and social networking are an integral part of the grid. Any channel (and any services provided by that channel) can make full use of feature-rich social communications on a global scale. These communications may be public or private - and private communications comprise not only fully encrypted transport, but also encrypted storage to help protect against accidental snooping and disclosure by rogue system administrators and internet service providers. + +Zot supports a wide array of background services in the grid, from friend suggestions to directory services. New content and data updates are propagated in the background between hubs across the grid according to access control lists and permissions specified by both sender *and* receiver channels. Data is also synchronized between an arbitrary number of channel clones, allowing hub members to access data and continue collaborating seamlessly in the event that their primary hub is inaccessible or offline. + +#### Identity + +Zot's identity layer is unique. It provides **invisible single sign-on** across all sites in the grid. + +It also provides **nomadic identity**, so that your communications with friends, family, and or anyone else you're communicating with won't be affected by the loss of your primary communication node - either temporarily or permanently. + +The important bits of your identity and relationships can be backed up to a thumb drive, or your laptop, and may appear at any node in the grid at any time - with all your friends and preferences intact. + +Crucially, these nomadic instances are kept in sync so any instance can take over if another one is compromised or damaged. This protects you against not only major system failure, but also temporary site overloads and governmental manipulation or censorship. + +Nomadic identity, single sign-on, and $Projectname's decentralisation of hubs, we believe, introduce a high degree of degree of **resiliency** and **persistence** in internet communications, that are sorely needed amidst global trends towards corporate centralization, as well as mass and indiscriminate government surveillance and censorship. + +As you browse the grid, viewing channels and their unique content, you are seamlessly authenticated as you go, even across completely different server hubs. No passwords to enter. Nothing to type. You're just greeted by name on every new site you visit. + +How does Zot do that? We call it **magic-auth**, because $Projectname hides the details of the complexities that go into single sign-on logins, and nomadic identities, from the experience of browsing on the grid. This is one of the design goals of $Projectname: to increase privacy, and freedom on the web, while reducing the complexity and tedium brought by the need to enter new passwords and login names for every different sight that someone might visit online. + +You login only once on your home hub (or any nomadic backup hub you have chosen). This allows you to access any authenticated services provided anywhere in the grid - such as shopping, blogs, forums, and access to private information. This is just like the services offered by large corporate providers with huge user databases; however you can be a member of this community, as well as a server on this network using a $35 Rasberry Pi. Your password isn't stored on a thousand different sites, or even worse, only on a few sites like Google and Facebook, beyond your direct control. + +You cannot be silenced. You cannot be removed from the grid, unless you yourself choose to exit it. + +#### Access Control + +Zot's identity layer allows you to provide fine-grained permissions to any content you wish to publish - and these permissions extend across $Projectname. This is like having one super huge website made up of an army of small individual websites - and where each channel in the grid can completely control their privacy and sharing preferences for any web resources they create. + +Currently, $Projectname supports access control for many types of data, including post/comment discussion threads, photo albums, events, cloud files, web pages, wikis, and more. Every object and how it is shared and with whom is completely under your control. + +This type of control is trivial on large corporate providers because they own the user database. Within the grid, there is no need for a huge user database on your machine - because the grid **is** your user database. It has what is essentially infinite capacity (limited by the total number of hubs online across the internet), and is spread amongst hundreds, and potentially millions of computers. + +Access can be granted or denied for any resource, to any channel, or any group of channels; anywhere within the grid. Others can access your content if you permit them to do so, and they do not even need to have an account on your hub. + ### Zot API The API endpoints detailed below are relative to `api/z/1.0`, meaning that if an -- cgit v1.2.3