Arrange2Drive Dokumentation

Arrange2Drive Dokumentation seit 3.3.0

Documentation for Arrange2Drive 3.3.0

Table of Contents

  1. Basic information
  2. About Arrange2Drive
  3. Installation
    1. Short installation overview
    2. Updating from Arrange2Drive 2.x to Arrange2Drive 3.3.0 in JOOMLA! 2.5.x or 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. jQuery (deprecated since 3.3.0)
      7. Prices
      8. Places
        1. Configuration of predefined or fixed places
      9. Mobile Settings (deprecated since 3.2.1)
      10. Vehicle Emission (deprecated since 3.3.0)
    4. Configuration via Arrange2Drive configuration
      1. Vehicle Settings
      2. Layout Settings
    5. Adding phone field in native JOOMLA! user profiles
    6. Predefined list of places / locations
    7. 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 this 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)
  9. Edit user details (edit Arrange2Drive user profile) since A2D 3.3.0

3.2 Updating from Arrange2Drive 2.x to Arrange2Drive 3.3.0 in JOOMLA! 2.5.x or 3.x

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!

IMPORTANT: After updating you must to the components "Options" and save them again!

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
  • reCaptcha public key - (verworfen seit A2D 3.3.0)
    • WICHTIG: Wenn Sie reCaptcha benutzen, so muss das reCaptcha Plugin aktiviert und dort die Keys eingetragen werdne
  • reCaptcha private key - (verworfen seit A2D 3.3.0)
  • 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

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 the A2D 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 - 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!
  • Link to the JomSocial profile - While using the JomSocial Profile, you can set a link in the detail site to the users profile
  • Jomsocial telephone - 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 - 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

 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
  • 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

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.
  • 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.
  • 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 (since version A2D 3.3)
    • (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 (since version A2D 3.3)
  • Calender time range
    • Choose from 1 to 24 months the calenders time range (since version A2D 3.3)
  • Show ext. search
    • Show the extended search options (gender, smoker) (since version A2D 3.3)

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

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 (since version A2D 3.3)
  • 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

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:

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 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.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

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: