DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

EXT: ast_addresszipsearch

Author:Kasper Skårhøj
Created:2002-11-01T00:32:00
Changed:2005-01-07T17:43:20
Description:ZIP Code Search Tool
Author:Andre Steiling
Email:steiling@pilotprojekt.com
Info 3:
Info 4:

EXT: ast_addresszipsearch

Extension Key: ast_addresszipsearch

Copyright 2004, Andre Steiling, <steiling@pilotprojekt.com>

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3

- a GNU/GPL CMS/Framework available from www.typo3.com

Table of Contents

EXT: ast_addresszipsearch 1

Introduction 1

What does it do? 1

Screenshots 1

Users manual 2

Adminstration 2

Configuration 3

Different layouts 3

Search modes 3

CSS styles 3

Reference 4

Known problems 4

To-Do list 5

Changelog 5

Introduction

What does it do?

The extension 'ZIP Code Search Tool' offers a simple forntend plugin for searching in tt_address records based on the zip code. E.g. you can use it for offering an easy access to a dealer list including hundrets(?) of records: Would you like to browse in x pages for getting your preferred dealer? Just enter your zip code and get a list of dealers only in your environs.

Following features are included:

  • Divided field CODE in FE plugin for searching in zip codes of different countries; part one will be the country selector, just enter what ever you want, e.g. 'DE' or 'de' for german addresses, but remember to put your 'country selector' into the tt_address field 'country' too. You see, even every string you enter is your selector, not only a country shortcut! The secound part represents the maximum length of the ZIP code thats belongs to your selected country and it´s optional.
  • Automatically complement of the zip code string, e.g. in germany you have a five-digit zip code, so the search string '48' will find all records beginning width '48'.
  • Supports output of the first image that is found in an address record - optional a placeholder image, if no one is found.
  • Supports alternative layouts for easy creating different css controlled result boxes.
  • Supports to search modes: 'single' and 'range'. Background of this feature: Connecting several ZIP codes and ranges to only one record. See section Configuration -> SearchMode for details.
  • The extension is fully CSS based - no tables are used. Also it´s included as a HTML template for easy editing.

Screenshots

img-1 The search form:

img-2 The result page:

Users manual

Download the extension from the repository and install it!Now you can create a content element of type 'plugin' on any page you want, select ' ZIP code search for tt_address ' and fill in your preferred ' search selector string ' in field CODE. Select the base/ storage pages(s) for your address records. If you don´t know what to enter as ' search selector string ', ask your Typo3 administrator for help or scroll down and feel like an admin by reading the section 'Administration' ;-).

img-3 In the screeshot the ' search selector string ' is 'DE'. So all records according to the database field ' country ' in tt_address are selected, if the value is 'DE'.

Adminstration

After installation the extension needs some configuration of your tt_address records to work correct: The database field 'country' needs to set to the string you entered in the field CODE of the FE plugin, e.g. your typed in 'DE' the plugin will find only records with 'DE', yah!? So you can create different search criteria in different search tools/ pages.

So far, so good, the extension is now ready to work.

Configuration

If you have entered your' search selector string ' in the CODE field of your FE plugin and the same string in the field 'country' of your address records the extension will work currectly. But you also extend the CODE by the maximum length of your ZIP code / your preferred country: Therefore you have to enter a slash ' / ' and the ZIP code´s maximum length after your' search selector string '.So, 'DE/5' will print out only a more detailed information for the user like this:

“Search result in ZIP code 48xxx : 5 hits” instead of “Search result in ZIP code 48 : 5 hits”.

This options adds as many 'x' as needful for the country´s maximum ZIP code length, but you will not need this for the search operation in order to work correctly!

((generated))

HTML template

The layout of the form is determined by the HTML template associated with the plugin. The default template provided with the plugin is: EXT:ast_addresszipsearch/pi1/tmpl_zipsearch.html

Different layouts

In the HTML template you will find two markers to render the address boxes: ###SEARCHRESULT_LIST_A### and ###SEARCHRESULT_LIST_B###. By default both markers are used to output the result, but you can optinaly use only the first marker. See section reference for details.

Search modes

Normaly only one zip code is part of an address record, but what will be if your record has several codes, e.g. a salesperson who is responsible for a huge trading area? You have to add a range of codes to only one record and therefore you can use the following format and the extension will do the rest:

Your salesperson covers all codes from 40000-48999 and from 50000-53999 (German ZIP code format) so you add 40000|48999,50000|53999 to the field ZIP of your record.

| is acting as “from” “till” of a range, separates different ranges, this is optinal

To avoid a lack of space in the database table, the extension will alter the field 'zip' (in tt_address) to type 'tinytext'.

NOTE: Mode 'range' will only work with ZIP codes based on integers for now! Therfore YOU have to add the ZIP code´s maximum length to the field CODE, see Configuration -> ' search selector string' above!

CSS styles

This extension needs some css styles declaired in setup: _CSS_DEFAULT_STYLE. Please copy these styles in your own external css file to avoid overhead ... Following styles ar needed and you are free to change them like you need it:

#tx_astaddresszipsearch_pi1_form fieldset {border: 1px solid #7C7C7C;}

