Arrange2Drive Dokumentation seit 3.3.2

Details
Erstellt am Montag, 24. November 2014 10:30
Zuletzt aktualisiert am Mittwoch, 26. November 2014 21:00

Übersetzung folgt in den kommenden Tagen

Allgemeine Informationen zur Konfiguration und Installation der Komponente

Inhaltsverzeichnis

  1. Grundlegende Informationen
  2. Über Arrange2Drive
  3. Installation
    1. Schneller Installationsüberblick
    2. Update von Arrange2Drive 2.x zu Arrange2Drive 3.3.2 in JOOMLA! 2.5.x oder 3.x
    3. Configuration via component parameters
      1. First configuration after installation or update
      2. Basic Configuration
      3. User Management
      4. Country Settings
      5. Display Settings
      6. Currencies / Prices
      7. Places
        1. Configuration of predefined or fixed places
    4. Configuration via Arrange2Drive configuration
      1. Vehicle Settings
      2. Custom Fields
      3. Layout Settings
      4. Bootstrap Layout
    5. Adding phone field in native JOOMLA! user profiles
    6. Predefined list of places / locations
    7. Multi currency options
    8. How to set up Community Builder fields
  4. Available Add-Ons
    1. Linkgenerator Component
    2. Custom View Module
    3. CO2 Emission Module
  5. Troubleshooting
  6. License
  7. Sources and Acknowledgements

1. Grundlegende Informationen

Willkommen zur Arrange2Drive Dokumentation. Zur besseren Verständlichkeit, stellen wir im folgenden alle Joomla! Menüpunkte, Felder oder Befehle, auf die von dieser Dokumentaion aus verwiesen wird, blau und fett dar, wie z.B. der Menüpunkt Erweiterungen. Dies erleichtert die Suche im Joomla! Backend nach den richtigen Feldern oder Menüpunkten. 

2. Über Arrange2Drive

Die Grundidee einer Mitfahrbörse für Joomla! entwickelte Lukas Chrzanowski-Vogel im Rahmen der Bachelor-Thesis (2011) im Fachbereich Umweltplanung / Umwelttechnik im Studiengang Medieninformatik an der FH Trier am Standort Umwelt-Campus Birkenfeld. Der Titel dieser Thesis lautet "Erstellung und Bewertung einer Mitfahrbörse für den Ländlichen Raum als Joomla Basierte Komponente".

Das Ziel ist, die oft mangelhaften Verbindungen des öffentlichen Verkehrs im ländlichen Raum, besonders im Pendlerverkehr, zu ergänzen und die Organisation von Mitfahrgelegenheiten deutlich zu erleichtern. Parallel dazu kann ein positiver Beitrag zum Umweltschutz beigetragen werden und hilft den Anbietern / Interessenten, gerade in Zeiten hoher Kraftstoffpreise, Geld zu sparen. Zusätzlich wird mit jeder gelungenen Fahrgemeinschaft auch die Verkehrssituation verbessert.

Seit 2011 wird die Mitfahrbörse ständig aktualisiert und verbessert.

3. Installation

3.1 Schneller Installationsüberblick

  1. Nach dem einloggen in das Joomla! Backend
  2. gehe zu: Erweiterungen
  3. → Erweiterungen
  4. → wähle die ZIP Datei und klicke auf Hochladen & Installieren
  5. → klicke nach der Installation oben rechts auf Optionen innerhalb der Arrange2Drive Komponente und konfiguriere die Komponente, speichern nicht vergessen!
  6. gehe zu: Menü
  7. → erstelle die benötigten / gewünschten Menüpunkte der Mitfahrbörse
    1. Falls die Mitfahrbörse mit Benutzerverwaltung funktionieren soll, so ist es wichtig, dass je ein Menüpunkt für
      1. "Meine Fahrten",
      2. "Meine DriveAlert's",
      3. "Mein Konto" erstellt wird! Bei diesen drei Menüpunkten ist es ratsam, die Zugriffsebene auf Registered zu setzen.

Die folgenden Menüpunkte / Masken sind für das Frontend im Menü zuweisbar

  1. Fahrten eintragen
  2. Alle Mitfahrangebote anzeigen
  3. Alle Mitfahrgesuche anzeigen
  4. Fahrten suchen
  5. Benachrichtigungsservice eintragen - DriveAlert (Maske zum eintragen einer Benachrichtigung)
  6. Benachrichtigungsservice austragen - DriveAlert (Maske zum austragen einer Benachrichtigung)
  7. DriveAlert - Überblick für registrierte User
  8. Fahrten - Überblick für registrierte User
  9. Edit user details / Benutzerdaten verwalten (Hier kann der Benutzer seine eigenen Daten verwalten ) seit A2D 3.3.0

