Arrange2Drive Dokumentation

Arrange2Drive Dokumentation für 3.2.2 und davor

Dokumentation für Arrange2Drive 3.2.2 und davor

Table of Contents

  1. Basic information
  2. About Arrange2Drive
  3. Installation
    1. Short installation overview
    2. Updating from Arrange2Drive 2.x to Arrange2Drive 3.1 in JOOMLA! 2.5
    3. Configuration
      1. First configuration after installation or update
      2. Basic Configuration
      3. Country Settings
      4. Display Settings
      5. jQuery
      6. Prices
      7. Places
        1. Configuration of predefined or fixed places
      8. Mobile Settings
      9. Vehicle Emission
    4. Adding phone field in native JOOMLA! user profiles
    5. Predefined list of places / locations
    6. Multi currency options
  4. Available Add-Ons
    1. Linkgenerator Component
    2. Custom View Module
    3. CO2 Emission Module
  5. Troubleshooting
    1. jQuery problems
  6. License
  7. Sources and Acknowledgements

1. Basic information

Welcome to the Arrange2Drive manual. For a better intelligibility all JOOMLA! labels or commands, that in this manual will be referred to are marked blue and bold, for example Extension Manager. This makes it easier for you to find the right labels or commands in the backend of JOOMLA!.

2. About Arrange2Drive

The basic idea of the carpool component for JOOMLA was developed by Lukas Chrzanowski - Vogel in case of his Bachelor-Thesis (2011) at the University of Applied Sciences in Trier at the Faculty of Environmental Planning/Enviromnental Technology at the Birkenfeld Campus in the course "Media and Computer Science". The title of this Thesis is "Creation and Evaluation of an Agency for Arranged Lifts for the Rural Area as a Joomla Based Component".

The main aim of that component is to improve the mobility in the rural area and complement the deficient public transport, especially the commuter traffic. Furthermore a positive contribution for the environmental protection can be reached. But with this component several different areas of application are possible. After graduation the Arrange2Drive project is constantly under development, so finally the third version will now be presented.

3. Installation

3.1 Short installation overview

  1. After log in to the JOOMLA! backend
  2. go to: Extensions
  3. → Extension Manager
  4. → choose the component zip file and press Upload & Install
  5. → after successful uploading click on Options of the Arrange2Drive component and configure the component completely (you can ignore “Mobile Settings”)
  6. go to: Menus
  7. → add / define in the menu you want your menu items for your carpooling service

The following menu items available to show in the front end

  1. Add a lift
  2. Show all offered lifts
  3. Show all wanted lifts
  4. Search lifts
  5. DriveAlert – Subscribe mask (mask to add a notification)
  6. Drive Alert – Unsubscribe (do not add to the menu while using user registration)
  7. DriveAlert overview for registered users (overview for registered users)
  8. Lift overview for registered users (overview for registered users)

3.2 Updating from Arrange2Drive 2.x to Arrange2Drive 3.1 in JOOMLA! 2.5

While updating from an older Arrange2Drive version in JOOMLA! 2.5 you don´t have to uninstall the old version. Now the update will just update your system and also the data base. So all your entries and data will not get lost!

Updating from an older Arrange2Drive version is quiet easy. Users of JOOMLA! 2.5 please follow the same steps as described in 3.1 in this manual. After successful updating you have to configure the component again! Especially the Allow user registration in the Arrange2Drive Configuration must be determined for your carpooling service now. So first please choose a mode!

3.3 Configuration

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

This is the third point Allow user registration in the Basic Configuration below.

