diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Bugs-and-Issues.md | 30 | ||||
| -rw-r--r-- | doc/Developers.md | 22 | ||||
| -rw-r--r-- | doc/Groups-and-Privacy.md | 36 | ||||
| -rw-r--r-- | doc/Home.md | 29 | ||||
| -rw-r--r-- | doc/Install.md | 97 | ||||
| -rw-r--r-- | doc/Making-Friends.md | 48 | ||||
| -rw-r--r-- | doc/Message-Flow.md | 54 | ||||
| -rw-r--r-- | doc/Pages.md | 28 | ||||
| -rw-r--r-- | doc/Plugins.md | 289 | ||||
| -rw-r--r-- | doc/Profiles.md | 51 | ||||
| -rw-r--r-- | doc/Remove-Account.md | 13 | ||||
| -rw-r--r-- | doc/Settings.md | 226 | ||||
| -rw-r--r-- | doc/Sites-running-Friendika-you-can-join.md | 7 | ||||
| -rw-r--r-- | doc/Tags-and-Mentions.md | 37 | ||||
| -rw-r--r-- | doc/developer | 18 |
15 files changed, 985 insertions, 0 deletions
diff --git a/doc/Bugs-and-Issues.md b/doc/Bugs-and-Issues.md new file mode 100644 index 000000000..ed2be00c8 --- /dev/null +++ b/doc/Bugs-and-Issues.md @@ -0,0 +1,30 @@ +Bugs and Issues +=============== + +* [Home](help) + + +Please report any bugs/issues you encounter using our bug tracker at [[http://bugs.friendika.com]] + +Try to provide as much information as you can about the bug (including the full text of any error messages or notices), and if possible your Friendika version. + +Your Friendika version may be found in newer releases by visiting http://YOURFRIENDIKASITE/friendika + +For older versions, view the HTML source of your profile page. The Friendika version is in the HTML header, 5-10 lines from the top of the page. + +For really old versions which don't have a version number in the HTML header - please upgrade. Your bug was probably fixed a long time ago. + +**Bug Sponsorship** + +The bug/issue database allows you to sponsor issues. This provides an incentive for developers to work on your issue. This isn't necessary - we don't like bugs and will try to fix them. This has more importance for future development projects and feature requests. + +Bug sponsorship works on the honour system. If you agree to pay $10 to fix a bug, when the fix has been checked in and verified you should send a paypal payment to the developer assigned to the bug. Don't ever think you can get away with not paying a developer for work performed. Some of these guys could hack into your credit card account if you make them mad. + +At the present time, one has to be approved as a "developer" to be able to assign themselves to a sponsored bug. This requires the developer to have some history fixing Friendika bugs. This is for everybody's assurance that the bug fix will work well with Friendika. If you wish to become approved as a developer, work on and check in some non-sponsored issues or your own projects and we will move you up the ladder. + +If you truly feel you have the solution to a sponsored bug but aren't an approved developer, you risk a sponsored developer assigning the bug to themselves before you check it in, but if they haven't done so - include a short note with your pull request. Assuming that it meets our code standards, we'll see that you get credit. + +If you sponsor a project at greater than a $50 level, you may be requested by the developer for payment up front before work has begun (typically half). Again this is on the honour system - and is mostly to avoid payment issues and disagreements later. You should also expect to see some progress updates or demonstrations if the work takes more than a week or two. If the work is not completed within a reasonable time (as decided by those involved), you are entitled to get your money back. + +Friendika is not involved in these transactions. It is purely a personal agreement between sponsors and developers. If there are any issues, the parties will need to work it out between themselves. We're just providing some guidelines to help avoid potential problems. + diff --git a/doc/Developers.md b/doc/Developers.md new file mode 100644 index 000000000..ebfaf97c3 --- /dev/null +++ b/doc/Developers.md @@ -0,0 +1,22 @@ +Friendika Developer Guide + +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 Friendika repository from [https://github.com/friendika/friendika.git](https://github.com/friendika/friendika.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 Friendika developer to review the code.
\ No newline at end of file diff --git a/doc/Groups-and-Privacy.md b/doc/Groups-and-Privacy.md new file mode 100644 index 000000000..7ff76906f --- /dev/null +++ b/doc/Groups-and-Privacy.md @@ -0,0 +1,36 @@ +Groups and Privacy +================== + +* [Home](help) + + +Groups are merely collections of friends. But Friendika uses these to unlock some very powerful features. + +To create a group, visit your Friendika "Contacts" page and select "Create a new group". Give the group a name. + +This brings you to a page where you can select the group members. + +You will have two boxes on this page. The top box is the roster of current group members. Below that is another box containing all of your friends who are *not* members of the group. + +If you click on a photo of a person who isn't in the group, they will be put into the group. If you click on a photo of a person who is in the group, they will be removed from it. + +Once you have created a group, you may use it in any access control list. This is the little lock icon beneath the status update box on your home page. If you click this you can select who can see and who can *not* see the post you are about to make. These can be individual people or groups. + +On your "Network" page you will find posts and conversation from everybody in your network. You may select an individual group on this page to show conversations pertaining only to members of that group. + +But wait, there's more... + +If you look carefully when visiting a group from your Network page, the lock icon under the status update box has an exclamation mark next to it. This is meant to draw attention to that lock. Click the lock. You will see that since you are only viewing a certain group of people, your status updates while on that screen default to only being seen by that same group of people. This is how you keep your future employers from seeing what you write to your drinking buddies. You can over-ride this setting, but this makes it easy to separate your conversations into different friend circles. + +These private conversations work best when your friends are Freindika members. We know who else can see the conversations - nobody, *unless* your friends cut and paste the messages and send them to others. + +This is a trust issue you need to be aware of. No software in the world can prevent your friends from leaking your confidential and trusted communications. Only a wise choice of friends. + +But it isn't as clear cut when dealing with status.net, identi.ca and other network providers. You are encouraged to be **very** cautious when other network members are in a group because it's entirely possible for your private messages to end up in a public newsfeed. If you look at the Contact Edit page for any person, we will tell you whether or not they are members of an insecure network where you should exercise caution. + +On your "Settings" page, you may create a set of default permissions which apply to every post that you create. + +Once you have created a post, you can not change the permissions assigned. Within seconds it has been delivered to lots of people - and perhaps everybody it was addressed to. If you mistakenly created a message and wish you could take it back, the best you can do is to delete it. We will send out a delete notification to everybody who received the message - and this should wipe out the message with the same speed it was initially propagated. In most cases it will be completely wiped from the Internet - in under a minute. Again, this applies to Friendika networks. Once a message spreads to other networks, it may not be removed quickly and in some cases it may not be removed at all. + +In case you haven't yet figured this out, we are encouraging you to encourage your friends to use Friendika - because all these privacy features work much better within a privacy-aware network. Many of the other social networks Friendika can connect to have no privacy controls. + diff --git a/doc/Home.md b/doc/Home.md new file mode 100644 index 000000000..2c9f90183 --- /dev/null +++ b/doc/Home.md @@ -0,0 +1,29 @@ +Friendika Documentation and Resources +===================================== + + +**Contents** + +* [Making Friends](help/Making-Friends) +* [Tags and Mentions](help/Tags-and-Mentions) +* [Profiles](help/Profiles) +* [Groups and Privacy](help/Groups-and-Privacy) +* [Pages](help/Pages) +* [Remove Account](help/Remove-Account) +* [Bugs and Issues](help/Bugs-and-Issues) + +**Technical Documentation** + +* [Install](help/Install) +* [Settings](help/Settings) +* [Plugins](help/Plugins) +* [Message Flow](help/Message-Flow) +* [Developers](help/Developers) + + +**External Resources** + +* [Main Website](http://friendika.com) +* [Forums](http://groups.google.com/group/friendika) +* [Developer Forums](http://groups.google.com/group/friendika-dev) + diff --git a/doc/Install.md b/doc/Install.md new file mode 100644 index 000000000..3538d7bfa --- /dev/null +++ b/doc/Install.md @@ -0,0 +1,97 @@ +Friendika Installation + +We've tried very hard to ensure that Friendika will run on commodity hosting platforms - such as those used to host Wordpress blogs and Drupal websites. But be aware that Friendika is more than a simple web application. It is a complex communications system which more closely resembles an email server than a web server. For reliability and performance, messages are delivered in the background and are queued for later delivery when sites are down. This kind of functionality requires a bit more of the host system than the typical blog. Not every PHP/MySQL hosting provider will be able to support Friendika. Many will. But **please** review the requirements and confirm these with your hosting provider prior to installation. + +Also if you encounter installation issues, please let us know via the forums at http://groups.google.com/group/friendika or file an issue at http://bugs.friendika.com . Please be as clear as you can about your operating environment and provide as much detail as possible about any error messages you may see, so that we can prevent it from happening in the future. Due to the large variety of operating systems and PHP platforms in existence we may have only limited ability to debug your PHP installation or acquire any missing modules - but we will do our best to solve any general code issues. + +Before you begin: Choose a domain name or subdomain name for your server. Put some thought into this - because changing it after installation is currently not-supported. Things will break, and some of your friends may have difficulty communicating with you. We plan to address this limitation in a future release. + + +1. Requirements + - Apache with mod-rewrite enabled and "Options All" so you can use a +local .htaccess file + + - PHP 5.2+. The later the better. You'll need 5.3 for encryption of key exchange conversations. On a Windows environment, 5.2+ might not work as the function dns_get_record() is only available with version 5.3. + - PHP *command line* access with register_argc_argv set to true in the +php.ini file + - curl, gd, mysql, and openssl extensions + - some form of email server or email gateway such that PHP mail() works + - mcrypt (optional; used for server-to-server message encryption) + + - Mysql 5.x + + - ability to schedule jobs with cron (Linux/Mac) or Scheduled Tasks +(Windows) [Note: other options are presented in Section 7 of this document] + + - Installation into a top-level domain or sub-domain (without a +directory/path component in the URL) is preferred. Directory paths will +not be as convenient to use and have not been thoroughly tested. + + + [Dreamhost.com offers all of the necessary hosting features at a +reasonable price. If your hosting provider doesn't allow Unix shell access, +you might have trouble getting everything to work.] + +2. Unpack the Friendika files into the root of your web server document area. + + - If you are able to do so, we recommend using git to clone the source repository rather than to use a packaged tar or zip file. This makes the software much easier to update. The Linux command to clone the repository into a directory "mywebsite" would be + + `git clone http://github.com/friendika/friendika.git mywebsite` + + and then you can pick up the latest changes at any time with + + `git pull` + + + + - If you copy the directory tree to your webserver, make sure + that you also copy .htaccess - as "dot" files are often hidden + and aren't normally copied. + + +3. Create an empty database and note the access details (hostname, username, password, database name). + +4. Visit your website with a web browser and follow the instructions. Please note any error messages and correct these before continuing. + +5. *If* the automated installation fails for any reason, check the following: + + - ".htconfig.php" exists ... If not, edit htconfig.php and change system settings. Rename +to .htconfig.php + - Database is populated. ... If not, import the contents of "database.sql" with phpmyadmin +or mysql command line + +6. At this point visit your website again, and register your personal account. +Registration errors should all be recoverable automatically. +If you get any *critical* failure at this point, it generally indicates the +database was not installed correctly. You might wish to move/rename +.htconfig.php to another name and empty (called 'dropping') the database +tables, so that you can start fresh. + +7. Set up a cron job or scheduled task to run the poller once every 5-10 +minutes in order to perform background processing. Example: + + `cd /base/directory; /path/to/php include/poller.php` + +Change "/base/directory", and "/path/to/php" as appropriate for your situation. + +If you are using a Linux server, run "crontab -e" and add a line like the +one shown, substituting for your unique paths and settings: + +`*/10 * * * * cd /home/myname/mywebsite; /usr/bin/php include/poller.php` + +You can generally find the location of PHP by executing "which php". If you +have troubles with this section please contact your hosting provider for +assistance. Friendika will not work correctly if you cannot perform this step. + +Alternative: You may be able to use the 'poormancron' plugin to perform this step +if you are using a recent Friendika release. To do this, edit the file ".htconfig.php" +and look for a line describing your plugins. On a fresh installation, it will look like + +`$a->config['system']['addon'] = 'js_upload';` + +This indicates the "js_upload" addon module is enabled. You may add additional +addons/plugins using this same line in the configuration file. Change it to read + +`$a->config['system']['addon'] = 'js_upload,poormancron';` + +and save your changes. diff --git a/doc/Making-Friends.md b/doc/Making-Friends.md new file mode 100644 index 000000000..135f1394a --- /dev/null +++ b/doc/Making-Friends.md @@ -0,0 +1,48 @@ +Making Friends +============== + +* [Home](help) + +Friendship in Friendika can take on a great many different meanings. But let's keep it simple, you want to be friends with somebody. How do you do it? + +The first thing you can do is look at the Directory for somebody you would like to connect with. Visit their profile. Just beneath their profile picture will be the word 'Connect' (we're assuming this is an English language profile). + +Click that. It will take you to a "Connect" form. + +This is going to ask you for your profile locator. This is necessary so that this person's website can find yours. + +What do you put in the box? + +If your Friendika site is called "demo.friendika.com" and your username/nickname on that site is "bob", you would put in "bob@demo.friendika.com". + +Notice this looks just like an email address. It was meant to be that way. It's easy for people to remember. + +You *could* also put in the URL of your profile page, such as "http://demo.friendika.com/profile/bob". + +The email-style locator is certainly easier. + +When you've submitted the connection page, it will take you back to your own site where you must then login (if necessary) and verify the connection request on *your* site. Once you've done this, the two websites can communicate with each other to complete the process (after your new friend has approved the request). + +If you already know somebody's profile location, you can enter it in the "connect" box on your "Contacts" page. This will take you through a similar process. + +You can also use your profile locator or other people's profile locators to become friends across networks. The list of possible networks is growing all the time. If you know (for instance) "bob" on identi.ca (a Status.Net site) you could put bob@identi.ca into your Contact page and become friends across networks. (Or you can put in Bob's profile URL if you wish). You can also be "partial" friends with somebody on Google Buzz by putting in their gmail address. Google Buzz does not yet support all the protocols we need for direct messaging, but you should be able to follow status updates from within Friendika. + +This works from other networks as well. If a friend of yours has an identi.ca account, they can become friends with you by putting your Friendika profile locator into their identi.ca subscription dialog box. + +If this happens you will receive a notification. You will need to approve this before the friendship is complete. + +Some networks allow people to send you messages without being friends and without your approval. Friendika does not allow this by default. It would open a gateway for spam. So when you've approved a friend request from one of these networks, look at your contact page for that person (this will be displayed as soon as you approve the relationship). They might be marked as an "Ignored" contact. + +This means they can see some of your posts (your public posts), but they aren't permitted to send you anything. You can "Un-ignore" them if you desire to allow them to contact you directly and to have their status updates appear in your Network feed. + +When you receive a friendship notification from another Friendika member, you will have the option of allowing them as a "fan" or as a "friend". If they are a fan, they can see what you have to say, including private communications that you send to them, but not vice versa. As a friend, you can both communicate with each other. + +Once you have become friends, if you find the person constantly sends you spam or worthless information, you can "Ignore" them - without breaking off the friendship or even alerting them to the fact that you aren't interested in anything they are saying. In many ways they are like a "fan" - but they don't know this. They think they are a friend. + +You can also "block" a person. This completely blocks communications with that person. They may still be able to see your public posts, as can anybody in the world, but they cannot communicate with you directly in any way. They will know or be able to discover that they have been blocked but there's nothing they can do about it. + +You can also delete a friend no matter what the friendship status - which complete removes everything relating to that person from your website. + + + + diff --git a/doc/Message-Flow.md b/doc/Message-Flow.md new file mode 100644 index 000000000..be2045f79 --- /dev/null +++ b/doc/Message-Flow.md @@ -0,0 +1,54 @@ +Friendika Message Flow + +This page attempts to document some of the details of how messages get from one person to another in the Friendika network. There are multiple paths, using multiple protocols and message formats. + +Those attempting to understand these message flows should become familiar with (at the minimum) the DFRN protocol document (http://dfrn.org/dfrn.pdf) and the message passing elements of the OStatus stack (salmon and Pubsubhubbub). + + +Most message passing involves the file include/items.php, which has functions for several feed-related import/export activities. + +When a message is posted, all immediate deliveries to all networks are made using include/notifier.php, which chooses how (and to whom) to deliver the message. This file also invokes the local side of all deliveries including DFRN-notify. + +mod/dfrn_notify.php handles the remote side of DFRN-notify. + +Local feeds are generated by mod/dfrn_poll.php - which also handles the remote side of DFRN-poll protocol. + +Salmon notifications arrive via mod/salmon.php. + +Push (pubsubhubbub) feeds arrive via mod/pubsub.php + +DFRN-poll feed imports arrive via include/poller.php as a scheduled task, this implements the local side of the DFRN-poll protocol. + + + + +Scenario #1. Bob posts a public status message + +This is a public message with no conversation members so no private transport is used. There are two paths it can take - as a bbcode path to DFRN clients, and converted to HTML with the server's PuSH (pubsubhubbub) hubs notified. When a PuSH hub is operational, dfrn-poll clients prefer to receive their information through the PuSH channel. They will fall back on a daily poll in case the hub has delivery issues (this is quite common when using the default Google reference hub). If there is no specified hub or hubs, DFRN clients will poll at a configurable (per-contact) rate at up to 5-minute intervals. Feeds retrieved via dfrn-poll are bbcode and may also contain private conversations which the poller has permissions to see. + +Scenario #2. Jack replies to Bob's public message. Jack is on the Friendika/DFRN network. + +Jack uses dfrn-notify to send a direct reply to Bob. Bob then creates a feed of the conversation and sends it to everybody involved in the conversation using dfrn-notify. PuSH hubs are notified that new content is available. The hub or hubs will then retrieve the latest feed and transmit it to all hub subscribers (which may be on different networks). + +Scenario #3. Mary replies to Bob's public message. Mary is on the Friendika/DFRN network. + +Mary uses dfrn-notify to send a direct reply to Bob. Bob then creates a feed of the conversation and sends it to everybody involved in the conversation (excluding himself, the conversation is now sent to both Jack and Mary). Messages are sent using dfrn-notify. Push hubs are also notified that new content is available. The hub or hubs will then retrieve the latest feed and transmit it to all hub subscribers (which may be on different networks). + +Scenario #4. William replies to Bob's public message. William is on the OStatus network. + +William uses salmon to notify Bob of the reply. Content is html embedded in salmon magic envelope. Bob then creates a feed of the conversation and sends it to all Friendika participants involved in the conversation using dfrn-notify (excluding himself, the conversation is sent to both Jack and Mary). Push hubs are notified that new content is available. The hub or hubs will then retrieve the latest feed and transmit it to all hub subscribers (which may be on different networks). + +Scenario #5. Bob posts a private message to Mary and Jack. + +Message is delivered immediately to Mary and Jack using dfrn_notify. Public hubs are not notified. Requeueing is attempted in case of timeout. Replies follow the same flow as the public replies except that hubs are not notified and message is never made available in the public feed. The entire conversation is also made available to Mary and Jack (and nobody else) through their dfrn-poll personalised feed. + + + + + + + + + + + diff --git a/doc/Pages.md b/doc/Pages.md new file mode 100644 index 000000000..6f4322b13 --- /dev/null +++ b/doc/Pages.md @@ -0,0 +1,28 @@ +Pages +===== + +* [Home](help) + + +Friendika also lets you create group and/or celebrity pages. + +Every page in Friendika has a nickname and these must all be unique. This applies to all pages, whether they are normal profiles or group pages. + +Therefore the first thing you need to do to create a new page is to register a new account for the page. Please note that the site administrator can restrict and/or regulate the registration of new accounts. + +If you create a second account on a system and use the same email address or OpenID account, you will no longer be able to use the email address (or OpenID) to login to the account. You should login using the account nickname instead. + +On the new account, visit the 'Settings' page. Towards the end of the page are "Advanced Page Settings". Typically you would use "Normal Account" for a normal personal account. This is the default selection. Group pages provide the ability for people to become friends/fans of the page without requiring approval. + +The exact setting you would use depends on how you wish to interact with people who join the page. The "Soapbox" setting let's the page owner control all communications. Everything you post will go out to the page members, but there will be no opportunity for interaction. This setting would typically be used for announcements or corporate communications. + +The most common setting is the "Community Account". This creates a group page where all members can freely interact. + +The "Automatic Friend Account" is typically used for personal profile pages where you wish to automatically approve any friendship/connection requests. + +**Managing Multiple Pages** + +We recommend that you create group pages with the same email address and password as your normal account. If you do this, you will find a new "Manage" tab on the menu bar which lets you toggle identities easily and manage your pages. You are not required to do this, but the alternative is to logout and log back into the other account to manage alternate pages - and this could get cumbersome if you manage several different pages/identities. + + + diff --git a/doc/Plugins.md b/doc/Plugins.md new file mode 100644 index 000000000..42c04cb26 --- /dev/null +++ b/doc/Plugins.md @@ -0,0 +1,289 @@ +**Friendika Addon/Plugin development** + +This is an early specification and hook details may be subject to change. + +Please see the sample addon 'randplace' for a working example of using some of these features. The facebook addon provides an example of integrating both "addon" and "module" functionality. Addons work by intercepting event hooks - which must be registered. Modules work by intercepting specific page requests (by URL path). + +You must register all addons/plugins with the system in the .htconfig.php file. + + $a->config['system']['addon'] = 'plugin1name, plugin2name, another_name'; + +Plugin names cannot contain spaces and are used as filenames. Each addon must contain both an install and an uninstall function based on the addon/plugin name. For instance "plugin1name_install()". These two functions take no arguments and are usually responsible for registering (and unregistering) event hooks that your plugin will require. The install and uninstall functions will also be called (i.e. re-installed) if the plugin changes after installation - therefore your uninstall should not destroy data and install should consider that data may already exist. Future extensions may provide for "setup" amd "remove". + + + +Register your plugin hooks during installation. + + register_hook($hookname, $file, $function); + +$hookname is a string and corresponds to a known Friendika hook. + +$file is a pathname relative to the top-level Friendika directory. This *should* be 'addon/plugin_name/plugin_name.php' in most cases. + +$function is a string and is the name of the function which will be executed when the hook is called. + + +Your hook callback functions will be called with at least one and possibly two arguments + + + function myhook_function(&$a, &$b) { + + + } + + +If you wish to make changes to the calling data, you must declare them as +reference variables (with '&') during function declaration. + +$a is the Friendika 'App' class - which contains a wealth of information +about the current state of Friendika, such as which module has been called, +configuration info, the page contents at the point the hook was invoked, profile +and user information, etc. It is recommeded you call this '$a' to match its usage +elsewhere. + +$b can be called anything you like. This is information which is specific to the hook +currently being processed, and generally contains information that is being immediately +processed or acted on that you can use, display, or alter. Remember to declare it with +'&' if you wish to alter it. + +**Modules** + +Plugins/addons may also act as "modules" and intercept all page requests for a given URL path. In order for a plugin to act as a module it needs to define a function "plugin_name_module()" which takes no arguments and need not do anything. + +If this function exists, you will now receive all page requests for "http://my.web.site/plugin_name" - with any number of URL components as additional arguments. These are parsed into an array $a->argv, with a corresponding $a->argc indicating the number of URL components. So http://my.web.site/plugin/arg1/arg2 would look for a module named "plugin" and pass its module functions the $a App structure (which is available to many components). This will include: + $a->argc = 3 + $a->argv = array(0 => 'plugin', 1 => 'arg1', 2 => 'arg2'); + +Your module functions will often contain the function plugin_name_content(&$a), which defines and returns the page body content. They may also contain plugin_name_post(&$a) which is called before the _content function and typically handles the results of POST forms. You may also have plugin_name_init(&$a) which is called very early on and often does module initialisation. + + + +**Current hooks:** + +**'authenticate'** - called when a user attempts to login. + $b is an array + 'username' => the supplied username + 'password' => the supplied password + 'authenticated' => set this to non-zero to authenticate the user. + 'user_record' => successful authentication must also return a valid user record from the database + +**'logged_in'** - called after a user has successfully logged in. + $b contains the $a->user array + + +**'display_item'** - called when formatting a post for display. + $b is an array + 'item' => The item (array) details pulled from the database + 'output' => the (string) HTML representation of this item prior to adding it to the page + +**'post_local'** - called when a status post or comment is entered on the local system + $b is the item array of the information to be stored in the database + {Please note: body contents are bbcode - not HTML) + +**'post_local_end'** - called when a local status post or comment has been stored on the local system + $b is the item array of the information which has just been stored in the database + {Please note: body contents are bbcode - not HTML) + +**'post_remote'** - called when receiving a post from another source. This may also be used to post local activity or system generated messages. + $b is the item array of information to be stored in the database and the item + body is bbcode. + +**'settings_form'** - called when generating the HTML for the user Settings page + $b is the (string) HTML of the settings page before the final '</form>' tag. + +**'settings_post'** - called when the Settings pages are submitted. + $b is the $_POST array + +**'plugin_settings'** - called when generating the HTML for the addon settings page + $b is the (string) HTML of the addon settings page before the final '</form>' tag. + +**'plugin_settings_post'** - called when the Addon Settings pages are submitted. + $b is the $_POST array + +**'profile_post'** - called when posting a profile page. + $b is the $_POST array + +**'profile_edit'** - called prior to output of profile edit page + $b is array + 'profile' => profile (array) record from the database + 'entry' => the (string) HTML of the generated entry + + +**'profile_advanced'** - called when the HTML is generated for the 'Advanced profile', corresponding to the 'Profile' tab within a person's profile page. + $b is the (string) HTML representation of the generated profile + (The profile array details are in $a->profile) + +**'directory_item'** - called from the Directory page when formatting an item for display + $b is an array + 'contact' => contact (array) record for the person from the database + 'entry' => the (string) HTML of the generated entry + +**'profile_sidebar_enter'** - called prior to generating the sidebar "short" profile for a page + $b is (array) the person's profile array + +**'profile_sidebar'** - called when generating the sidebar "short" profile for a page + $b is an array + 'profile' => profile (array) record for the person from the database + 'entry' => the (string) HTML of the generated entry + +**'contact_block_end'** - called when formatting the block of contacts/friends on a profile sidebar has completed + $b is an array + 'contacts' => array of contacts + 'output' => the (string) generated HTML of the contact block + +**'bbcode'** - called during conversion of bbcode to html + $b is (string) converted text + +**'html2bbcode'** - called during conversion of html to bbcode (e.g. remote message posting) + $b is (string) converted text + +**'page_header'** - called after building the page navigation section + $b is (string) HTML of nav region + +**'personal_xrd'** - called prior to output of personal XRD file. + $b is an array + 'user' => the user record for the person + 'xml' => the complete XML to be output + +**'home_content'** - called prior to output home page content, shown to unlogged users + $b is (string) HTML of section region + +**'contact_edit'** - called when editing contact details on an individual from the Contacts page + $b is (array) + 'contact' => contact record (array) of target contact + 'output' => the (string) generated HTML of the contact edit page + +**'contact_edit_post'** - called when posting the contact edit page + $b is the $_POST array + +**'init_1'** - called just after DB has been opened and before session start + $b is not used or passed + + +**'page_end'** - called after HTML content functions have completed + $b is (string) HTML of content div + + +*** = subject to change + +Not yet documented (you may view these within the source code): + +**'atom_feed'** *** + +**'atom_feed_end'** *** + +**'parse_atom'** *** + +**'atom_author'** *** + +**'atom_entry'** *** + +A complete list of all hook callbacks with file locations (generated 22-Feb-2011): Please see the source for details of any hooks not documented above. + +boot.php: call_hooks('contact_block_end', $arr); + +boot.php: call_hooks('profile_sidebar_enter', $profile); + +boot.php: call_hooks('profile_sidebar', $arr); + +boot.php: call_hooks("proc_run", $args); + +include/nav.php: call_hooks('page_header', $a->page['nav']); + +include/auth.php: call_hooks('authenticate', $addon_auth); + +include/auth.php: call_hooks('logged_in', $a->user); + +include/bbcode.php: call_hooks('bbcode',$Text); + +include/acl_selectors.php: call_hooks($a->module . '_pre_' . $selname, $arr); + +include/acl_selectors.php: call_hooks($a->module . '_post_' . $selname, $o); + +include/acl_selectors.php: call_hooks($a->module . '_pre_' . $selname, $arr); + +include/acl_selectors.php: call_hooks($a->module . '_post_' . $selname, $o); + +include/items.php: call_hooks('atom_feed', $atom); + +include/items.php: call_hooks('atom_feed_end', $atom); + +include/items.php: call_hooks('atom_feed_end', $atom); + +include/items.php: call_hooks('parse_atom', $arr); + +include/items.php: call_hooks('post_remote',$arr); + +include/items.php: call_hooks('atom_author', $o); + +include/items.php: call_hooks('atom_entry', $o); + +include/html2bbcode.php: call_hooks('html2bbcode', $text); + +index.php: call_hooks('init_1'); + +index.php:call_hooks('app_menu', $arr); + +index.php:call_hooks('page_end', $a->page['content']); + +mod/photos.php: call_hooks('photo_post_init', $_POST); + +mod/photos.php: call_hooks('photo_post_file',$ret); + +mod/photos.php: call_hooks('photo_post_end',intval($item_id)); + +mod/photos.php: call_hooks('photo_upload_form',$ret); + +mod/parse_url.php: call_hooks('parse_link', $arr); + +mod/home.php: call_hooks("home_content",$o); + +mod/contacts.php: call_hooks('contact_edit_post', $_POST); + +mod/contacts.php: call_hooks('contact_edit', $arr); + +mod/settings.php: call_hooks('plugin_settings_post', $_POST); + +mod/settings.php: call_hooks('settings_post', $_POST); + +mod/settings.php: call_hooks('plugin_settings', $o); + +mod/settings.php: call_hooks('settings_form',$o); + +mod/network.php: call_hooks('jot_tool', $jotplugins); + +mod/network.php: call_hooks('jot_networks', $jotnets); + +mod/network.php: call_hooks('display_item', $arr); + +mod/xrd.php: call_hooks('personal_xrd', $arr); + +mod/item.php: call_hooks('post_local_start', $_POST); + +mod/item.php: call_hooks('post_local',$datarray); + +mod/item.php: call_hooks('post_local_end', $datarray); + +mod/profile.php: call_hooks('profile_advanced',$o); + +mod/profile.php: call_hooks('jot_tool', $jotplugins); + +mod/profile.php: call_hooks('jot_networks', $jotnets); + +mod/profile.php: call_hooks('display_item', $arr); + +mod/display.php: call_hooks('display_item', $arr); + +mod/profiles.php: call_hooks('profile_post', $_POST); + +mod/profiles.php: call_hooks('profile_edit', $arr); + +mod/cb.php: call_hooks('cb_init'); + +mod/cb.php: call_hooks('cb_post', $_POST); + +mod/cb.php: call_hooks('cb_afterpost'); + +mod/cb.php: call_hooks('cb_content', $o); + +mod/directory.php: call_hooks('directory_item', $arr); diff --git a/doc/Profiles.md b/doc/Profiles.md new file mode 100644 index 000000000..9c81071c5 --- /dev/null +++ b/doc/Profiles.md @@ -0,0 +1,51 @@ +Profiles +======== + +* [Home](help) + +Friendika has unlimited profiles. You may use different profiles to show different "sides of yourself" to different audiences. + +You always have a profile known as your "default" profile (though you may change the name). This profile is always available to the general public and cannot be hidden. You may (and probably should) restrict the information you make available on your public profile. + +That said, if you want other friends to be able to find you, it helps to have the following information in your public profile... + +* Your real name +* A photo of **you** +* Your location on the planet, at least to a country level. + +Without this basic information, you could get very lonely here. Most people (even your best friends) will not try and connect with somebody that has a fake name or doesn't contain a real photo. + +In addition, if you'd like to meet people that share some general interests with you, please take a moment and add some "Public Keywords" to your profile. Such as "music, linux, photography" or whatever. You can add as many keywords as you like. Without this, people with similar interests may never know it unless you stumble across them through another friend. + + +Your default or public profile is also shown to contacts on other networks, since they do not have the ability to view your private profiles. Only members of the Friendika network can see alternate/private profiles. + + +To create an alternate profile, select "Profiles" from the menu of your Friendika site. You may edit an existing profile, change the profile photo, or create a new profile. You may also create a "clone" of an existing profile if you only wish to change a few items but don't wish to enter all the information again. + +To assign a profile to specific persons, select the person from your "Contacts" page and click the pencil "Edit" icon. You will find a dropdown box listing the various profiles available. If this box is not selectable, the person is not in a supported network and cannot be assigned a specific profile. + +Once a profile has been selected, when the person views your profile from one of the "magic profile links" on their site, they will see the private profile you have assigned. If they are not logged into their site or view your profile from elsewhere, they will see your public profile. + +A magic profile link is indicated by a special cursor when hovering over a contact's name or photo. Currently this cursor is a hand next to a small padlock. These magic cursors indicate that by following the link, you are able to access special areas of the other person's pages which are only available to friends and may not be available to the general public. + +You may also discover that (assuming you have the proper permissions) you may be able to post directly on the other person's profile (often called a "wall-to-wall" post). You may also be able to comment directly on posts from while visiting the other person's profile page. + +There are two settings which allow you to publish your profile to a directory and ensure that it can be found by others. You can change these through settings on the "Settings" page. One setting allows you to publish your profile in the site directory of this Friendika server. Another option (this may have been disabled by the site creator) allows you to publish your profile in the "Global Directory". This is a mega directory which contains people from many other Friendika installations world-wide. + +If you do not wish to be visible to any of these sites, you may leave your profile unpublished. + +Although you may have multiple profiles, you only have one profile photo. This is intentional. In early tests we experimented with different photos for each profile and found it was very confusing for people. They might see a different picture depending on what website they visited or what conversation they were in, and often alerted them to the fact that other people might be able to see different profiles of you than they could see. + +(But you can use the rich-text information boxes within a profile such as "Tell us about yourself" and link other photos onto the page.) + +**Keywords and Directory Search** + +On the site Directory page, you may search for people with published profiles who are on this site. The search is typically for your nickname or part of your full name. However this search will also match against other profile fields - such as gender, location, "about", work, and education. You may also include "Keywords" in your default profile - which may be used to search for common interests with other members. These keywords are *not* displayed on your profile page. You could use these keywords to locate people who share membership in secret societies, or that share a love of fishing (for example) - without making this information visible on your public profile. In Friendika version 2.2 and later there are two sets of Keywords - public and private. Public keywords are used in the friend suggestion tool and although they aren't readily visible, they may be seen by viewing the HTML of your profile page. Private keywords are hidden and secret. (Keywords from earlier releases are all converted into private keywords during upgrade). + +Directory searches are also able to use "boolean" logic so that you can search for "+lesbian +Florida" and find those who's sexual preference (or keywords) contain the world "lesbian" and that live in Florida. See the section on "Topical Tags" on the [[Tags-and-Mentions]] page for more information on performing boolean searches. + +On your Contacts page is a link to "Find People with Shared Interests" (unless your site administrator has disabled the global directory). This will combine both your public and private keywords, and find people in the global directory who have matching and/or similar keywords. (Your private keywords are not identified or stored on the global directory). The more keywords you provide, the more relevant the search results that are returned. These are sorted by relevance. You may discover that you are the first person on the list - because you are very likely the most relevant match for your keywords in the directory. + + +
\ No newline at end of file diff --git a/doc/Remove-Account.md b/doc/Remove-Account.md new file mode 100644 index 000000000..10c5d5cfe --- /dev/null +++ b/doc/Remove-Account.md @@ -0,0 +1,13 @@ +Remove Account +============== + +* [Home](help) + +We don't like to see people leave Friendika, but if you need to remove your account, you should visit the URL + +http://friendika-site/removeme + +with your web browser. You will need to be logged in at the time. (Replace "friendika-site" with the hostname of your Friendika server) + +You will be asked for your password to confirm the request. If this matches your stored password, your account will immediately be removed. Unlike some social networks we do **not** hold onto it for a grace period in case you change your mind. Your user details, your conversations, your photos, your friends - everything; will be removed immediately and you will be logged out. + diff --git a/doc/Settings.md b/doc/Settings.md new file mode 100644 index 000000000..215eeb327 --- /dev/null +++ b/doc/Settings.md @@ -0,0 +1,226 @@ +Here are some of the built-in features which don't have an exposed interface or are otherwise undocumented. Configuration settings are stored in the file ".htconfig.php". Edit this file with a text editor to make the desired changes. Several system settings are already documented in that file and will not be covered here. + +**Hot Keys** + +Friendika traps the following keyboard events: + +* [Pause] - Pauses "Ajax" update activity. This is the process that provides updates without reloading the page. You may wish to pause it to reduce network usage and/or as a debugging aid for javascript developers. A pause indicator will appear at the lower right hand corner of the page. Hit the [pause] key once again to resume. + +* [F8] - Displays a language selector + + +**Birthday Notifications** + +Birthday events are published on your Home page for any friends having a birthday in the coming 6 days. In order for your birthday to be discoverable by all of your friends, you must set your birthday (at least the month and day) in your default profile. You are not required to provide the year. + +**Configuration settings** + + +**Language** + +System Setting + +Please see util/README for information on creating language translations. + +Config: +``` +$a->config['system']['language'] = 'name'; +``` + + +**System Theme** + +System Setting + +Choose a named theme to be the default system theme (which may be over-ridden by user profiles). Default theme is "default". + +Config: +``` +$a->config['system']['theme'] = 'theme-name'; +``` + + +**Verify SSL Certitificates** + +Security setting + +By default Friendika allows SSL communication between websites that have "self-signed" SSL certificates. For the widest compatibility with browsers and other networks we do not recommend using self-signed certificates, but we will not prevent you from using them. SSL encrypts all the data transmitted between sites (and to your browser) and this allows you to have completely encrypted communications, and also protect your login session from hijacking. Self-signed certificates can be generated for free, without paying top-dollar for a website SSL certificate - however these aren't looked upon favourably in the security community because they can be subject to so-called "man-in-the-middle" attacks. If you wish, you can turn on strict certificate checking. This will mean you cannot connect (at all) to self-signed SSL sites. + +Config: +``` +$a->config['system']['verifyssl'] = true; +``` + + +**Allowed Friend Domains** + +Corporate/Edu enhancement + +Comma separated list of domains which are allowed to establish friendships with this site. Wildcards are accepted. (Wildcard support on Windows platforms requires PHP5.3). By default, any (valid) domain may establish friendships with this site. + +Config: +``` +$a->config['system']['allowed_sites'] = "sitea.com, *siteb.com"; +``` + + +**Allowed Email Domains** + +Corporate/Edu enhancement + +Comma separated list of domains which are allowed in email addresses for registrations to this site. This can lockout those who are not part of this organisation from registering here. Wildcards are accepted. (Wildcard support on Windows platforms requires PHP5.3). By default, any (valid) email address is allowed in registrations. + +Config: +``` +$a->config['system']['allowed_email'] = "sitea.com, *siteb.com"; +``` + + +**Force Publish** + +Corporate/Edu enhancement + +By default, each user can choose on their Settings page whether or not to have their profile published in the site directory. This setting forces all +profiles on this site to be listed in the site directory and there is no option provided to the user to change it. Default is false. + +Config: +``` +$a->config['system']['publish_all'] = true; +``` + + +**Global Directory** + +Corporate/Edu enhancement + +This configures the URL to update the global directory, and is supplied in the default configuration. The undocumented part is that if this is not set, the global directory is completely unavailable to the application. This allows a private community to be completely isolated from the global mistpark network. + +``` +$a->config['system']['directory_submit_url'] = 'http://dir.friendika.com/submit'; +``` + + +**Proxy Configuration Settings** + +If your site uses a proxy to connect to the internet, you may use these settings to communicate with the outside world (the outside world still needs to be able to see your website, or this will not be very useful). + +Config: +``` +$a->config['system']['proxy'] = "http://proxyserver.domain:port"; +$a->config['system']['proxyuser'] = "username:password"; +``` + + +**Network Timeout** + +How long to wait on a network communication before timing out. Value is in seconds. Default is 60 seconds. Set to 0 for unlimited (not recommended). + +Config: +``` +$a->config['system']['curl_timeout'] = 60; +``` + + +**Banner/Logo** + +Set the content for the site banner. Default is the Friendika logo and name. You may wish to provide HTML/CSS to style and/or position this content, as it may not be themed by default. + +Config: +``` +$a->config['system']['banner'] = '<span id="logo-text">My Great Website</span>'; +``` + + +**Maximum Image Size** + +Maximum size in bytes of uploaded images. Default is 0, which means no limits. + +Config: +``` +$a->config['system']['maximagesize'] = 1000000; +``` + + +**UTF-8 Regular Expressions** + +During registrations, full names are checked using UTF-8 regular expressions. This requires PHP to have been compiled with a special setting to allow UTF-8 expressions. If you are completely unable to register accounts, set no_utf to true. Default is false (meaning UTF8 regular expressions are supported and working). + +Config: +``` +$a->config['system']['no_utf'] = true; +``` + + +**Check Full Names** + +You may find a lot of spammers trying to register on your site. During testing we discovered that since these registrations were automatic, the "Full Name" field was often set to just an account name with no space between first and last name. If you would like to support people with only one name as their full name, you may change this setting to true. Default is false. + +Config: +``` +$a->config['system']['no_regfullname'] = true; +``` + + +**Gravatars** + +During registration, we will try to automatically find a user photo for you on the web using the gravatar service. You may turn this off by setting 'no_gravatar' to true. Default is false. + +Config: +``` +$a->config['system']['no_gravatar'] = true; +``` + + +**OpenID** + +By default, OpenID may be used for both registration and logins. If you do not wish to make OpenID facilities available on your system (at all), set 'no_openid' to true. Default is false. + +Config: +``` +$a->config['system']['no_openid'] = true; +``` + + +**Multiple Registrations** + +The ability to create "Pages" requires a person to register more than once. Your site configuration can block registration (or require approval to register). By default logged in users can register additional accounts for use as pages. These will still require approval if REGISTER_APPROVE is selected. You may prohibit logged in users from creating additional accounts by setting 'block_extended_register' to true. Default is false. + +Config: +``` +$a->config['system']['block_extended_register'] = true; +``` + + +**Developer Settings** + +Most useful when debugging protocol exchanges and tracking down other communications issues. + +Config: + +``` +$a->config['system']['debugging'] = true; +$a->config['system']['logfile'] = 'logfile.out'; +$a->config['system']['loglevel'] = LOGGER_DEBUG; +``` +Turns on detailed debugging logs which will be stored in 'logfile.out' (which must be writeable by the webserver). LOGGER_DEBUG will show a good deal of information about system activity but will not include detailed data. You may also select LOGGER_ALL but due to the volume of information we recommend only enabling this when you are tracking down a specific problem. Other log levels are possible but are not being used at the present time. + + +**PHP error logging** + +Use the following settings to redirect PHP errors to a file. + +Config: + +``` +error_reporting(E_ERROR | E_WARNING | E_PARSE ); +ini_set('error_log','php.out'); +ini_set('log_errors','1'); +ini_set('display_errors', '0'); +``` + +This will put all PHP errors in the file php.out (which must be writeable by the webserver). Undeclared variables are occasionally referenced in the program and therefore we do not recommend using E_NOTICE or E_ALL. The vast majority of issues reported at these levels are completely harmless. Please report to the developers any errors you encounter in the logs using the recommended settings above. They generally indicate issues which need to be resolved. + +If you encounter a blank (white) page when using the application, view the PHP logs - as this almost always indicates an error has occurred. + + + diff --git a/doc/Sites-running-Friendika-you-can-join.md b/doc/Sites-running-Friendika-you-can-join.md new file mode 100644 index 000000000..8127a5b9c --- /dev/null +++ b/doc/Sites-running-Friendika-you-can-join.md @@ -0,0 +1,7 @@ +Here is a list of Friendika installations free for everybody to join: + +* [friendika.com](http://demo.friendika.com) +* [friendika.net](http://www.friendika.net) +* [aphasi.cc](https://friendika.aphasi.cc) +* [openmindspace.org](http://friendika.openmindspace.org) +* [dfrn.net](http://dfrn.net/)
\ No newline at end of file diff --git a/doc/Tags-and-Mentions.md b/doc/Tags-and-Mentions.md new file mode 100644 index 000000000..d5880254b --- /dev/null +++ b/doc/Tags-and-Mentions.md @@ -0,0 +1,37 @@ +Tags and Mentions +================= + + +* [Home](help) + + +Like many other modern social networks, Friendika uses a special notation inside messages to indicate "tags" or contextual links to other entities. + +**Mentions** + +People are tagged by preceding their name with the @ character. + +The following are various ways of indicating a person: + +* @mike - indicates a known contact in your social circle whose nickname is "mike" +* @mike_macgirvin - indicates a known contact in your social circle whose full name is "Mike Macgirvin". Note that spaces cannot be used inside tags. +* @mike@macgirvin.com - indicates the profile locator of a person on a different network, or one that is *not* in your social circle. This can only be an email-style locator, not a web URL. + +Unless their system blocks unsolicited "mentions", the person tagged will likely receive a "Mention" post/activity or become a direct participant in the conversation in the case of public posts. Please note that Friendika often blocks incoming "mentions" from other networks and especially from people with no relationship to you. This is a spam prevention measure. + +Friendika makes no distinction between people and groups for the purpose of tagging. (Some other networks use !group to indicate a group.) + +**Topical Tags** + +Topical tags are indicated by preceding the tag name with the # character. This will create a link in the post to a generalised site search for the term provided. For example, #cars will provide a search link for all posts mentioning 'cars' on your site. Topical tags are generally a minimum of three characters in length. Shorter search terms are not likely to yield any search results, although this depends on the database configuration. The same rules apply as with names that spaces within tags are represented by the underscore character. It is therefore not possible to create a tag whose target contains an underscore. + +Tag searches may also use "boolean" logic. + +* \#bike - creates a search for "bike" +* \#bike_red - creates a search for posts that contain either the word "bike" OR the word "red". +* \#+bike_+red - creates a search for posts that contain both the word "bike" AND the word "red" +* \#+bike_-blue - creates a search for posts that contain the word "bike" but do *not* contain the word "blue" + + + + diff --git a/doc/developer b/doc/developer new file mode 100644 index 000000000..1dfd0503b --- /dev/null +++ b/doc/developer @@ -0,0 +1,18 @@ +Friendika Developer Guide + +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. + +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.
\ No newline at end of file |