3.2 Update von Arrange2Drive 2.x zu Arrange2Drive 3.3.2 in JOOMLA! 2.5.x oder 3.x

Falls Sie von einer älteren Arrange2Drive Version in Joomla! 2.5.x oder 3.x aktualisieren möchten, so müssen Sie nicht zwangsweise die alte Version deinstallieren. Bei einer Aktualisierung / Update wird das System, also die Arrange2Drive Komponente samt der Datenbank angepasst und aktualisiert. Alle Einträge, falls vorhanden, bleiben erhalten.

Wichtig: Vergewissern Sie sich, dass Sie nach jedem Update die Optionen der Arrange2Drive Komponente überprüfen und erneut speichern.

3.3 Configuration via component parameters

First configuration after installation or update

After installation you have first to think about the mode in which you want to run your carpooling service. There are two modes available:

  1. carpooling service with the native JOOMLA! user registration
  2. carpooling service without user registration

We recommend to use with user registration!

This is the first point User registration in the User Management tab in Arrange2Drive options learn more

Basic Configuration

  • Email Admin
    • Here you must choose one administrator for the carpooling service
  • Notify admin
    • Here you can set if the admin, defined above, will be automatically informed about each new entered lift / ride
  • Delete past entries
    • This point defines what to do with past entries. After termination they can be deleted or still be in the data base set to unpublished
  • Sorting
    • Decides how to sort the overview sites by default
  • Captcha settings
    • Here you have three options. You can disable the captcha options, use a simple calc captcha or use the more advanced reCaptcha. When using reCaptcha, you have to create an account on http://www.google.com/recaptcha
    • IMPORTANT: for reCaptcha you must activate the reCaptcha plugin and fill in there the public and private key! After this you can use reCaptcha in Arrange2Drive
  • Accept the TOS
    • Here you can set if the user should accept your own terms of service while entering a lift / ride
  • URL to the TOS
    • If you have set the point above to Yes, you have to type in here the complete URL to your TOS
  • Bootstrap (since version A2D 3.3.1)
    • Enable the native Joomla Bootstrap and JS
    • Since version A2D 3.3.2 Bootstrap must be activated, but uses it's own CSS file

Screenshot:

basic

User Management

You can use Arrange2Drive with or without user registration. Therefore we offer an own extended user management.

We recommend to use Arrange2Drive with user registration and the Arrange2Drive user profiles, but of course you can use Joomla profiles or other community components.

IMPORTANT: Choose before going online, if you want to run your system with or without user registration. Do NOT change between these options while having entries in your Arrange2Drive database. This will lead to errors!

  • User registration - Choose if the system should run with user registration
  • User management - Choose which extended user management you want to use
  • Link to user profile - While using the Arrange2Drive Profile, you can set a link in the detail site to the users profile
  • Profile image size - The size in KB of the users profile image
  • Using Jomsocial - deprecated since A2D 3.3.2
  • Community Builder
    • Link to the profile - Shows a link to the Community Builder profile page
    • Community Builder Telephone - Custom field name for the telephone
    • Community Builder Gender - Custom field name for the gender
  • JomSocial
    • Link to the profile - Shows a link to the JomSocial profile page
    • JomSocial Telephone - Custom field name for the telephone
    • JomSocial Gender - Custom field name for the gender

 Screenshot:

user

Country Settings

  • Country code e.g. DE
    • Type in the short code of your country, e.g. for Germany → DE
  • Multilingual - Choose if your site is multilingual or not
  • System of measurement
    • Choose the system of measurement to display the distances and calculate the radius search correctly
  • Your time zone
    • Choose here your time zone
  • Latitude
    • Here you can center the map over the region where your service will be used mostly. Type in here the latitude. Center over Germany → 51.
    • Search in Google for your values with get latitude longitude
  • Longitude
    • Here you can center the map over the region where your service will be used mostly. Type in here the longitude. Center over Germany → 10
  • Map zoom
    • Here you can set the standard map zoom above your region. We recommend to use 5 or 6.

Screenshot:

country

