Address List

Extension Key: tt_address

Copyright 2006-2007, Ingo Renner, <typo3@ingo-renner.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

Addresses	1

Introduction	1

What does it do?	1

Screenshots	1

Users manual	2

Creating a Group	2

Assigning groups to an address record	3

Creating a Plugin Content Element and adding addresses to it	3

Adminstration	4

Updating from tt_address versions before 2.0.0	4

Configuration	5

Reference	5

Known problems	6

To-Do list	7

Introduction

What does it do?

The extension comes with a plugin where either single tt_address records can get selected or as an alternative the selection can be made through groups. That group selection can have AND or OR combinations of groups. Additionally the plugin offers to select a template to display the address records.

In both, the tt_address records and the plugin the groups can be selected through a tree view like that known from DAM or tt_news.

The advantage of using address records through the plugin instead of inserting them with the “Insert record” content element especially pays of with larger sites with a lot of address records, so you can assign the groups to addresses and on a page you make a selection by groups, thus if a person changes its function you don't need to search the whole site where that person is shown. Instead you just assign his old group to a new person and it is exchanged through out the whole site.

Screenshots

This is the plugin with the tree selector.

Users manual

Creating a Group

At first you need to create some groups for your address records. To do this navigate to a sysfolder and switch to the list view. Click “Create new record” at the bottom, now click Address Group.

In that form the title is the only required field, if you have created some groups already you will see them in the tree view and can select one as the parent group for the group you are about to create. At the bottom you can add a small note or description to the group.

Assigning groups to an address record

Adding groups to an address is as easy as adding a parent group to another group. Open the address record you want to assign a group to or create a new address record, go to the bottom of the form and add one or more groups from the right box by clicking on the group.

When adding groups to an address there's one point to be aware of: The top most group you assign to an address can be put out in the front end later, so you might want to choose that carefully or switch positions of the selected groups.

Creating a Plugin Content Element and adding addresses to it

Go to the page view and navigate to the page where you want to insert one or more addresses. Create a new content element and in the “new content element wizard” scroll down to the plugins section and select “Address Selection”

Now on the first tab [1] you can add address records to the plugin, the second tab [2] is for selecting a template for how the address should look like, this needs to be configured by your administrator. If there're no templates on the second tab, just save the content element once and after saving it they should apear.

In the Single addresses field [3] you can select addresses by using the known element browser. Even if the addresses selected here would be selected via groups, too they do not appear twice in the front end.

In the groups field [4] you can select groups from the tree view. These groups get combined either by AND or by OR [5]. That means you can select addresses which are in all of the given groups (AND) or they are required to be in at least one of the given groups (OR).

The starting point does not necessarily need to be set. The extension can be configured to work with a default setting which needs to be adjusted by your administrator. If you set a startingpoint here, it will override that default setting that might be set. The recursive field [7] sets how deep in the page tree beginning from the startingpoint the system should look for addresses with the given groups.

Adminstration

There's not much to say about administration here, just install the extension. After installation you need to configure the extension. For that, please consult the next section.

Updating from tt_address versions before 2.0.0

If you're updating from a tt_address version < 2.0.0 and the addressgroups extension there's an update script for you!

Go to the extension manager, select tt_address and in the upper right corner you'll find a drop down menu with an element called “UPDATE!”. The update script will split names from the old combined name field to first and last name. Although there's also a new middle name field it is not used by the update script. Names are split by comma (expecting the part in front of the comma to be the last name and the part after the comma to be the first name) or by space (expecting the first word to be the first name and the part after the first space to be the last name even if there're more space). Records which couldn't be updated automatically will be highlighted in the update log afterwards, edit them by hand.

If you have installed EXT:addressgroups this will also be taken into account. The update script copies the groups to the new tt_address native table and rebuilds the relations. Addressgroups plugin content elements will also be updated to tt_address plugin content elements.

After that you need to update your HTML templates by hand, the ###NAME### marker from addressgroups is not available in tt_address, instead you need to use the respective markers ###FIRSTNAME##, ###MIDDLENAME###, and ###LASTNAME###. Also don't forget to update the TS from plugin.tx_addressgroups_pi1 to plugin.tx_ttaddress_pi1!

If you're using other extensions which extend tt_address there's one more thing which needs your attention:
After you updated your records to use the split name fields you can disable the old field from the extension manager. Althoug you disabled the old combined name field from displaying in the back end tt_address takes care of writing changes from the split name fields back to the combined name field. From the extension manager you can configure the format to use or which fits your previous record naming. Thus other extensions can still use the old – now internal – combined name field.

Configuration

When starting to configure the extension you should create a separate TS extension template for it where you do all the configuration for this extension. That extension template can then get included in the root template. In the extension template add the static TS configuration, otherwise it wont work!

Reference

Property:	Data type:	Description:	Default:
templatePath	string	Defines the path where the templates are located. Put templates in that folder and they will be listed automatically in the plugin. You can also add a small graphic showing how the address will be displayed. That graphic need to have the same name as the template but must be a gif. This basically works like the template selector from MTB2.	fileadmin/templates/
defaultTemplateFileName	string	Defines the default template file.	addressgroups_default.htm
pidList	int	A comma separated list of integers representing page ids where to get the address records from	0
recursive	int	Defines how many levels to search for tt_address records from the given pages in pidList.	0
wrap	string	wraps the whole output	
singleSelection	stdWrap	Comma separated list of tt_address record uids, will be overriden with flexform data	
groupSelection	string	Comma separated list of tt_address group record uids, will be overriden with flexform data	
combination	int	0 = AND, 1 = OR	0
sortByColumn	string	Defines by which tt_address column you want to sort, if an invalid column is given it's set to 'name' Valid columns for sorting: uid, pid, tstamp, name, title, email, phone, mobile, www, address, company, city, zip, country, image, fax, description	name
sortOrder	string	Defines the sorting order, DESC for descending and ASC for ascending. Any other (invalid) value is set to ASC.	ASC
templates.[TEMPLATE_NAME]	wrap	wraps a single address	
templates.[TEMPLATE_NAME]	allWrap	wraps the whole output of the specific template	
templates.[TEMPLATE_NAME].[FIELD_NAME]	stdWrap	The configurations for the different templates goes here. Let's have a look at an example: Let's assume you have three different html templates: * template_1.htm * other_template.htm * different_template.htm TEMPLATENAME is the file name without the extension. Now you can configure each of these templates: Example: plugin.tx_ttaddress_pi1 { templates.template_1 { email.wrap = E-Mail: |<br /> email.required = 1 ... } templates.other_template { ... } templates.different_template { ... } } each standard tt_address field can be configured with stdWrap properties. Like wrap and required which will propably be the most important and most used ones. Here's the list of default fields you can use inside each template configuration: gender, first_name, middle_name, last_name, title, email, phone, mobile, www, address, building, room, birthday, organization, city, zip, region, country, image, fax, description, mainGroup You can control max width and hight of an image with image.file.maxW and image.file.maxH An example template can be found in the res folder in the extension. This template also contains a list of all available markers.	
templates.[TEMPLATE_NAME.][subparts]		Each template configuration can have subparts. You can define as many subparts as like, stdWrap properties will apply to them. If you have a subpart configuration templates.other_template { ... subparts { xyz { } abc { } } } you can use these subparts in your HTML template like <!-- ###SUBPART_XYZ### begin --> ... <!-- ###SUBPART_XYZ### end --> <!-- ###SUBPART_ABC### begin --> ... <!-- ###SUBPART_ABC### end --> Subparts have a special condition property: hasOneOf, with this property you define that an address record must have at least one of the defined name fields before the whole subpart is shown: subparts.abc.hasOneOf = city, zip, country	

[tsref:plugin.tx_ttaddress_pi1]

Known problems

None so far

To-Do list

Nothing yet, please add your ideas for improvements to the bugtracker.

Address List - 7

Address List

Kasper Skårhøj

2002-11-01T00:32:00

Ingo Renner

Kasper Skårhøj