#tx_astaddresszipsearch_pi1_form div.row {clear: both; padding-top: 1em;}

#tx_astaddresszipsearch_pi1_form div.spacer {clear: both;}

#tx_astaddresszipsearch_pi1_form div.row span.label {float: left; width: 47%; text-align: right; margin: 0; padding: 0;}

#tx_astaddresszipsearch_pi1_form div.row span.formw {float: right; width: 50%; text-align: left; margin: 0; padding: 0;}

#tx_astaddresszipsearch_pi1_form .input {width: 60%; background- color: #FFFFFF; border: 1px solid #7C7C7C;}

#tx_astaddresszipsearch_pi1_form .text {width: 60%; font-size: 95%; background-color: #FFFFFF; border: 1px solid #7C7C7C;}

#tx_astaddresszipsearch_pi1_form .submit {background-color: #FFFFFF; border: 1px solid #7C7C7C;}

#tx_astaddresszipsearch_pi1_res div.adrboxA {float: left; width: 47%; margin-bottom: 2em; text-align: left;}

#tx_astaddresszipsearch_pi1_res div.adrboxB {float: right; width: 47%; margin-bottom: 2em; text-align: left;}

#tx_astaddresszipsearch_pi1_res div img {float: right; margin: 0 40px 0 10px;}

#tx_astaddresszipsearch_pi1_res div h4 {margin-top: 0; margin- bottom: 5px;}

#tx_astaddresszipsearch_pi1_res div.spacer {clear: both;}

Reference

You can influence many many many details by the power of Typoscript! Here it comes :-)

templateFile

Property

templateFile

Data type

string

Description

The HTML template you want the extension to use.

Default

searchMode

Property

searchMode

Data type

string

Description

Forces the extension only to search in a single zip or in a range of zip codes. Selector value could be: single or range

Normaly only one zip code is part of an address record, but what will be if your record has several codes, e.g. a salesperson who is responsible for a huge trading area? You have to add a range of codes to only one record and therefore you can use the following format and the extension will do the rest:

Your salesperson covers all codes from 40000-48999 and from 50000-53999 (German ZIP code format) so you add 40000|48999,50000|53999 to the field ZIP of your record.

| is acting as “from” “till” of a range

, separates different ranges, this is optinal

NOTE: Mode 'range' will only work with ZIPcodes based on integers!

Default

single

showAddress {

Property

showAddress {

title = 0

name = 1

ZIP = 1

address = 1

city = 1

phone = 1

fax = 1

mobile = 0

email = 0

WWW = 0

desc = 0

}

Data type

boolean

Description

Witch data from the address record should be renderd in the result view? Just switch the coloums on or off. The default configuration you see under property!

Default

See -> property

resultSorting

Property

resultSorting

Data type

string

Description

Comma-separated list of any tt_address field for sorting the result.

Default

zip,title

showResultHeader

Property

showResultHeader

Data type

boolean

Description

Result header: "Search result in ZIP code xx: y hits", switch it on/off

Default

1

showSearchInResult

Property

showSearchInResult

Data type

boolean

Description

The search box below the result, switch it on/off

Default

1

showBoxesLayout

Property

showBoxesLayout

Data type

boolean

Description

Alternative layout for the result view, uses marker LIST_A and LIST_B or only LIST_A by switching it of

Default

1

showImgInResult

Property

showImgInResult

Data type

boolean

Description

Shows a assigned image to the address record in the result view

Default

1

showNoImgAvailable

Property

showNoImgAvailable

Data type

boolean

Description

Shows placeholder image if showImgInResult is 1 and no image is found in the adress record

Default

1

clickImgEnlarge

Property

clickImgEnlarge

Data type

boolean

Description

Enable Typo3 clickEnlarge if showImgInResult is 1

Default

1

imgMaxW

Property

imgMaxW

Data type

boolean

Description

Max. image width in pixels, default is 96 according to the placeholder image thats comes with the extension

Default

96

noImgAvailableSrc

Property

noImgAvailableSrc

Data type

string

Description

The placeholder image: If no image is found in the address record, show this one

Default

[tsref:(cObject).TEST]

Known problems

- No problems are currently known.

To-Do list

  • Add a form selector for the frontend to let the user choose the country. By the way you will not need to serve serveral plugins and pages for different countries.
  • Some more result layouts by time ...

Changelog

  • 0.1.0 – 0.2.0 : Initial release (something like a case study ;-) )
  • 0.3.0 : Documentation added and killed some bugs
  • 0.4.0 – 0.4.1 : Some bugs are gone, you don´t want to know !!!
  • 0.4.2 : Added two-part field CODE in FE plugin, image support and alternative layouts for the result. More suppler support for different countries and ZIP codes length by a free editable string you enter.
  • 0.4.3 : Different enhancements, bug fixes
  • 0.4.4 – 0.4.6 : More suppler at all! Now you can switch on and off nearly everthing that could be renderd.
  • 0.5.6 : Add “searchMode”: Now you can search in a single ZIP code or a range of codes, see documentation.

img-4 EXT: ast_addresszipsearch - 5