Display Settings

  • Date Format
    • Choose here your date format for example dd.mm.YYYY for e.g. 24.12.2012
  • Alt. jQ date
    • Alternative jQuery date format.
  • Alt. PHP date
    • Alternative PHP date format.
  • Show gender options 
    • Here you can choose, if you want to display the gender-specific options. So while entering a ride the user must choose her/his gender and the gender with whom she/he wants to travel with

gender

  • Show author link
    • Here you can allow a back link to the Arrange2Drive project page. Thank you very much, if you´ll set this to Yes!
  • Show contact details 
    • Here you have to choose, if visitors of the detail sites are able to see the contact details without being logged in. It is not connected to the privacy settings while entering a ride.
  • Show overlay 
    • Here you can choose if after entering a ride an overlay with a Facebook share button should be shown or not.
  • Show on map button
    • (Yes / No) - Enables a show on map button and hides the map while loading a detail site. Otherwise the map will directly be shown.
  • Social networks
    • Show the social networks buttons on the detail sites 
  • Calender time range
    • Choose from 1 to 24 months the calenders time range
  • Show ext. search
    • Show the extended search options (gender, smoker)
  • Main Logo
    • Your main logo for the service (since version A2D 3.3.1)
  • Facebook Logo
    • Your Facebook share logor main logo for the service (since version A2D 3.3.1)

Screenshot:

display

jQuery (deprecated since 3.3.0)

If you need more information to older versions, so please take a look on the documentation for Arrange2Drive lower than 3.3.0

Currencies / Prices

Here you can configure the prices for the component and your local currency.

  • Show price
    • Choose if the price options should be available in the front-end
  • Currency code e.g. EUR
    • Here you can type in your currency ISO code to display your currency correctly. Euro → EUR
  • Start value 
    • Here you set the start value for the price list. By default it is set to 0, which means that a user can offer a lift / ride for free
  • Length of list 
    • Here you set the length of the list. By default it is set to 50, which means that the price list will be counted from 0,- to 49,-
  • Increase of prices 
    • Here you set the interval of the price (value). This is important for currencies with a high amount of figures 10000,-
  • Separator
    • Here you can set the separator for the decimal places, e.g. 9,50 EUR or 9.50 EUR
  • Intermediate steps
    • Here you can set the amount of intermediate steps for small values like 2,50 EUR
  • Decimal places
    • Here you can set the decimal place amount of each intermediate step, e.g. 2,50 or 2,25

Screenshot:

prices

Places

Here you can set separately predefined places for the departure and / or the destination!

  • Fixed departure
    • Here you can type in the predefined place for departure
  • Changeable
    • Here you can choose, if the place above may be changeable or should be fixed
  • Fixed destination
    • Here you can type in the predefined place for destination

Screenshot:

places

 

Configuration of predefined or fixed places

The predefined places for departure and / or destination can be used in two different ways.

  1. By using the correct place name like Berlin, Alexanderplatz, Germany
  2. By using an arbitrary name for a place like BIG Great Festival 2013

The point is, that the name of the place must be known by Google Maps and the request returns a valid place result. In the 2. point the result won't be valid, such a place does not exist in the world. Therefore the arbitrary name of the place must be described by adding the latitude and the longitude. This looks like this:

  • Name#latitude,longitude
  • BIG Great Festival 2013#51.754201,12.437725

First comes the NAME, followed by # and then by the correct latitude and longitude of that place! So with this additional information it is possible to display a different place name to each point of the map and get a valid place result returned by Google Maps. This can be very useful for companies or festivals...

Please note if using the arbitrary place names:

The first part of the whole string, the name, should not contain a comma without adding the country at the end. This is important for filtering the country out of the place names returned by Google Maps!

Correct: Berlin, Alexanderplatz, Germany
Not correct: Berlin, Alexanderplatz

Screenshot of a not changeable predefined destination:

fixed-places-front

Mobile Settings

(deprecated since A2D 3.2.1 - your template must be mobile ready)

If you need more information to older versions, so please take a look on the documentation for Arrange2Drive lower than 3.3.0

Vehicle Emission

(deprecated since A2D 3.3.0)

Since Arrange2Drive 3.3.0 vehicles can be edited and added in the Arrange2Drive new configurations options.

3.4. Configuration via Arrange2Drive configuration

This is new since Arrange2Drive 3.3.0. Here you manage easily vehicles or the layout of your carpooling service.

3.4.1 Vehicle Settings

Here you can manage the vehicles, which should be shown in the front-end. You can set the name, a language tag, the fuel consumption and the max. free seats of each vehicle.

