Home

Welcome, this wiki is for documentation of adx.
You can find here information how adx works, tips and tricks, etc.

Table of contents:

• What is adx?
• Live Demo
• Getting started
• Requirements
• IMPORTANT: Browser workaround needed for local usage ("file://...")
  • Workaround for Firefox 68 and newer for local usage ("file://...")
  • Workaround for Chromium based browsers for local usage ("file://...")
    • Workaround for Chrome under Windows
    • Workaround for Chromium under Ubuntu
    • Workaround for other Chromium based browsers like Chrome, Opera, Vivaldi, Brave, etc under Ubuntu
  • Obsolete browsers (not tested any more)
• Import contacts to adx
• Export contacts from adx
  • Export contacts to vCard (vcf file)
  • Export contacts via QR Code (vCard)
  • Export contacts to whatever format you want
• Web browser search in your adx contacts
  • Integrate adx in browser search: Chrome/Chromium
  • Integrate adx in browser search: Firefox (option 1)
  • Integrate adx in browser search: Firefox (option 2)
• Settings
• URL parameters
• Securing your data in adx
  • Basic access authentication over HTTPS
  • Others ways to secure adx

What is adx?

adx (addressbook.xml) is a simple but massively web enabled address book in your web browser (no server components needed).

Supported web accounts: Skype, LinkedIn, Facebook, Xing, ebay, Flickr, Picasa, YouTube, MySpace, Twitter, Soup, ICQ, AIM, YIM, MSNIM, Jabber, Picasa, Google, Spin.de, last.fm, SourceForge, DeviantArt, identi.ca, bebo, studiVZ, qype.com, brightkite.com, hi5.com, quarterlife.com, amiestreet.com, hellotxt, etc. See [Accounts] for full list

How it works: addressbook.xml + XSLT = HTML in your web browser

Live Demo

http://elektronengehirn.net/addressbook/addressbook.xml

Getting started

