docs

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
docs [28-11-2007 21:17]
cwacha 		docs [05-03-2020 01:03] (current)
cwacha
Line 1: Line 1:
 ====== Documentation ====== ====== Documentation ======
-{{documentation.png?nolink  }}+{{:documentation.png?nolink |}}
  
  
-==== Prerequisites / Dependencies ====+===== Prerequisites / Dependencies =====
 PHP iAddressbook does only have very little dependencies since I wanted it to work on as many systems as possible. PHP iAddressbook does only have very little dependencies since I wanted it to work on as many systems as possible.
  
-\\ +You will need: 
-\\ +  * [[http://www.php.net|PHP]] (Version 5.6 or higher) 
- +  * a database (MySQL (PDO) or SQLite2 or 3 (sqlite3 or PDO sqlite3)
-You need: +
-  * [[http://www.php.net|PHP]] (any recent version should do) +
-  * a database (MySQL or SQLite, [[http://adodb.sourceforge.net/|ADOdb]] is used as abstraction layer)+
   * (optional) iconv (if you want to import vcards that are not UTF-8 encoded)   * (optional) iconv (if you want to import vcards that are not UTF-8 encoded)
   * (optional) ImageMagick's convert or GD (if you want to import photos)   * (optional) ImageMagick's convert or GD (if you want to import photos)
  
-==== Installation ====+===== Installation =====
  
 Installing the address book consists of four steps: Installing the address book consists of four steps:
  
-  - create a new database called //addressbook// +  - Copy all files to your web space 
-  - create three new tables inside this database called //addressbook//, //addressbook_cat// and //addressbook_catmap// using the template found in the root directory of the archive (addressbook.sql) +  - Open your web browser and point it to your installation. You will be automatically redirected to the first time installation 
-  - make a copy of //conf/config.php.dist// or create your own **//conf/config.php//** (for a list of all available configuration parameters see **//conf/defaults.php//**). The settings in //conf/config.php// override those in //conf/defaults.php//. +  - Follow the steps in the installer 
-  - if you want authorization support make a copy of //auth.php.dist// into **//auth.php//** and add usernames and passwords as needed.+  - If you want authorization support enable it during the installation. You need to manually create users in conf/auth.php for now. You will find instructions in conf/auth.php.
  
-=== Setup for SQLite === 
  
-  - make sure that your PHP installation has sqlite support +===== Upgrade =====
-  - adjust your //conf/config.php// +
-  - either create a new sqlite database or use the one supplied with PHP iAddressBook +
-  - sqlite version 2.x and version 3.x are not compatible, make sure that you are using the correct version (sqlite-db2 is for version 2.x - sqlite-db3 is for version 3.x) +
-  - make sure that the webserver and PHP can write to the sqlite database file (use ''chmod 777 sqlite/sqlite-db2'') +
-  - make sure that the webserver and PHP can write to the directory where the sqlite database file is located (use ''chmod 777 sqlite/'')+
  
 +The easiest way to upgrade is to use the vCard export feature to get all your contacts
 +and then import these contacts into a new installation. You won't lose any data as the
 +vCard export preserves all fields!
  
-  $conf['dbtype']      = 'sqlite'; 
-  $conf['dbname']      = 'addressbook'; 
-  $conf['dbserver']    = AB_INC.'sqlite/sqlite-db2'; 
-  $conf['dbuser']      = ''; 
-  $conf['dbpass']      = ''; 
-  $conf['dbtable_ab']     = 'addressbook_test'; 
-  $conf['dbtable_cat']    = 'addressbook_test_cat'; 
-  $conf['dbtable_catmap'] = 'addressbook_test_catmap'; 
  
-=== Setup for SQLite on Debian Linux ===+Follow these steps and you should be on the safe side:
  
-This assumes that you already have a web server with PHP support installed and configured. +  - Export all your contacts using the vCard export. 
- +  - Install the addressbook as described in the installation chapter. 
- +  - Import your vCard into the new addressbook. Use the //folder import// feature if you 
-  * Make sure that you have all of the other bits and pieces installed: +    have a lot of contacts. 
- +  - If everything works as expected, remove the old installation and rename/move your 
-  # apt-get install libphp-adodb php4-pear php4-sqlite sqlite</code> +    new installation to the old place.
- +
-  * Unzip iAddressbook into your web servers DocumentRoot and rename the folder appropriately: +
- +
-  # unzip -a ab_095.zip -d /var/www +
-  # mv /var/www/ab_095 /var/www/iaddressbook +
- +
-  * Change into the iAddressbook directory: +
- +
-  # cd /var/www/iaddressbook +
- +
-  * Change permissions on the provided sqlite database so that the web server has write permissions (www-data is the default web server user on Debian, if you've changed it to use another user you'll need to change the below command appropriately): +
- +
-  # chown -R www-data sqlite/ +
- +
-  * Copy in the new config files you are going to use: +
- +
-  # cp conf/config.php.dist conf/config.php +
-  # cp conf/auth.php.dist conf/auth.php +
- +
-  * Edit config.php and change it so that it uses the SQLite database, the database section should look something like this (note that the dbname, username and password variables aren't needed for SQLite): +
- +
-  $conf['dbtype'] = 'sqlite'; +
-  $conf['dbserver'] = '/var/www/iaddressbook/sqlite/sqlite-db2'; +
-  $conf['dbtable_ab'] = 'addressbook'; +
-  $conf['dbtable_cat'] = 'addressbook_cat'; +
-  $conf['dbtable_catmap'] = 'addressbook_catmap'; +
- +
-  * You should now be ready to go, you can test your installation by going to the URL (eg. http://www.yourdomain.com/iaddresssbook/) +
- +
- +
-==== Upgrade ==== +
- +
-Upgrading is always tricky since you have to make sure that no personal configuration data is accidently overridden. I tried to separate the default configuration settings from your personal settings to make updating as easy as possible. The data-format for you contacts in the database is stable (even for upcoming categories). Your contacts will always remain safe in the database and are not affected by an upgrade. There is no need to create a new database if you are upgrading. +
- +
- +
-Follow these steps and you should be on the safe side:+
  
-  - Read the changelog (check for changed database layout or other incompatibilities). 
-  - create a parallel installation of the addressbook and copy your old **//conf/config.php//** file to the new installation. 
-  - if you have a customized template you will have to migrate it manually. I still have to make minor changes in the default templates. Best bet would be to //diff// the old default template with the new one to see if anything has changed.  
-  - if everything works as expected, remove the old installation and rename/move your new installation to the old place. 
  
 [[changelog|The changelog can be found here]] [[changelog|The changelog can be found here]]
  
-==== Import ====+===== Import =====
  
 Import //should// work out of the box as the addressbook can auto-detect the most important encodings. The addressbook can detect vCards in the following encodings: Import //should// work out of the box as the addressbook can auto-detect the most important encodings. The addressbook can detect vCards in the following encodings:
Line 106: Line 52:
 All UNICODE encodings are auto-detected even if the file does not have a Byte Order Mark (BOM). The last encoding (here: ISO-8859-1) is a fallback encoding if auto-detection does not work (or if the file is not UTF encoded) and can be configured in the configuration file. All encodings supported by **iconv** are available. All UNICODE encodings are auto-detected even if the file does not have a Byte Order Mark (BOM). The last encoding (here: ISO-8859-1) is a fallback encoding if auto-detection does not work (or if the file is not UTF encoded) and can be configured in the configuration file. All encodings supported by **iconv** are available.
  
-=== Conversion ===+==== Conversion ==== 
 You can use a tool like //**iconv**// to change the encoding of your vCards. This is usually not needed. Only try it if the address book does not correctly auto-detect your vCards. Please file a bug report in that case. You can use a tool like //**iconv**// to change the encoding of your vCards. This is usually not needed. Only try it if the address book does not correctly auto-detect your vCards. Please file a bug report in that case.
  
Line 117: Line 64:
   iconv -f UTF-16 -t UTF-8 vcard.vcf > converted_vcard.vcf   iconv -f UTF-16 -t UTF-8 vcard.vcf > converted_vcard.vcf
  
-==== Permissions / Access Controls ====+===== Permissions / Access Controls =====
  
 Since version 0.98 the iAddressBook has advanced authentication support. Every logged in user has a set of actions which he is allowed to execute. That way we have complete control over who is allowed to add contacts and who may delete groups or export vCards. If the user is not logged in he can be optionally //mapped// to a guest account. The //guest// permissions can be configured as well. Let's see how it works. Since version 0.98 the iAddressBook has advanced authentication support. Every logged in user has a set of actions which he is allowed to execute. That way we have complete control over who is allowed to add contacts and who may delete groups or export vCards. If the user is not logged in he can be optionally //mapped// to a guest account. The //guest// permissions can be configured as well. Let's see how it works.
  
-=== Activate Authentication ===+==== Activate Authentication ====
  
   * First of all we have to activate authentication support (as long as this is disabled, everyone has full access to the iAddressBook). You can do this in **''conf/config.php''**.   * First of all we have to activate authentication support (as long as this is disabled, everyone has full access to the iAddressBook). You can do this in **''conf/config.php''**.
Line 135: Line 82:
 </code> </code>
  
-=== Creating User Accounts ===+==== Creating User Accounts ====
   * Now we have to setup user accounts. As with prior versions they are all managed inside **''/conf/auth.php''**. Let's create a user with username=fred, password=banana and permissions to execute the actions 'show' and 'img'. Fred should also be member of the group '@editors'. The ACL entry looks like this:   * Now we have to setup user accounts. As with prior versions they are all managed inside **''/conf/auth.php''**. Let's create a user with username=fred, password=banana and permissions to execute the actions 'show' and 'img'. Fred should also be member of the group '@editors'. The ACL entry looks like this:
  
Line 154: Line 101:
   * As the address book already comes with pre-defined groups (@admin, @editor, @guest) you will probably not need the 'permissions' field.    * As the address book already comes with pre-defined groups (@admin, @editor, @guest) you will probably not need the 'permissions' field. 
  
-=== Creating Groups ===+==== Creating Groups ====
  
-  * Groups are also maintained within **''/conf/auth.php''**. The syntax is basically the same as with user accounts. Groups only need the permissions field. It should be pretty self explanatory.+  * Groups are also maintained within **''/conf/auth.php''** and **''/lib/default/auth.php''**. The syntax is basically the same as with user accounts. Groups only need the permissions field. It should be pretty self explanatory.
  
 <code php> <code php>
-$auth['@admin']['permissions']  = array('show', 'img', 'search', 'edit', 'new', 'save', 'delete', 'delete_many',+$auth['@admin']['permissions']  = array('show', 'img', 'search', 'edit', 'new', 'save', 'delete', 'delete_many', 'select_letter', 'select_offset',
                                         'cat_select', 'cat_add', 'cat_del', 'cat_del_empty', 'cat_add_contacts', 'cat_del_contacts',                                         'cat_select', 'cat_add', 'cat_del', 'cat_del_empty', 'cat_add_contacts', 'cat_del_contacts',
-                                        'import_vcard', 'export_vcard', 'export_vcard_cat', 'export_csv_cat', 'export_ldif_cat',  +                                        'import_vcard', 'import_folder', 'export_vcard', 'export_vcard_cat', 'export_csv_cat', 'export_ldif_cat',  
-                                        'login', 'logout', +                                        'login', 'logout', 'reset', 
-                                        'debug', 'check');+                                        'debug', 'check', 'info');
  
-$auth['@editor']['permissions'] = array('show', 'img', 'search', 'edit', 'new', 'save', 'delete', 'delete_many',+ 
 +$auth['@editor']['permissions'] = array('show', 'img', 'search', 'edit', 'new', 'save', 'delete', 'delete_many', 'select_letter', 'select_offset',
                                         'cat_select', 'cat_add', 'cat_del', 'cat_del_empty', 'cat_add_contacts', 'cat_del_contacts',                                         'cat_select', 'cat_add', 'cat_del', 'cat_del_empty', 'cat_add_contacts', 'cat_del_contacts',
-                                        'import_vcard', 'export_vcard', 'export_vcard_cat', 'export_csv_cat', 'export_ldif_cat', +                                        'import_vcard', 'import_folder', 'export_vcard', 'export_vcard_cat', 'export_csv_cat', 'export_ldif_cat', 
-                                        'login', 'logout');+                                        'login', 'logout', 'reset');
  
-$auth['@guest']['permissions']  = array('show', 'img', 'search', + 
 +$auth['@guest']['permissions']  = array('show', 'img', 'search', 'select_letter', 'select_offset',
                                         'cat_select',                                          'cat_select', 
-                                        'export_vcard', 'export_vcard_cat', +                                        'export_vcard', 'export_vcard_cat', 'export_csv_cat', 'export_ldif_cat', 
-                                        'login', 'logout');+                                        'login', 'logout', 'reset'); 
 + 
 +$auth['@xml_client']['permissions']  = array('xml_version', 
 +                                        'xml_search', 'xml_search_email', 'xml_get_contact', 'xml_get_contacts', 'xml_count_contacts', 
 +                                        'xml_set_contact', 'xml_delete_contact', 
 +                                        'xml_import_vcard', 'xml_export_vcard');
 </code> </code>
- +==== Guest Account ====
-=== Guest Account ===+
  
   * The guest account is a normal user account an can also be configured like any other user account. The guest username is 'guest'. The default permissmions allow viewing, exporting and searching but do not allow changes to the iAddressBook.   * The guest account is a normal user account an can also be configured like any other user account. The guest username is 'guest'. The default permissmions allow viewing, exporting and searching but do not allow changes to the iAddressBook.
Line 191: Line 144:
 </code> </code>
  
-=== Actions Index ===+==== Actions Index ====
  
 The default action is 'show'. Whenever a user requests an action which he has no permission to execute the address book will execute 'show' instead. The default action is 'show'. Whenever a user requests an action which he has no permission to execute the address book will execute 'show' instead.
Line 223: Line 176:
 | check               | Check if the installation of iAddressBook works properly (database, file system access, etc.) | | check               | Check if the installation of iAddressBook works properly (database, file system access, etc.) |
  
 +===== XML-RPC API =====
  
 +[[docs:xmlrpc|The XML-RPC API has its own page here]]
  
-==== Contact Format ====+===== CardDAV Interface ===== 
 + 
 +[[docs:carddav|The CardDAV Interface has its own page here]] 
 + 
 +===== Contact Format =====
   * title   * title
   * firstname   * firstname
Line 252: Line 211:
   * creation date   * creation date
   * modification date   * modification date
 +  * UID
  
-=== Unsupported fields ===+==== Unsupported fields ====
   * maidenname (X-MAIDENNAME)   * maidenname (X-MAIDENNAME)
   * custom dates (X-ABDATE)   * custom dates (X-ABDATE)
Line 260: Line 220:
 These fields will not be included since I have absolutely no need for them. The current design is transparent enough for me. These fields will not be included since I have absolutely no need for them. The current design is transparent enough for me.
  
- 
-==== Templates ==== 
- 
-This section describes the HTML template that is currently used. In the current state the template system should be flexible enough to allow you to design a look and feel as you like (and not as the template system likes). 
- 
-The template files have the file ending ''.tpl''. The main file that keeps it all together is called **main.tpl**. 
- 
-  main.tpl 
-     | 
-     +- search.tpl 
-     | 
-     +- tpl_showcontactlist() 
-     |   +- contactlist.tpl 
-     |       +- tpl_contactlist() 
-     |           +- contactlist_item.tpl 
-     | 
-     +- tpl_showperson() 
-         +- person_empty.tpl 
-         | 
-         +- person.tpl 
-         |   +- tpl_addresses() 
-         |   |   +- address.tpl 
-         |   | 
-         |   +- tpl_phones() 
-         |   |   +- phone.tpl 
-         |   | 
-         |   +- tpl_emails() 
-         |   |   +- email.tpl 
-         |   | 
-         |   +- tpl_chathandles() 
-         |   |   +- chathandle.tpl 
-         |   | 
-         |   +- tpl_urls() 
-         |   |   +- url.tpl 
-         |   | 
-         |   +- tpl_relatednames() 
-         | 
-         +- person_edit.tpl 
-             +- tpl_include() 
-             |   +- person_edit_phones.tpl 
-             | 
-             +- tpl_include() 
-             |   +- person_edit_emails.tpl 
-             | 
-             +- tpl_include() 
-             |   +- person_edit_urls.tpl 
-             | 
-             +- tpl_include() 
-             |   +- person_edit_relatednames.tpl 
-             | 
-             +- tpl_include() 
-             |   +- person_edit_chathandles.tpl 
-             | 
-             +- tpl_include() 
-                 +- person_edit_addresses.tpl 
- 
- 
- 
-  * //tpl_showcontactlist()// creates the list of contacts. It basically just inserts the file **contactlist.tpl** 
-  * //tpl_contactlist()// iterates over all contacts and outputs one **contactlist_item.tpl** per contact. 
- 
- 
-  * All other functions work the same way, you should get the hang of it. Remark that **person_edit.tpl** does not call any //tpl_functions// since i thouhgt it would be easier to just inline all the code. Other suggestions are welcome. I have never done a template system before, so it might still have some inconsitencies. 
  
  
-~~DISCUSSION:off~~ 
  • docs.1196281037.txt.gz
  • Last modified: 17-11-2016 12:33
  • (external edit)