While using your site multilingual and adding new vehicles, you must also extend your language ini files by the added vehicle language tag.

Example:

  • Vehicle: Motorcycle
  • Language tag: A2D_MOTORCYCLE
  • Line in your Arrange2Drive language ini file(s): A2D_MOTORCYCLE="Motorcycle in that language"

Screenshot:

vehicles

 

3.4.2 Custom Fields

Custom Fields are new since Arrange2Drive 3.3.2. You will find them in the Arrange2Drive back-end under the menu item "Configuration". Here you can manage your own input fields, e.g. for luggage or nationality.

You can add input field groups with the following options:

  • Group enabled / Group disabled
  • Field required / Field not required
  • Field copyable / Field not copyable
  • Field countable / Field not countable

It is possible to give your input group a name, a language tag and a short description.

Each group can have as much items as you want. Each item is described by:

  • Label (required)
  • Language tag (optional)
  • Value (predefined - not changeable)

Screenshot back-end:

custom-fields

Screenshot Custom Fields front-end:

custom-fields-front

 

3.4.3 Layout Settings

Since Arrange2Drive 3.3.0 the layout / colours can be managed easily via an own CSS and colour editor. So the layout and colour scheme can be customized in a few clicks! Using the colour picker it is possible to customize your Arrange2Drive sites in a few seconds.

You should use nearby the same colour depth / intensity for each colour as it is set in the basic preferences. You can't modify a single colour of a heading with the colour picker. You can only set a general colour scheme for the whole Arrange2Drive CSS file. Play around with the "Colour preferences" buttons to see how it is intended.

In the "Individualized CSS styles" text area you can also overwrite or put own CSS styles. These styles will be included in the main Arrange2Drive CSS. So there will be only one CSS file for the whole Arrange2Drive component.

Screenshot:

layout

 

3.4.4 Bootstrap Layout

New since A2D 3.3.2! Here you can manage the colours of the Bootstrap buttons which appear in Arrange2Drive.

bootstrap-layout

 

3.5 Adding phone field in native JOOMLA! user profiles

  1. Add Phone field in JOOMLA!
    1. Go to: Extensions
    2. → Plug-in Manager
    3. → Select from drop down list - Select Type - the value user
    4. → Select User - Profile
    5. → Set Status to Enabled
    6. → Disable all not required or optional fields and enable Phone in User profile fields for registration and administrator user forms and User profile fields for profile edit form under Basic Options on the right side

3.6. Predefined list of places / locations

Since Arrange2Drive 3.2 you can set predefined places for departure and destination. A list of places will be read out of a XML file. The information to the locations are stored in the locations.xml file in the front end includes folder. The locations.xml file in the Arrange2Drive component is delivered empty, so no predefined places will appear in the front end. Anyway the empty file must not be deleted! The empty file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<data>
    <place>
        <formPlace></formPlace>
    </place>
</data>

When you want to offer predefined places, you have to fill the XML file with information. Each record of a place in between <data></data> looks e.g. like this:

<place>
    <formPlace>London, United Kingdom</formPlace>
</place>

NOTE: The place must be a valid place or address returned by Google Maps. Otherwise the place wouldn’t be shown.

Example of some predefined locations (complete XML file content):

<?xml version="1.0" encoding="UTF-8"?>
<data>
    <place>
        <formPlace>London, United Kingdom</formPlace>
    </place>
    <place>
        <formPlace>Köln, Deutschland</formPlace>
    </place>
    <place>
        <formPlace>Alexanderplatz, Berlin, Deutschland</formPlace>
    </place>
    <place>
        <formPlace>Wien, Österreich</formPlace>
    </place>
    <place>
        <formPlace>Av. des Champs Élysées, Paris, France</formPlace>
    </place>
    <place>
        <formPlace>Warschau, Polen</formPlace>
    </place>
    <place>
        <formPlace>Rom, Provinz Rom, Italien</formPlace>
    </place>
</data>

Front end screenshots:

predefined-locations-3

predefined-locations-2

3.7. Multi currency options

Since Arrange2Drive 3.2  a multi currency option is available. Now there can be simultaneously any number of currencies while entering and editing an entry. Similar to the predefined places, the multi currency options will be set in a XML file.

The information to the multi currency options are stored in the currencies.xml file in the front end includes folder.

The currencies.xml file in the Arrange2Drive component is delivered empty, so no predefined multi currency options will appear in the front end. Anyway the empty file must not be deleted!