• Download from Sourceforge latest adx zip file
• Unzip downloaded adx zip file
• Load addressbook.xml in a web browser.
  Note: in case of local usage (file://...) you need to apply a workaround in your browser to allow local file access, see #important-browser-workaround-needed-for-local-usage
• Click on the entries to expand details (TODO: Add animated gif)
• Most entries in contact details are clickable (e.g. direct calling phone numbers via Skype, address lookup in map providers like Google Maps or Open Street Map)

To add contacts just edit addressbook.xml in a text editor of your choice

Requirements

Any modern web browser should work (e.g. Firefox, Safari, Chrome and any other Chromium-based browser like Edge, Vivaldi, Opera, Brave, etc). All of them have support for XSLT which is needed for adx to transfrom XML to HTML.

For online usage (http(s)://...) no further requirements beside that you need to host the two files addressbook.xml and adx2html_phonelist.xsl on any web server

For local usage (file://...) most modern browser don't allow local file access any more out of the box. Therefore you need to configure your browser to allow local file access! See details in following.

IMPORTANT: Browser workaround needed for local usage ("file://...")

A workaround for your browser is only needed if you want to use adx locally (file://...) instead of online (http(s)://....).
The reason is that most browsers don't allow loading additionally local files. But adx needs exactly one more file to load: adx2html_phonelist.xsl. Only with the XSL file adx can transform the XML to a HTML web site.

A general workaround without need to change anything for your browser is to use a local web server and access adx by something like http://localhost/adx/addressbook.xml

Read on for browser specific workarounds.

Recommended browser for using adx from local disk: Firefox

Reasons:

• Convenient: Firefox can be configured internally in an easy way (about:config) with exact one change. Chromium based browsers need to be started with an additional command line parameter which needs to be done by adapting the browser start script
• Global: Firefox configuration needs one global change. Chromium based browsers need to ensure that all relevant start scripts are adapted. Actually the very first start of the browser matters. If you start the Chromium based browser by clicking on a link the additional parameter may not be passed.
• Sustainable: In Firefox the configuration change needs to be done exactly once (and remains also after Firefox version updates). For Chromium based browsers the change may need to be re-applied on start scripts as they may be replaced on browser updates.

Workaround for Firefox 68 and newer for local usage ("file://...")

If you open addressbook.xml in Firefox with file://.../addressbook.xml and you see something like following you need to apply the workaround for Firefox below.

You may also see an empty web site. You can also double-check the error on Firefox Console (by right-click on website -> Inspect). You will see something like following error:
Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at file:///.../adx2html_phonelist.xsl. (Reason: CORS request not http).

Root cause:
With introduced restrictions to access local files in Mozilla Firefox version 68, adx does not work any more out of the box (because the opened addressbook.xml in the browser is not allowed to access the needed XSL file adx2html_phonelist.xsl to do the transformation to HTML). for details about restriction reasons see here.

Workaround:
In order to be still able to run adx locally ("file://...") you can apply a workaround by changing internal Firefox config. But please be aware that disabling this security setting is at your own risk!
1. Enter about:config as URL in Firefox
2. Set security.fileuri.strict_origin_policy to false. See "security.fileuri.strict_origin_policy" for more details.
Note: Setting privacy.file_unique_origin to false allowed also local file access but seems not to work any more since Firefox 95.

Workaround for Chromium based browsers for local usage ("file://...")

All Chromium based browsers (version 5 or newer) need a workaround if you want to use adx locally (if you use "file://..." to access adx):

• Google Chrome: workaround needed
• Microsoft Edge (Chromium based): workaround needed
• Opera: workaround needed
• Vivaldi: workaround needed
• Brave: workaround needed
• Chromium: workaround needed
• Other Chromium based browsers: not tested; same or similar workaround probably needed

Root cause:
Chromium's more restrictive security model for local access starting with version 5. See here for more info.

Workaround:
Start browser with command line param "--allow-file-access-from-files"

In following you see two How Tos which should be similar on any other OS.

Workaround for Chrome under Windows

1. Search for your shortcut icon for starting Chrome on your Windows desktop.
2. Right-click on the Chrome shortcut and select "Properties"
3. Append in field "Target": --allow-file-access-from-files

Notes:

• It's important that the very first instance of Chrome was started with parameter --allow-file-access-from-files. You can check this in Chrome by entering URL chrome://version (see screenshot below).
• As Chrome/Chomium uses background tasks even if it's closed a restart of the whole OS is the safest way to ensure that the additional paramter is applied.
• It might be necessary to apply this on every shortcut you use. E.g. in start menu, on desktop, etc.
• You may not be able to access properties of a pinned Chrome icon to the task bar. Try unpin Chrome shortcut. Start Chrome with an adjusted Chrome shortcut (with --allow-file-access-from-files) and pin again.

Workaround for Chromium under Ubuntu

Following was tested with Ubuntu 11.10 - 20.04 under Gnome 3. Add needed command line parameter in file /usr/share/applications/chromium-browser.desktop:

1. Load file in browser. E.g. open a terminal window and enter sudo gedit /usr/share/applications/chromium-browser.desktop
2. Replace in text editor Exec=/usr/bin/chromium-browser %U with Exec=/usr/bin/chromium-browser --allow-file-access-from-files %U
3. As Chrome/Chomium uses background tasks even if it's closed a reboot is the safest way to ensure that the additional paramter is applied.

If it's still not working you can doublecheck with URL chrome://version if the parameter --allow-file-access-from-files is listed:

Attention: This option is applied to all chromium instances started inside Gnome desktop. If you have security concerns you should start chromium directly from terminal with command line parameter chromium-browser --allow-file-access-from-files.

Note: This change gets overwritten on each update of the browser and must be repeated. An automated way to check and update the desktop file is therefore recommended.

Workaround for other Chromium based browsers like Chrome, Opera, Vivaldi, Brave, etc under Ubuntu

Workaround should be similar as described above for Chromium.

Filenames of the different browsers in /usr/share/applications/:
- Opera: e.g. opera.desktop
- Vivaldi (stable): e.g. vivaldi-stable.desktop
- Brave: e.g. brave-browser.desktop
- Google Chrome: ?
- ...

Obsolete browsers (not tested any more)

• Microsoft IE (Internet Explorer version 11 worked but not tested any more)
• Obsolete version of Microsoft Edge based on short living render engine EdgeHTML (worked but superseded by Edge based on Chromium first announced 2018)

Import contacts to adx

Importing contacts
- Online importer for Open Contacts (a freeware address book tool for Windows)
- Opent Contacts has itself various import possibilities which can be used as intermediate step before importing to adx. Supported import formats are Outlook, vCard, Mozilla, Eudora, CSV, LDIF and more.
- You can create your own XSLT transformator to import any XML based format to adx (e.g. based on the XSLT file from Open Contacts to adx)

Otherwise add your contacts manually to [addressbook.xml] with a text editor of your choice.

Export contacts from adx

Below you can find different ways to export contacts from adx to a vCard file or QR Code.

Note:
If you want to import it afterwards on Android with your contacts app, the vCard (vcf file) is strongly recommended. In my experience, it works much better than importing via QR Code although the same contacts app is used. It seems there's different algorithm/library is used for importing from vcf or QR code.
Normally the contact apps on Android provide under "Settings" a possbility to import a vcf file with vCards.

Export contacts to vCard (vcf file)

Native vCard export via adx:

• All contacts in one vcf file: in adx menu => Export => All
• One contact per vcf file: in adx menu => Export => One (formerly known as "Specific") enables for each contact a link vCard to download a vcf file
• Note: On native exporting the contacts are completely processed in the web browser. So, your contact data is not leaving your web browsor and therefore not uploaded to any server. Privacy matters!

Or export via Firefox browser plugins like Operator or Tails Export

How to use the vCard files:

• Android phones can import easily vCard contacts (Android >= 2.1). Go to contacts in your phone and press 'menu' where you can find an import functionality from your SDCard (e.g. in 'options').

• Thunderbird (version 16 as of now) has several issues on importing vCard data. The Thunderbird extension MoreFunctionsForAddressBook imports vCards much better.

• Evolution Email solution can also import vCard files.

• As vCard is the standard format for contact interchange there are many tools which support vCards.

Export contacts via QR Code (vCard)

A QR code is a two-dimensional barcode which can contain vCard data. Following example contains a full contact:

A QR code can be optically read out e.g. by any smartphone with a camera. If your device does not support reading QR Codes out-of-the-box you need to install an app for reading QR Codes from your app store.

adx uses a open source QR code generator library to generate the QR code completely offline. So, your contact data is not leaving your web browsor and therefore not uploaded to any server.

Export contacts to whatever format you want

You can also create a own XSLT document to export the contacts to the format of your choice.

Web browser search in your adx contacts

You can register adx as browser search engine. Add a url template like following consisting of your addressbook.xml (works online and offline). "%s" will be replaced by your search term.

Examples:

• file:///home/username/addressbook.xml?searchfilter=%s
• http://myhost.com/addressbook.xml?searchfilter=%s

You need to replace the path to your addressbook.xml (works online and offline).

Integrate adx in browser search: Chrome/Chromium

In Chrome this can be added very easy in Preferences -> Manage Search Engines.

Integrate adx in browser search: Firefox (option 1)

You can easily integrate adx search by "Add a keyword for this search" in Firefox.
Afterwards you can search for it by entering in address bar: {keyword} {search term(s)} (e.g. adx acme).
See following video with instructions:

In the background a bookmark is created with keyword (here "adx") which can also be edited:

For definition of the default URL parameters, see setting "browser_searchengine_parameters" [UserSettings].

Integrate adx in browser search: Firefox (option 2)

Firefox integration can be done also via a bookmark with above url pattern. Important is to apply a keyword for the bookmark (e.g. "adx") in order to call it from the url bar:

Once added as bookmark (here with keyword "adx") you can search from the address bar:

Settings

You can adjust many visual and functional settings like changing map provider for addresses (e.g. from Open Street Maps to Google Maps or any other), enable/disable contact sorting, use your own logo, etc.

Recommended: Since adx v1.40 you can adjust the settings directly inside the addressbook.xml file. See [UserSettings] for details.

The old and alternative way is to set the same settings in XSL File (adx2html_phonelist.xsl). But on every new version of adx you need to adapt the settings in the XSL file again. If you change the settings in the XSLT note that you must use "$YES"/"$NO" instead of "YES"/NO" compared to the addressbook.xml file.

Note: URL parameters can also be used to adjust a subset of settings. But this is more recommended when you need a link where the contact list shall be filtered, e.g. to a specific entry. See below for details.

URL parameters

URL parameters cover only a small subset of settings you can directly adjust on your adx web site. Example in order to show contact details by default: http://elektronengehirn.net/addressbook/addressbook.xml?showdetails=1

This is handy in order to bookmark adx with your needed settings and especially when you want to provide a link with certain filter(s) applied:

1. Adjust settings in your adx web site
2. Clicking on "Save" (upper right corner in adx) and press OK to apply it directly in your web browser
3. Now you can bookmark or share this link

Example with all URL parameters: http://elektronengehirn.net/addressbook/addressbook.xml?showdetails=1&showheader=1&showexport=1&tagfilter=Musician&searchfilter=Raph&frequencyhigh=1&frequencymedium=1&frequencylow=1&fontsize=1.1em

adx can also be directly started with text for QR code generator, e.g.: https://elektronengehirn.net/addressbook/addressbook.xml?qr=Hello%20world

Note: Cookies are not used at all by adx.

Securing your data in adx

Basic access authentication over HTTPS

Provides an easy way to encrypt your data and set user/password, e.g. if you want to publish your adx on the internet.

Two independent techniques are combined:

• Basic access authentication for user credentials with user and password (see Wikipedia)
• HTTPS for encryption of transport (avoid sniffing your adx data) (see Wikipedia)

Protection:

• What is protected: all files (including addressbook.xml with your sensitive contact data) are encryped while transport from server to browser via HTTPS-protocol
• Who can access: Everybody who has the credentials (user/password)

Security notes:

• See article on StackOverflow about security issues
• Warning: If you forget the "s" in https your password (from Basic Authentication) will be sent unecnrypted and can be easily sniffed (see next item)
• Do NOT use Basic access authentication alone because the password is only BASE64-encoded. This is no encryption and can be sniffed in clear text when the browser sends it to the server.

How to setup:

• Create a directory on your web server. e.g. "demo-https-basicauth"
• Enable Basic authentication for the new directory and define user and password to access it (for more details check your hoster's documentation)
• Enable HTTPS on your web server (for more details check your hoster's documentation)
• Upload your adx files to the new directory on your web server (e.g. addressbook.xml, adx2html_phonelist.xsl, qrcodeUTF8.min.js)
  Now you should be able to access your adx accordingly.

Demo: https://elektronengehirn.net/addressbook/demo-https-basicauth/addressbook.xml (user: "demo", password: "httpsBasicAuth")

Others ways to secure adx

Basically every possibility to encrypt or protect you data on the web. E.g. OAuth, ...