EXT: abcourses¶

What does it do?¶

abcourses is an extension for offering your seminars, courses, or appointments in various ways. This extension aims to be compatible with the most requirements. So if you are looking for an extension to offer many courses and appointments, this extension is made for you. But if you need a solution which can be used right after installation (like plug'n play) than this is the wrong one. Abcourse is really flexible and it takes you some time to get in to it.

About the development¶

SYMPLASSON http://www.symplasson.de/ started the development of this extension in close collaboration with @b-networks http://www.ab-networks.de/ in 2005 to create a solution for offering different courses with several thousand appointments a year.

Since then, the development was continued along our customers requirements or our own ideas.

This extension is still under further development (if requested ;-) ) and is supported by Andreas Behrens (@b-networks; behrens@b-networks.de , Lüneburg, Germany) as well as by Stefan Precht ( sprecht@gmx.de , Hamburg, Germany)

Many people supported this extension within the last years. Independent from if it were just ideas, debugging or anything else. Here we want to say “thanks” for supporting the development to:

• IBS Schreiber Gmbh ( http://www.ibs-hamburg.com )
• Tallence GmbH ( http://www.tallence.com )
• Kanton Basel-Landschaft ( http:// :underline:`www.baselland.ch <http://www.baselland.ch/>`_ )
• as well as to all the others ...

Screen shots¶

You will find some more screen shots associated to the different views later in this documentation. These few screens are just for a small overview.

Important notice:

The information as displayed on this sample screens are only for demonstrating the possible look and feel of this extension. Description and content of courses are test-data, just like shown prices or other informations!

Abbildung 1: Sample view of course details

Abbildung 2: Another detail view. Highlighted area on the right is rendered by the Last-Minute short overview

Abbildung 3: Sample of a start screen. The input field is rendered with the search-view, the colored boxes are rendered with the category overview. Other parts are normal text content elements.

Category¶

Courses are associated with categories. For a category you can enter a title, a description and you can upload an image for representing the category.

Course¶

For a course you can enter the following:

• number
• title
• subtitle
• associate a category (category 1 : n courses)
• associate a type (type 1 : n courses)
• associate teaching aids (teaching aids n : m courses)
• teaser
• description
• associate pages with e.g. further informations
• upload files as an associated download for a course (max. 5)
• associate trainers (n : m)
• skill level (represented with a small icon)
• educational points (just for information)
• days (just for information of the course duration)
• contingent (just as information about the max. amount of participants)
• conditions (text input)
• conditions (reference to other course records)
• price (with or without VAT must be configured in TS)

Course type¶

A course type represents the skill level in another way than the value “skill level” (attr. of course records). You can only enter a title of a course type.

Teaching aids¶

You can only enter a title for this records. Teaching aids are associated to course records for information purposes.

Trainer¶

The data for trainer records are saved in tt_address records. This is the reason for the fact, that tt_address is required for the use of abcourses.

Please consider that only a few fields are used in the template for a trainer. These are:

• name
• title
• company
• image
• trainer number
• trainer position

The last two attributes come with abcourses and extends the tt_address table.

Event¶

Events are the records a user can subscribe to and are associated to one course record.

Available fields are:

• event number
• start-date for registration
• end-date for registration
• start-date and time of the first day
• end-date and time of the last day
• associated course (course 1 : n event)
• associated trainers
• subscribed participants ( this field is not in use currently. See also the To-Do section...)
• associated location (1:n)
• discount flag (if the price for this single event should differ to the base price as entered in the course record)
• discount value (enter a positive double value for raise, and a negative value for reduce the base price)
• last-minute flag (if activated and supported by the corresponding templates, a special css class can be associated to this event for highlighting this record in listings. Records marked as “last minute” are shown in last-minute views automatically)
• contingent amount (if contingent management is activated, this value limits the possible amount of subscriptions)
• subscriptions (this value is increased with each subscription and will be compared with “contingent amount” if contingent management is activated)
• associated arrangements (to offer additional accommodations)

Location¶

A location can be assigned to an event for informational purposes.

These attributes can be entered for location records:

• title
• street
• zip
• city
• phone
• fax
• email
• contact person
• informations (as reference to a page record with e.g. additional informations)

Category¶

To categorize your offered courses.

You can enter:

• title
• teaser
• image

Hotel¶

If you want to offer additional accommodations you have to enter some hotels and arrangements.

For a hotel you can enter:

• name
• subtitle
• link
• image (e.g. a logo)
• rating (0 start, 1 star ...)

Arrangements¶

To offer additional accommodations with an event you need to enter arrangements to assign them later with the events.

For this you can enter:

• backendname (as title in BE view)
• frontendname (as title in FE output)
• associated hotel (hotel 1 : n arrangements)
• price (if this is with or without VAT depends on the global tax configuration)

Please consider that there is not really an interface for subscribing an accommodation. It is only included in the confirmation email.

Categories overview¶

This view represents two views in one. At least one PlugIn with this view-type is required for abcourses.

On one hand this view-type can list all available categories, and on the other hand it can list all courses for one specific category. It depends on an URL parameter which view-type will be rendered. With a flag available in the FlexForm of the PlugIn, you can force the view- type to ignore the URL parameter and list the categories all the time. For example this is necessary if you have one page with two PlugIns of this view type and you want to show the courses of the category on the left and an overview of other available categories on the right.

The following two screens represents the “courses in this category” view.

Abbildung 4: Courses in one category 2

Abbildung 5: An example for two PlugIns with view-type category overview on one page

Both views based internally completely on the abcourses object layer. It is up to you and depends on the used template which information will be displayed. Read more about this later in the template section...

Mini search-box¶

This view renders only an input field for a textual search. You have to configure the page id of the result page to make it work... See one sample of this search-box at Abbildung 4

Search result list¶

Come on, just guess what it does :-) Not to derive from the name: The search result list will get the parameters from indexed_search input fields for look ups as well. So you can combine both plug ins on the same page...

Detail view¶

The detail view can show all informations associated with a course. It depends on the template what will be displayed. Please consider that this view is not completely based on the abcourses object layer! Why? Because the extension grew with the time and there was no object layer in the first version. So this is a relict from previous version. But although it contains the full scope of operation. Refactoring of this function is already on our to do list... Maybe the template structure for this view can change then.

Events will be only shown if it is possible to subscribe. As an exception you can configure the count of days events may be expired. These expired events will be shown but there is no subscribe link rendered for them.

See screen shots of this view at Abbildung1 and Abbildung3 .

Subscribe view¶

The user reaches the subscribe view automatically (because the default subscribe view is configured via TS), if he clicks on an event for which a subscription is possible. Depending on the template the subscribe view shows all informations about the course, the event and all records which you can assign via the BE.

Depending on TS configuration and one more template snippet you can create a form for subscribing an event (including server side input validation). And if available, the user could request an accommodation as well!

After successful registration the user is redirected to a “thank you” side (a page record from you cms) and an email will be send to the admin as configured in TS (and optionally to the user). During the registration a hook is called which you can use for whatever you want it to do...

You can even use this PlugIn for direct subscriptions. Just add it via TYPO3 BE and select an event in the BE! Please don't do this for the default subscription view as configured in TS.

Abbildung 6: Front-End subscribe form

Abbildung 7: BE FlexForm PlugIn configuration

Read more about setup, hook and template later in this documentation.

Last minute short¶

Deprecated. Use the selectedEvents view.

This view was used for short listings of last minute events. Since you can use the “selectedEvents” view for this (since version 1.3.X) it is not recommended to use this short view. Also an argument for this is, that the selectedEvents view use the abcourses object layer. See the selectedEvents section of this document for further informations.

Last minute detailed¶

Deprecated. Use the selectedEvents view.

This view was used for short listings of last minute events. Since you can use the “selectedEvents” view for this (since version 1.3.X) it is not recommended to use this short view. Also an argument for this is, that the selectedEvents view use the abcourses object layer. See the selectedEvents section of this document for further informations.

Category overview and a listing of current events¶

This view-type is a special variant of the category listing and is able not only to list categories but also show an configurable number of courses, which the closest events are assigned to.

This is very useful for search engine optimization (for internal linking), because the page has (computed) different content which does not rotate with each page view or something like this but with each time one event is no longer the “closest” event within a category.

Abbildung 8: Sample screen shot for this view type.

Overview of selected events¶

This view is for displaying events without the selection of a special class and renders only special events. You can select this events manually or you can configure this view-type to display events which are marked as “last-minute”. For the last-minute layout you can set an amount of events you want to display as well.

The last-minute feature is implemented since version 1.3.X and displaces the both last-minute view-types. This is because it depends only on the assigned template file if you make this view type as an short or a detailed overview of last-minute events.

If there is more than one event selected (or computed) for one course, they get merged with this course during the rendering process.

Abbildung 9: Example layout for this view-type with additional course and trainer informations.

Detail search¶

I'm sorry, but this is not functional at the moment.

Overview of selected categories¶

This view is for displaying categories. But other than the normal categories overview, this view type only renders categories which you have manually selected in the BE FlexForm. Within the FlexForm use the Tab “Special View Settings” and than the selection “Categories to be shown within the special view Selected-Categories”.

There are some TS settings for this view to change the output. See more about this in the TS section of this documentation.

You should start with this¶

Make a back-up of your environment (to play safe)

Create some Sys-Folder records where your content for this extension is stored later. Depending on the number of records you want to deal with, it could be recommended to create a folder for each category (to store your events in)

I recommend a folder structure like this:

Seminars

• Categories and Course-Types
• Courses
• Events
• Hotels and Arrangements
• Trainers, Locations and Teachin-Aid's

Create some page records for your front-end PlugIns.Depending on the TS configuration and some implemented link features you need at least pages for:

• a categories overview
• The result view of search queries (as not in menu)
• the course details (as not in menu)
• the subscribe view (as not in menu)
• a “thank you” page where subscribers are redirected after a successful subscription

Add the corresponding PlugIn view types for the pages as mentioned above on each page

Overwrite the extensions default TS as described later in this documentation.

And: Do not forget to define a storage page within the backend. The storage page is used as pid for tracked subscriptions!

IMPORTANT! Have a look that the locale settings are correct. There are two fields for this within the plugins TypoScript: locale and offset. See more about this in the TS configuration table of this documentation and within the TS Default template as well.

That's it... Was easy, wasn't it? :-)

If you need help with your configuration: Since Version 1.3.3 there is a third Tab in the Plugins BE FlexForm called “config info”. Check the box on this tab and reload the page where you have problems... And configuration check will be rendered then! Sometimes this is very usefull and can save you a lot of time...

plugin.tx_abcourses_pi1¶

This is the basic PlugIn configuration.

TS for “Category overview”¶

plugin.tx_abcourses_pi1.catoverview

TS for “Courses in category”¶

plugin.tx_abcourses_pi1.coursesincat

TS for “Quicksearch”¶

Actually there is no configuration required for this view.

TS for “Resultlist”¶

plugin.tx_abcourses_pi1.resultlist

TS for view-type “Detail”¶

In because of this view-type is currently not completely based on the object-model, some of the TS properties are not nested as like for other view-type's.

Template structure and TS configuration for this view will change during the implementation of the object model for this view-type!

plugin.tx_abcourses_pi1.coursedetail

TS for view-type “Subscribe”¶

This view-type is responsible for rendering generally informations for the corresponding event on the one hand, and for generating the accommodation- and subscribe-form on the other hand.

TS for view-type “Category overview with next courses”¶

For this type of category overview you can display the next events and their courses too. This view type is really useful for SEO efforts because this list change every time an event is not the closest event for a category any more. So you can create a nice view with different internally links.

plugin.tx_abcourses_pi1.catoverviewwithnextevents

TS for view-type “Selected events”¶

This view can represent a list of manually selected events and their corresponding courses as well as an computed list of events / courses which are marked as “last minute”.

Which variant this view stands for is normally selected via the FlexForm configuration of the PlugIn in the BackEnd. But if you want to insert this with TypoScript you must do this settings via TS too.

plugin.tx_abcourses_pi1.selectedevents

Generally available markers¶

The template marker as listed below can be used in every template! They are primarily intended to be used as labels.

<div class="additionaly">
    ###LABELADDITIONAL###<br />
    <select name="Raucherzimmer">
        <option select="selected">###LABELADDITIONAL.I.0###</option>
        <option>###LABELADDITIONAL.I.1###</option>
        <option>###LABELADDITIONAL.I.2###</option>
   </select>
</div>

<div class="form-label">
    <label for="Anrede">###LABELTITLE###</label>
</div>
<select name="Anrede">
    <option select="selected">###LABELTITLE.I.0###</option>
    <option>###LABELTITLE.I.1###</option>
    <option>###LABELTITLE.I.2###</option>
</select>

All category fields¶

"

All course fields¶

"

All event fields¶

Example for the usage of the sub template “Locations”:
<!-- ###EVENT### begin -->                                                        <div class="event ###LASTMINUTE###">
                ###DATE### - ###PRICE######CUR### (###PRICETAX######CUR### ###TAXLABEL###)<br />
                ###SUBSCRIBELINK###
        </div>
        <!-- ###LOCATIONS### begin -->
                <!-- ###LOCATION### begin -->
                        ###LOCCITY###
                <!-- ###LOCATION### end -->
        <!-- ###LOCATIONS### end -->
<!-- ###EVENT### end -->

All trainer fields¶

All location fields¶

All page fields¶

All hotel fields¶

All arrangement fields¶

All teaching aid fields¶

For subtemplates of teaching aid records, there is only a fieldmarker ###NAME### without any special wrapping.

All conditions fields¶

In this case conditions are course records which contains recommended previous knowledge. You can integrate them only in the detail view of a course record at the moment. This is because the support for of them is currently not assumed in the object model.

All participantfields¶

These are the available fields for tracked participants. You can create create participant records manually as well. They will only automatically created if you have activated and configured this feature.

The manual location selector¶

Coming soon...

The subscription hook¶

Pre-subscription hook. The variable $hookAbort is passed into the expected method. If you implement this as an reference in your hook handler, you can abort the subscription an the user will get an error message...

if (is_array ($GLOBALS['TYPO3_CONF_VARS']['EXTCONF'][$this->extKey][$this->prefixId]['subscription'])) {
    foreach  ($GLOBALS['TYPO3_CONF_VARS']['EXTCONF'][$this->extKey][$this->prefixId]['subscription'] as $classRef) {
            $hookObj= &t3lib_div::getUserObj($classRef);
                  if (method_exists($hookObj, 'startSubscription')) {
                  $hookObj->startSubscription($MA, $MACourse, $MAEvent, $MATrainer, $MALocation, $hookAbort, $this);
          }
    }
}

The parameters prefixed with $MA are associative marker arrays for template substitutions. $this is the PHP common reference to the current object. In this case, the pi1 class instance.

The displayDetail Hook¶

This hook is called just before the output of the displayDetail Method renders the detailed View of an course. That is the hook:

if (is_array ($GLOBALS['TYPO3_CONF_VARS']['EXTCONF'][$this->extKey][$this->prefixId]['displayDetail'])){
    foreach  ($GLOBALS['TYPO3_CONF_VARS']['EXTCONF'][$this->extKey][$this->prefixId]['displayDetail'] as $classRef){
            $hookObj= &t3lib_div::getUserObj($classRef);
                  if (method_exists($hookObj, 'customDisplayDetail')) {
                  $hookObj->customDisplayDetail($sRet,$MACourse);
          }
      }
}

Your method customDisplayDetail MUST receive the parameter as Reference to take an effect!!!

The fillAllLabels Hook¶

This hook is called just before the method fillAllLabels returns. The method fills an array with general markers and is used for substitution before the output of each view type! So you can use this hook to add different labels.

Thats the hook:

if (is_array ($GLOBALS['TYPO3_CONF_VARS']['EXTCONF'][$this->extKey][$this->prefixId]['fillAllLabels'])) {
    foreach  ($GLOBALS['TYPO3_CONF_VARS']['EXTCONF'][$this->extKey][$this->prefixId]['fillAllLabels'] as $classRef){
            $hookObj= &t3lib_div::getUserObj($classRef);
                  if (method_exists($hookObj, 'customFillAllLabels')) {
                    $hookObj->customFillAllLabels($MA);
            }
    }
}

How to change the subscription form¶

Due to the fact that a submitted subscription form is not stored in any way by this extension currently, you can add as many fields as you want. If you want the submitted data to be stored anywhere, you can use the subscription hook for this. Of course, that means you have to do some coding.

However, add some fields to the subscription form does not require any coding skills.

Here an example. Expecting you have a form-template with input fields for firstname, surname and email, the template would look like this:

<!--  ###SUBSCRIBEFORMTMPL### begin -->
    <h2>###LABELSUBSCRIBEHEADER###</h2>
    ###LABELWARNING###
    ###WARNING###
    <form action="###PATHSUBSCRIBE###" method="POST">

The next 3 lines are the input fields!

        ###LABELNAME### <input type="text" name="vorname" value="###VORNAME###"/><br />
        ###LABELLASTNAME### <input type="text" name="nachname" value="###NACHNAME###"/><br />
        ###LABELEMAIL### <input type="text" name="email" value="###EMAIL###"/>   <br />


        <input type="hidden" name="subscribe" value="1" />
        <input type="hidden" name="eventid" value="###EVENTID###" />
        <br />
        <input type="submit" value="###LABELSUBMITSUBSCRIBE###" />
    </form>
    <!--  ###NOSUBSCRIBEFORMTMPL### begin -->
            ###LABELERRORCONTACTUS###<br>
            ###LINKCATOVERVIEW###<br>
            ###LINKDETAILSEARCH###
    <!--  ###NOSUBSCRIBEFORMTMPL### end -->
<!--  ###SUBSCRIBEFORMTMPL### end -->

And now, we want to add an required input field where the subscriber should enter the name of the company he is working for. We call the input field “company”.

For a new Input field we can:

• create a new localized template marker for the label of the field as shown on the rendered subscribing form
• create a new localization for the rendered mails
• define the new field as “required” input
• suppress or show the field in the generated mail

Especially the last point is usefull if you integrate some hidden form fields which may be required within your subscription hook.

At first, you add one line in the template of you form:

<input type="text" name="company"/><br />

But now you have only an input field. You want to have a localized label as well. So you add a marker for the label:

###ADDONLBL-COMPANY### <input type="text" name="company"/><br />

Now, add “addonlbl-company” to the comma separated list of the plugins TS configuration. This is explained above in the section “TS Configuration”. And of course, add one line to the pi1's locallang.xml file. Use the key “addonlbl-company” for the index attribute of the new line in the XML file. Do not forget: f you update abcourses later, make a backup of you locallang.xml to play save!

We want the new form field to be stikky. That means, that the input of the field is not deleted if the subscriber returns to the subscribing form in case of a failed form validation. So, add the “value” attribute to the new form field and insert a marker. The marker must be the uppercase “name” attribute of the form field, but with 3 # prefixed and post-positioned.

###ADDONLBL-COMPANY### <input type="text" name="company" value=”###COMPANY###”/><br />

The first step is done now. You have a new line in your form, made it stikky, added a label and localized it. Great ;-)

But what is about the “required” setting as mentioned above? And where to find the visibility settings? Go back to the TS Configuration and you will find some description for the template marker: usedLabels, required, mailLabels.

For our example setup it should look like this:

# ALL fields of the form must be listed here!!!
usedLabels =  vorname, nachname, email, subscribe, eventid, company

# Here you list all fields that you wants to be reuired!!!
required      =  email, company

# And last but not least: list all labels that you wants to appear within the sent mails.
mailLabels  = vorname, nachname, email, company

One more hint! The name of the field “email” is automatically validated as an email address and will be used as the sendTo recipient for the customers confirmation email.

Thats it! I hope this quick overview was usefull for you.

What you should know about the email template¶

Within the email template you will find a marker ###FORMDATA###.

This marker will be replaced by the _POST variables of the subscription form. For each key>value pair their will be one new line rendered.

Please note that you have to define the values, which you want to be included in this listing, within the TS setup variable “mailLabels”.

By example: The _POST variable “company” will be rendered like this:

Company : XYZ AG

But where comes the “Company” from? Abcourses tries to look up every POST key in the locallang.xml. If you added there a line with “company” as index, you can localize the form field labels for the mail template.

If abcourses do not found a localization, it uses the key of the field as label with an upper cased first letter.

Please consider that you should not choose key names which already exists in the locallang.xml!