Basic Configuration

  • Email Admin
    • Here you must define one administrator of the carpooling service
  • Notify admin
    • Here you can set if the admin, defined above, will be automatically informed about each new entered lift / ride
  • Allow user registration
    • This is new since Arrage2Drive 3.0! Here you have to define the mode of your service. This should not be changed after your service got online! Otherwise problems can occur with the user management and the belonging of entries
  • 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
  • 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
  • reCaptcha public key
    • If the point above is set to Yes, use reCaptcha you have to create an account on Googles reCaptcha program and type in here your reCaptcha public key
  • reCaptcha private key
    • If the parameter Captcha Settings is set to Yes, use reCaptcha you have to create an account on Googles reCaptcha program an type in here your reCaptcha private key
  • 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
  • Using http or https (new since 3.1)
    • Here you have to choose the protocol your system is running with (http or https)
  • Using Jomsocial (new since 3.1)
    • Since A2D 3.1.x the carpooling software component is connected to Jomsocial while running with user registration. Choose this option only to Yes, if you have already properly installed Jomsocial!
  • Jomsocial telephone (new since 3.1)
    • While using Jomsocial with custom profile fields, you can enter here the field code of the telephone to be displayed in the detail sites, e.g. FIELD_MOBILE
  • Jomsocial gender (new since 3.1)
    • While using Jomsocial with custom profile fields, you can enter here the field code of the gender to be displayed in the detail sites, e.g. FIELD_GENDER

Country Settings

  • Country code e.g. DE
    • Type in the short code of your country, e.g. for Germany → DE
  • Your time zone
    • Choose here your time zone
  • System of measurement
    • Choose the system of measurement to display the distances and calculate the radius search correctly

Display Settings

  • Date Format
    • Choose here your date format for example dd.mm.YYYY for e.g. 24.12.2012
  • 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 (new since 3.1)
    • Here you can set the standard map zoom above your region. We recommend to use 5 or 6.
  • Gender options (new since 3.1)
    • 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 (new since 3.1)
    • 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 (new since 3.1)
    • Here you can choose if after entering a ride an overlay with a Facebook share button should be shown or not.

jQuery

  • jQuery
    • If is set to Yes, the jQuery 1.9.0 library will be loaded by the component
  • jQuery UI
    • If is set to Yes, the jQuery UI 1.10.0 custom library will be loaded by the component
  • jQuery noConflict Option an (neu seit 3.2)
    • Aktiviert den jQuery noConflict Modus für die Arrange2Drive jQuery Bibliotheken

To guarantee a smoothly functionality of this component, both parameter should be set to Yes! When disabling one or both mentioned above parameter, the functionality of the component can not be guaranteed! So please disable them only, when you are exactly knowing what you are doing!

Notice, that other components or the new JOOMLA! templates are also including jQuery libraries by default. For a smoothly functionality there should be just one jQuery library on a single site! See the point Troubleshooting in this manual.

Prices

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

  • 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

Places

Places are new since Arrange2Drive 3.2!

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 of back-end Places options:

fixed-departure

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

 

(verworfen seit A2D 3.2.1 - Ihr Template muss die mobile Ansicht unterstützen)

 

The mobile settings are bound to the jQuery library.

  • Mobile view
    • Here you can enable the mobile display mode for mobile devices like smart phones or tablets. If you are using a template which is already mobile device ready, so set the Mobile view to No
  • Mobile id position 1 to 5
    • Here you can type in the id of a container to be displayed below the Arrange2Drive component. You can display up to 5 positions by identifying them via their id
  • Mobile class position 1 to 5
    • Here you can type in the class of a container to be displayed below the Arrange2Drive component. You can display up to 5 modules / positions by identifying them via their class. Please keep guaranteed, that this class position is unique in your document. This can be useful to display modules via the Module Class Suffix.

Vehicle Emission

Here you can set the average fuel consumption per 100 km for the different vehicles. The emission counter calculates only approximately values. Exact values can not be calculated, because it depends on the exact individual vehicle emission and the interfered number of passengers to each lift / ride. The here calculated approximately values are only valid per each successful lift / ride.

  • Average fuel price (new since 3.1)
    • Here you have to enter an average fuel price / litre in your region. Since A2D 3.1.x on each detail site, below the map, the amount of saved fuel and money will be displayed.

3.4 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.5. 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.6. 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

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

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!">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!