The empty file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<data>
    <currency>
        <language></language>
        <currencyCode></currencyCode>
        <startValue></startValue>
        <lengthList></lengthList>
        <increase></increase>
        <separator></separator>
        <intermediateSteps></intermediateSteps>
        <decimalPlaces></decimalPlaces>
    </currency>
</data>

While using just one currency, the XML file should not be modified. Then the options for the currency must be set in the JOOMLA back end in the Arrange2Drive component.

Example of three predefined currencies:

<?xml version="1.0" encoding="UTF-8"?>
<data>
    <currency>
        <language>de-DE</language>
        <currencyCode>EUR</currencyCode>
        <startValue>0</startValue>
        <lengthList>51</lengthList>
        <increase>1</increase>
        <separator>,</separator>
        <intermediateSteps>5</intermediateSteps>
        <decimalPlaces>50</decimalPlaces>
    </currency>
    <currency>
        <language>en-GB</language>
        <currencyCode>GBP</currencyCode>
        <startValue>0</startValue>
        <lengthList>36</lengthList>
        <increase>1</increase>
        <separator>.</separator>
        <intermediateSteps>10</intermediateSteps>
        <decimalPlaces>50</decimalPlaces>
    </currency>
    <currency>
        <language>pl-PL</language>
        <currencyCode>PLN</currencyCode>
        <startValue>0</startValue>
        <lengthList>151</lengthList>
        <increase>1</increase>
        <separator>,</separator>
        <intermediateSteps>10</intermediateSteps>
        <decimalPlaces>50</decimalPlaces>
    </currency>
</data>

Front end screenshot:

multi-currencies

 

3.8 How to set up Community Builder fields

Set up a Community Builder Field

  1. Go to your CB component and choose "Field Management"
  2. Create the field you need, e.g. for telephone or gender
  3. Copy the "Name", not the "Title" of the field and put the name, e.g. "cb_telephone" in your "Community Builder Telephone" field in the Arrange2Drive options

Screenshot of the Community Builder "Field Management":

cb-telephone-config

 

4 Available Add-Ons

The Add-Ons are not part of the of the Arrange2Drive component and must be purchased separately.

4.1 Linkgenerator Component

The Linkgenerator is useful for automatic and predefined inscribing of lifts for example to all types of occasions and predefined happenings.

If your Arrange2Drive carpooling service is open to all users, you can offer this Linkgenerator to your partner sites, to enable predefined inscribing of lifts from these third party sites. There can be e.g. a predefined departure, destination, date, type of a lift and so on. Demonstration of this component

4.2 Custom View Module

With the Arrange2Drive Custom View Module it is possible to show

  1. the recently added offered lifts / rides or
  2. the recently added wanted lifts / rides or
  3. both, recently added offered and wanted lifts / rides

on each module position you want! Demonstration of this module

4.3 CO2 Emission Module

The CO2 Emission Module shows the amount of the approximately calculated value for the CO2 emission economization. Its a sum of all active and past lifts / rides.

5 Troubleshooting

Since Arrange2Drive 3.3.0 you must not use a jQuery manager to run Arrange2Drive properly on your site. Please just ensure, that the Arrange2Drive jQuery library will not be excluded.

jQuery problems

The most known problems are associated with jQuery. If you are using jQuery driven templates or different modules or components, which need jQuery, please make sure, that the jQuery library or the jQuery UI is only once bound per web site. Everything else is unnecessary, increases traffic, loading time and leads to errors.

Your source code should NOT look like this:

jquery-problem

There are a lot of ways to avoid this, but this is not part of that manual. You can use plugins to import jQuery and manage them on several sites with the JS CSS Control or jQuery Easy. You can find them at http://extensions.joomla.org

If you are using JS CSS Control, you have to set up the Basic Options in this plugin that way:

  • jquery.min.js|option=com_arrange2drive

The first part jquery.min.js is the exact file name, that has to be disabled followed by the separator | and the "section" / part of your site where it has to be disabled option=com_arrange2drive - this should be on all sites of the Arrange2Drive component

To ensure a prefect running carpooling service it is highly recommended to use jQuery and the jQuery UI delivered with that Arrange2Drive installation package. If you have problems and need our help for a perfect running installation, please contact us via Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!

6 License

All license information you will find here: http://www.arrange2drive.com/license/

7 Sources and Acknowledgements

Big thanks and huge recognition to the following projects used also in Arrange2Drive: