.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt ================================== Advanced cal / partner integration ================================== :Author: Thomas Kowtsch :Created: 2009-07-13T22:07:05 :Changed by: Thomas Kowtsch :Changed: 2009-07-14T13:27:18.880000000 :Classification: adv_calpartner :Keywords: forAdmins, forDevelopers, forIntermediates :Author: Thomas Kowtsch :Email: typo3@thomas-kowtsch.de :Info 4: :Language: en |img-1| |img-2| Advanced cal / partner integration - adv\_calpartner .. _Advanced-cal-partner-integration: Advanced cal / partner integration ================================== Extension Key: adv\_calpartner Language: en Keywords: forAdmins, forDevelopers, forIntermediates Copyright 2000-2008, Thomas Kowtsch, 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.org .. _Table-of-Contents: Table of Contents ----------------- `Advanced cal / partner integration 1 <#1.Advanced%20cal%20/%20partner%20integration|outline>`_ **`Introduction 3 <#1.1.Introduction|outline>`_** `What does it do? 3 <#1.1.1.What%20does%20it%20do_|outline>`_ `Screenshots 3 <#1.1.2.Screenshots|outline>`_ **`Users manual 4 <#1.2.Users%20manual|outline>`_** `FAQ 4 <#1.2.1.FAQ|outline>`_ **`Administration 5 <#1.3.Administration|outline>`_** `FAQ 5 <#1.3.1.FAQ|outline>`_ **`Configuration 6 <#1.4.Configuration|outline>`_** `FAQ 6 <#1.4.1.FAQ|outline>`_ `Reference 6 <#1.4.2.Reference|outline>`_ **`Tutorial 7 <#1.5.Tutorial|outline>`_** **`Known problems 8 <#1.6.Known%20problems|outline>`_** **`To-Do list 9 <#1.7.To-Do%20list|outline>`_** **`ChangeLog 10 <#1.8.ChangeLog|outline>`_** `Important guidelines 11 <#2.Important%20guidelines|outline>`_ **`HowTo update a manual to the new layout 12 <#2.1.HowTo%20update%20a %20manual%20to%20the%20new%20layout|outline>`_** **`Issues with Open Office documentation for TYPO3 13 <#2.2.Issues%20w ith%20Open%20Office%20documentation%20for%20TYPO3|outline>`_** `Inserting images 13 <#2.2.1.Inserting%20images|outline>`_ `Paragraph styles 13 <#2.2.2.Paragraph%20styles|outline>`_ `Linking 14 <#2.2.3.Linking|outline>`_ `Meta data and updates 14 <#2.2.4.Meta%20data%20and%20updates|outline>`_ `Help by documentation.openoffice.org 14 <#2.2.5.Help%20by%20documentation.openoffice.org|outline>`_ .. _Introduction: Introduction ------------ .. _What-does-it-do: What does it do? ^^^^^^^^^^^^^^^^ This extension is about to deliver some advanced features to tighten the integration between calendar base (cal) and partner framework (partner) extensions, esp. regarding location relationship and display. Main feature is to provide access to the relationship definitions defined by using partner as location definition. In terms of a calendar, this means to allow - showing different levels in the hierarchy, depending on the view - give users a tree-style input form for easier event creation/editing *(planned for release version 0.9)* - limit handling of relationships to some well-defined relationship UIDs - limit calendar output to certain locations *(planned for release version 2.0)* .. _Screenshots: Screenshots ^^^^^^^^^^^ The location “Leuben” has 3 relations assigned to it: |img-3| An event with location “Himmelfahrtskirche Leuben” can be rendered with it's full location (using cal's default ###LOCATION### marker), but this extension also allows now to show also a more generic location such as the region (“Leuben”) where the event takes place. This is useful for public calendars showing a large number of events that are spread over larger areas where users want to see the region at a glance. |img-4| |img-5| *Default location rendering for single event view* *Short rendering in month view showing only the region instead of the full-detailed standard rendering* .. _User-Administration-manual: User/Administration manual -------------------------- .. _Installation: Installation ^^^^^^^^^^^^ .. _Step-1-Install-the-extension: Step 1: Install the extension """"""""""""""""""""""""""""" The extension can be installed through the typical TYPO3 installation process using the Extension Manager. It requires to to have the calendar base extension (extension key: cal) installed in version 1.2 or above. *At the time of creating the extension and writing this manual, this requires to install a development snapshot release (available under `http://svn.webempoweredchurch.org/snapshots/show/calendar)! `_* .. _Step-2-Add-static-TypoScript-template: Step 2: Add static TypoScript template """""""""""""""""""""""""""""""""""""" |img-6| Open your page template (or create a new extension template), and add the “Default cal/partner location settings” to the “Include static (from extensions):” list. The default configuration is to allow users only to select locations with type “Organization”, no other filter is set in defaults. If this fits your needs, you do not need to touch the configuration. .. _Step-3-Adjust-the-settings: Step 3: Adjust the settings """"""""""""""""""""""""""" Please refer to the chapter “configuration” to get an overview about the ways you can tweak the extensions behaviour. Instead of writing error-prone text to the “constants” field it might be better to use the “Constants Editor” instead: |img-7| .. _Step-4-Adjust-your-calendar-s-templates-where-needed: Step 4: Adjust your calendar's templates where needed """"""""""""""""""""""""""""""""""""""""""""""""""""" If you want to make use of different location rendering, you need to adjust your calendar template files. Please refer to the documentation of cal to learn more details about how to use custom template files. New introduced markers for the locations are described in the “Configuration” chapter .. _FAQ: FAQ ^^^ F: While trying to install the extension, the Extension Manager complains about a wrong version of cal... A: Most likely, cal's version 1.2 is not available in the TER yet. At the time of writing this manual, it was still in development, requiring to manually install a development snapshot. .. _Configuration: Configuration ------------- The extension is configured trough constants in the page template. Please see the table below for valid variables and values. .. _Constants-Reference: Constants Reference ^^^^^^^^^^^^^^^^^^^ Available constants for plugin.tx\_advcalpartner: .. ### BEGIN~OF~TABLE ### .. _relationshipTypePids: relationshipTypePids """""""""""""""""""" .. container:: table-row Property relationshipTypePids Data type string Description Comma-separated list of relationship record Ids. This list is used as filter when building up the hierarchy tree between location records: - If it is not set, all relationships will be taken into account - If set to “1,4” only relationships with these IDs will be handled to keep locations together Default Not set .. _limitToOrganizations: limitToOrganizations """""""""""""""""""" .. container:: table-row Property limitToOrganizations Data type boolean Description If set to true, only locations of type “Organization” will be shown to users when creating new records / edititing existing ones. Default yes .. _limitToLocations: limitToLocations """""""""""""""" .. container:: table-row Property limitToLocations Data type string Description Comma-separated list f location record IDs If set, only events with locations in this list will be shown. Default Not set .. _includeSubLocations: includeSubLocations """"""""""""""""""" .. container:: table-row Property includeSubLocations Data type boolean Description Show events with locations listed in “limitToLocations” and auto- include their sub-locations. Sub-locations will be found by taking “relationshipTypePids” into account! Default no .. ###### END~OF~TABLE ###### .. _Markers-Reference: Markers Reference ^^^^^^^^^^^^^^^^^ Available markers that can be used in custom template files: .. ### BEGIN~OF~TABLE ### .. _ADVCALPARTNER-LOCATION-0: ###ADVCALPARTNER\_LOCATION\_0### """""""""""""""""""""""""""""""" .. container:: table-row Marker ###ADVCALPARTNER\_LOCATION\_0### ###ADVCALPARTNER\_LOCATION\_1### ###ADVCALPARTNER\_LOCATION\_2### … … ###ADVCALPARTNER\_LOCATION\_9### Description The number reflects what item to show in the hierarchy. “0” means the top-most item (root element). If the tree has only 3 levels (e.g., metropolitan area, region, building; see example section for details) and a marker for level 5 is placed in the template, the most detailed available level is used. .. ###### END~OF~TABLE ###### .. _generated: ((generated)) """"""""""""" .. _Example: Example ~~~~~~~ To limit relationship handling to relationships with ID 1 and 2, your configuration could look like this: :: plugin.tx_advcalpartner { relationshipTypePids = 1,2 limitToOrganizations = 1 limitToLocations = includeSubLocations = 0 } .. _Tutorial-Example: Tutorial/Example ---------------- Let's assume that we have the following structure that is used within one installation to feed several domains / localized sites from the same data source: :: |-> Parish 1 | |-> Region 1_1 | | |-> Building 1_1_1 | | |-> Garden-area 1_1_1_1 | | |-> Garden-area 1_1_1_2 | | | |-> Region 1_2 | | |-> Building 1_2_1 | | |-> Building 1_2_2 | | |-> Building 1_2_3 | | |-> Garden-area 1_2_1 | | | |-> Region 1_3 | |-> Building 1_3_1 | |-> Parish 2 |-> Region 2_1 |-> Building 2_1_1 | |-> Room 2_1_1_1 | |-> Room 2_1_1_2 | |-> Building 2_1_2 | |-> Garden-area 2_1_1 Both parish's hold their data together in one Typo3 installation, but data rendering for the public calendars is separated for the web site of Parish 1, the site of Parish 2 and a third (joined) site showing all events. As the locations of Parish 1 are widely spread, visitors are mainly interested in having an *rough* overview of what events take place when and where. A month-like preview is used to look 6 weeks ahead in the future (realized by cal\_weekpreview); but in addition, there is the need to have dedicated list views for Region 1\_1, 1\_2 and 1\_3. So, the overview pages with week previews get a new marker placed near to the event title: **###ADVCALPARTNER\_LOCATION\_1###** ,the page showing all events from both parishes renders **###ADVCALPARTNER\_LOCATION\_0###** to distinguish both easily, a CSS hover shows some more details by rendering **###ADVCALPARTNER\_LOCATION\_1###** . This structure itself is modeled with separate partner records, each of type “Organization”. Using them with cal 'as is' adds another problem to editors: The drop down field for location selection is sorted alphabetically, resulting in :: Building 1_1_1 Building 1_2_1 Building 1_2_2 Building 1_2_3 Building 1_3_1 Building 2_1_1 Building 2_1_2 Gardenarea 1_1_1_1 Gardenarea 1_1_1_2 Gardenarea 1_2_1 Gardenarea 2_1_1 Parish 1 Parish 2 Region 1_1 Region 1_2 Region 1_3 Region 2_1 Room 2_1_1_1 Room 2_1_1_2 Not really userfriendly... .. _To-Do-list: To-Do list ---------- - give users a tree-style input form for easier event creation/editing *(planned for release version 0.9)* - limit calendar output to certain locations *(planned for release version 2.0)* - improve source code documentation *(planned for release version 1.5)* .. _ChangeLog: ChangeLog --------- 8 .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. |img-2| image:: img-2.png .. :border: 0 .. :height: 21 .. :hspace: 9 .. :id: Grafik2 .. :name: Grafik2 .. :width: 87 .. |img-3| image:: img-3.png .. :align: left .. :border: 0 .. :height: 234 .. :id: graphics4 .. :name: graphics4 .. :width: 433 .. |img-4| image:: img-4.png .. :align: left .. :border: 0 .. :height: 140 .. :id: graphics2 .. :name: graphics2 .. :width: 219 .. |img-5| image:: img-5.png .. :align: left .. :border: 0 .. :height: 125 .. :id: graphics3 .. :name: graphics3 .. :width: 451 .. |img-6| image:: img-6.png .. :align: left .. :border: 0 .. :height: 61 .. :id: graphics5 .. :name: graphics5 .. :width: 266 .. |img-7| image:: img-7.png .. :align: left .. :border: 0 .. :height: 233 .. :id: graphics6 .. :name: graphics6 .. :width: 413