.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt .. role:: underline =============== EXT: cgswigmore =============== :Author: Christoph Gostner :Created: 2009-05-25T12:47:00 :Changed: 2009-06-02T15:32:07 :Email: christoph.gostner@gmail.com :Info 2: :Info 3: :Info 4: .. _EXT-cgswigmore: EXT: cgswigmore =============== Extension Key: **cgswigmore** Copyright 2007-2009, , 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: Table of Contents ----------------- **EXT: cgswigmore 1** **Table of Contents 1** **Introduction 1** What is it about 1 Screenshots 3 **Live demo 4** **User manual 5** **Administration 6** Installation 6 Setting up the extension - a step by step tutorial 6 Styling cgswigmore 12 **Configuration 12** Using your own html templates 12 Display code 13 UserFunc 13 Common properties 13 SECTION 14 STAFF 15 PUBLICATION 16 JOB 17 LOCATION 17 **Known problems 18** **Changelog 18** .. _Introduction: Introduction ------------ .. _What-is-it-about: What is it about ^^^^^^^^^^^^^^^^ Swigmore institute (cgswigmore) is a TYPO3 extensionwhich was developed to displayinformation about work groups (departments/defined as “sections”), publications, staff members and job offers on your homepage. Foreachsectionit provides a list- andasingle view.Thesingle view includes the section's member list, a list ofthepublications and a detailed description. The extension uses html templates to change the style of the output. The extension itself is multi-lingual, atthemoment English and German are available. Swigmore institute uses true MN-relation tables for the staff members, the publications etc.. Using cgswigmoreneeds some configuration, but it is easily to set up. The best way is to create one main templatecontainingall global information for yourpage. In page-dependent sub-templates you can customize the configuration. .. _Screenshots: Screenshots ^^^^^^^^^^^ T |img-1| he extension's data should be managed in different SysFolders. |img-2| Here you can see the input form for a new section: |img-3| A section contains the section's name, title, image, description and extra fields for the main and secondary leader. The section's front-endlist viewcould look like this: |img-4| .. _Live-demo: Live demo --------- Cgswigmore institute was originally developed for the Tyrolean Cancer Research Institute: - :underline:``http://www.tcri.at `_` (English version) - :underline:``http://www.tkfi.at `_` (German version) If you know other pages using this extension please let me know::underline:``christoph.gostner@gmail.com `_` .. _User-manual: User manual ----------- *This part of the manual should be useful for editors who want to add sections, publications etc. For information about setting up the extension and the needed frond-end pages please refer to the “Administration” chapter.* To add, edit and delete sections, publications, etc.it is recommend towork in the **List** module; S |img-5| elect the section's **SysFolder** and you will see the list of work groups/departments you created. |img-6| To add a new work group/department, simply click |img-7| .If you wish to edit the section, click the pen-button. If your **SysFolder** is empty you can use the ***add*** button to select one of the following elements: |img-8| .. _Administration: Administration -------------- *This chapter* *explains* *how to set up the extension. Warning: some basic knowledge of creating extension-templates and inserting plugins on a page is expected.* .. _Installation: Installation ^^^^^^^^^^^^ Go to the extension's manager, choose **Import extensions** and search for“ *cgswigmore* ”. Install the extension and create any required tables. .. _Setting-up-the-extension-a-step-by-step-tutorial: Setting up the extension -a step by step tutorial ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Step 1** Let us start setting up the base structure of the homepage ( *cgswigmore test site* ). Until n |img-9| ow the test homepage contains one **SysFolder** whichcontains the typo3 configuration ( *config* ) and the typo3 template settings ( *site* ).Additionally the **SysFolder** contains a folder called *data* , where youcanset up the extension's templates in different sub-folders. Setting up a section:The homepage's structure contains a page for *Sections* (UID=5) and a sub-page for *Details* (UID=8).If you don't want to use a sub-page for *Details, you can* combine the *Details* and *Section* page, however you must set the UID correctly. **Step 2 – Configuration of cgswigmore in the folder data** We create a new template in the folder *data* , which will contain all global configuration for cgswigmore.Define the template as following: :: plugin.tx_cgswigmore_pi1 { section { templateFile = EXT:cgswigmore/res/section.html sectionUID = 8 sort = sorting ASC } } This is a minimal configuration for the element. We define thesectionUIDproperty to the *Detail* page with UID 8. **Attention** with the definitions:“ *Sections* ” means the page which will display the data.“ *sections”* is a SysFolder which will contain the data.“section” (used in the template above) is a part of cgswigmore's configuration. **Step 3** Now add the template you created in Step 2 to your page (eg. *Homepage* ). **Step 4** Configure the *Section* 's page (UID 5) and edit the page properties. You can set the **'** **General Record Storage page'** to the *sections* folder, this will tell cgswigmore wheretofind the dataprovided for being displayed. Finally you have to create a template in the *Sections* page with the following content: :: plugin.tx_cgswigmore_pi1 { display = SECTION } page.10.subparts.CONTENT < plugin.tx_cgswigmore_pi1 At the *Section's* page (front-end) now you can see the section list (if you created any, refer to the first part of the user manual). Thereexistmore options for the “section” element (step 2),but thosewill be explained later. **Step 5** Settingup a staff item (member):First create a new **SysFolder** (e.g. *data/staff* - UID=9) and a page (e.g. *homepage/Staffpage* - UID=10) to view the staff's information. Secondly edit the template in the **SysFolder** *staff* .Add the following configuration: :: plugin.tx_cgswigmore_pi1 { staff { templateFile = EXT:cgswigmore/res/staff.html sort = name ASC staffUID = 10 link.sprintf = %s %s } } .. _Now-you-can-create-new-staff-member-itemsin-the-SysFolder-staff: Now you can create new staff member itemsin the **SysFolder** *staff* . |img-10| Do you see a problem? You cannot select any section item for the staff member youcreated. To enable this option, go to the page properties and set the **'** **General Record Storage page'** to the *data/sections* **SysFolder.** **Step 6** Now go to the page (e.g. *Homepage/Staffpage* - UID=10) you created for the staff member items. There you create a template with the following content: :: plugin.tx_cgswigmore_pi1 { display = STAFF } page.10.subparts.CONTENT < plugin.tx_cgswigmore_pi1 Then set the **'** **General Record Storage page'** to the **SysFolder** *staff* . If you go to the staff's site on the front-end (e.g. *Homepage/Staffpage* - UID=10) youmostprobably see another problem. The link/text for the *sections* are not generated. To solve this problem you have to overwrite the **SysFolders** UID in the global configuration template *(/data)* by setting the section. *recordIds* property. So the final template for the page (UID=10) looks like this: :: plugin.tx_cgswigmore_pi1 { display = STAFF section.recordIds = 7 } page.10.subparts.CONTENT < plugin.tx_cgswigmore_pi1 The sameconflicthas the section's staff view ( *Homepage/Sections/Detail* ). Also there the staff members can't be displayed because of the **'** **General Record Storage page'** . Edit the *Sections* template, at the end it should look like this: :: plugin.tx_cgswigmore_pi1 { display = SECTION staff.recordIds = 9 } page.10.subparts.CONTENT < plugin.tx_cgswigmore_pi1 **Step 7** Setting up of publications: First create a new **SysFolder** ( *data/publication –* UID=11) and a new page (e.g. *Homepage/Pubpage* - UID=12), thenedit the template in the **SysFolder** *data* . Add the following configuration for the publications: :: plugin.tx_cgswigmore_pi1 { publication { templateFile = EXT:cgswigmore/res/publication.html link = 0 sort = date DESC } } Before you add a new publication you should set the **'** **General Record Storage page'** of the data/ *publication* **SysFolder** to the data/ *sections* folder. **Step 8** Go to the publication page ( *Homepage/Pubpage* ), set the **'** **General Record Storage page'** for the publication's **SysFolder** (UID=11) and create a new template with the following content: :: plugin.tx_cgswigmore_pi1 { display = PUBLICATION } page.10.subparts.CONTENT < plugin.tx_cgswigmore_pi1 Edit the templates for the staff member item page ( *Homepage/Staffpage* ) and the *Sections* page ( *Homepage/Sections* ) to find the publications. Simply add the following lines to the templates: :: publication { recordIds = 11 } **Step 9** Creatingjob categories Simply adda single **SysFolder** ( *data/jobcategory* - UID=13) and create some job categories. **Step 10** Within the job categoriesyoucan create job offers. Create a **SysFolder** ( *data/job* - UID=14) and a page ( *Homepage/Job* - UID=15). The job page's **'General Record Storage page'** should point to the job categires **SysFolder.** Edit the template in the **SysFolder** data and add the following lines: :: job { templateFile = EXT:cgswigmore/res/job.html category { sort = sorting ASC } job { sort = crdate DESC } } **Step 11** The next step is to create a template in the page *Job* (UID=15) with the content: :: plugin.tx_cgswigmore_pi1 { display = JOB staff { recordIds = 9 } } page.10.subparts.CONTENT < plugin.tx_cgswigmore_pi1 Note thatwe haveset the *recordIds* property for the staff member items. The extension again needs this setting to find the staff member items in the correct **SysFolder.** **Step 12** Finally I woud like to explain the set up for a location page.Howeverthere are muchnicerextensionsavailabledoingthe same job. Create a **SysFolder** *(data/location* - UID=16) and a page *(Homepage/Location* - UID=17). Now configure the template in the **SysFolder** *data* and add the following lines: :: plugin.tx_cgswigmore_pi1 { location { templateFile = EXT:cgswigmore/res/location.html } } **Step 13** Go to the *Location* page (UID=17) and set the **'General Record Storage page'** to the location's **SysFolder** (UID=16). Create a new template which contains: :: plugin.tx_cgswigmore_pi1 { display = LOCATION location { uid = 1 # the uid of the location to display } } page.10.subparts.CONTENT < plugin.tx_cgswigmore_pi1 The template in the **SysFolder** *data* should now look like this: :: plugin.tx_cgswigmore_pi1 { section { templateFile = EXT:cgswigmore/res/section.html sectionUID = 8 sort = sorting ASC } staff { templateFile = EXT:cgswigmore/res/staff.html sort = name ASC staffUID = 10 link.sprintf = %s %s } publication { templateFile = EXT:cgswigmore/res/publication.html link = 0 sort = date DESC } job { templateFile = EXT:cgswigmore/res/job.html category { sort = sorting ASC } job { sort = crdate DESC } } location { templateFile = EXT:cgswigmore/res/location.html } } Thistutorialcontains only some options which are supported by cgswigmore. See the configuration chapter for more details. .. _Styling-cgswigmore: Styling cgswigmore ^^^^^^^^^^^^^^^^^^ Cgswigmoreprovidesa CSS style which you can include or/and modify.Of course some basic CSS knowledge is required. To include the CSS file add the following line to your templage ( **SysFolder** */data).* :: page.includeCSS.file00101010 = EXT:cgswigmore/res/css/cgswigmore.css .. _Configuration: Configuration ------------- .. _Using-your-own-html-templates: Using your own html templates ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Itispretty easy to use your own HTML template. Each section has its own template. The default templates are located at *typo3conf/ext/cgswigmore/res* and contain all the supported markers by cgswigmore. .. _Display-code: Display code ^^^^^^^^^^^^ With the display code you can decide which information willbe shownon the homepage. The supported codes are: .. ### BEGIN~OF~TABLE ### .. _display: display """"""" .. container:: table-row Property display Data type string Description The display code: SECTION STAFF PUBLICATION JOB LOCATION Default .. ###### END~OF~TABLE ###### .. _UserFunc: UserFunc ^^^^^^^^ Cgswigmore provides three predefined user functions which can be used in the extension's configuration.Howeverit is important that typo3 knows this user functions before. Insert the following lines in your configuration template: :: page.includeLibs.userFuncs1 = EXT:cgswigmore/userFunc/class.user_cgswigmore_userfunc_pubmed.php page.includeLibs.userFuncs2 = EXT:cgswigmore/userFunc/class.user_cgswigmore_userfunc_file.php page.includeLibs.userFuncs3 = EXT:cgswigmore/userFunc/class.user_cgswigmore_userfunc_file_icon.php .. _Common-properties: Common properties ^^^^^^^^^^^^^^^^^ Here are some properties which are common for all the elements listed below. The *templateFile* property isnotoptional and must be set for each configured item. The other options explained here are optional, but as you have seen in the step by step tutorial, sometimes they are required. .. ### BEGIN~OF~TABLE ### .. _templateFile: templateFile """""""""""" .. container:: table-row Property templateFile Data type string Description This is a template to display the content. Some templates already exist in the extension's folder called res and can be included: :: templateFile = EXT:cgswigmore/res/section.html templateFile = EXT:cgswigmore/res/staff.html templateFile = EXT:cgswigmore/res/publication.html templateFile = EXT:cgswigmore/res/job.html templateFile = EXT:cgswigmore/res/location.html Default .. _recordIds: recordIds """"""""" .. container:: table-row Property recordIds Data type int,int,... Description With this option you can specify pages/SysFolders witch contain the data to display. Default .. _recursive: recursive """"""""" .. container:: table-row Property recursive Data type bool Description If this option is set to 1 also the data in the sub-folders are included in the data result. Default 0 .. ###### END~OF~TABLE ###### .. _SECTION: SECTION ^^^^^^^ The configuration of the section element will be done inplugin.tx\_cgswigmore\_pi1.sectionas we already used in thetutorial. Additionally to the previously presented basic properties you can use the following options: .. ### BEGIN~OF~TABLE ### .. _sectionUID: sectionUID """""""""" .. container:: table-row Property sectionUID Data type int Description This is the UID of the page where you want to display the section's details. Itisaessentialsetting, if you want to create a link from the staff list to the section(s) of the members. Default .. _sort: sort """" .. container:: table-row Property sort Data type string Description This option defines how the result should be ordered before it is displayed. This could look like this: :: sort = DESC The *field* tag could be one or many of theseoptions: - uid - pid - section - title - photo - description - photo - leader1 - leader2 Default .. _doList: doList """""" .. container:: table-row Property doList Data type int, int, ... Description With this setting you can decide that only specific sections are displayed. Default .. _doNotList: doNotList """"""""" .. container:: table-row Property doNotList Data type int, int, ... Description This is an array of sections which should not be displayed. Default .. _image: image """"" .. container:: table-row Property image Data type ->imgResource ->stdWrap Description This property defines how the section's image should be displayed. An example configuration could look like this: :: image { height = 70 format = png quality = 100 } Default .. _icon-userFunc: icon.userFunc """"""""""""" .. container:: table-row Property icon.userFunc Data type string Description A section cancontainfiles. The section's detailed view displays them as a list with a short description. If you donotset this option,only the files' description will be displayed. The user function for icons is: :: user_cgswigmore_userfunc_file_icon->linkFileIcon Default .. _file-sort: file.sort """"""""" .. container:: table-row Property file.sort Data type string Description Here you can specify how the files should be sorted. Thisworkslike the sort property, but cancontainonly the following *field* tags: - sorting - file - description Default .. ###### END~OF~TABLE ###### .. _STAFF: STAFF ^^^^^ Configuration of the staff element will be done inplugin.tx\_cgswigmore\_pi1.staffas we already used it in the tutorial. Additionally to the previously presented basic properties you canusethe following options: .. ### BEGIN~OF~TABLE ### .. _staffUID: staffUID """""""" .. container:: table-row Property staffUID Data type int Description This is the page's UID where your hompage will display the staff's details. Also this setting is aessentialproperty, because it is neededtodisplay the section's staff member items. Default .. _sort: sort """" .. container:: table-row Property sort Data type string Description This option defines how the result should be ordered before it is displayed. This could look like this: :: sort = DESC The *field* tagcan beone or many of these options: - uid - pid - title - firstname - name - description - phone - mobile - image Default .. _link-sprintf: link.sprintf """""""""""" .. container:: table-row Property link.sprintf Data type string Description This property defines the font style of the member'sfore- and surname. For example :: link.sprintf = %s %s defines that the first name is bold, the second not. For more details about how to use this setting please look at the PHP function's documentation of *sprintf* , Default .. _switch-linkClass: switch.linkClass """""""""""""""" .. container:: table-row Property switch.linkClass Data type string Description The staff's list view shows a button/text witch can be used to switch between the active and the former members. This link is created by an internal function, so you do not have access to the tag. So the *switch.linkClass* property allows you to set this CSS class. Default .. _section-doNotLink: section.doNotLink """"""""""""""""" .. container:: table-row Property section.doNotLink Data type int, int, ... Description In the staff's list view you can also display the section names for each member.Wth this setting you can disable the link for certain sections. It can be used if a certain section has no own page. :: section.doNotLink = 1 Default .. _image: image """"" .. container:: table-row Property image Data type ->imgResource ->stdWrap Description This property defines how the staff's image should be formatted. An example configuration could look like this: :: image { width = 80 format = png quality = 100 } Default .. ###### END~OF~TABLE ###### .. _PUBLICATION: PUBLICATION ^^^^^^^^^^^ Configuration of the publication element will be done inplugin.tx\_cgswigmore\_pi1.publicationas we already used it inthe tutorial. Additionally to the previously presented basic properties you can use the following options: .. ### BEGIN~OF~TABLE ### .. _view: view """" .. container:: table-row Property view Data type String Description The publication element supports two view types. The standard one is the **All In One** list, a simple list of all publication items in one page. The second setting is called **List Per Year** (LPY) and presents a select box where the user can select publications published in a specific year. - AIO - LPY Default AIO .. _link: link """" .. container:: table-row Property link Data type bool Description This setting decides if the title of the publication should be linked or not (see link.userFunc). If you set the value to 1 (true), you also have to set the *link.userFunc* property, if not you will get errors. Default 0 .. _link-userFunc: link.userFunc """"""""""""" .. container:: table-row Property link.userFunc Data type string Description This setting defines which user function should be used to link the title of the publications. Cgswigmore provides two classes for this property: :: user_cgswigmore_userfunc_file->linkFile This user function creates a link to the file specified in the publication record if the publication record contains any file. :: user_cgswigmore_userfunc_pubmed->linkPubMed This user function creates a URL to the pubmed homepage for publications which contain a PMID. Default .. _link-field: link.field """""""""" .. container:: table-row Property link.field Data type string Description This setting defines the publication property field (e.g. author, title, …) that will be displayed as link text. See the *sort* property for the values you can set here. Default .. _icon: icon """" .. container:: table-row Property icon Data type bool Description By setting this property to 1 cgswigmore will display an icon file if the publication contains a file reference. Default 0 .. _icon-userFunc: icon.userFunc """"""""""""" .. container:: table-row Property icon.userFunc Data type string Description This property is usefull only if you set the *icon* propertyto 1. Then it creates a link to the file specified in the publication record, e.g. :: user_cgswigmore_userfunc_file_icon->linkFileIcon Default .. _sort: sort """" .. container:: table-row Property sort Data type string Description The sort property defines the order of the result before it is displayed. This could look like this: :: sort = DESC The *field* tag could be one or many of these options: - uid - pid - author - title - journal - date - volume - pages - note - pmid - staff - section - number - file Default .. ###### END~OF~TABLE ###### .. _JOB: JOB ^^^ Configuration of the job element will be done inplugin.tx\_cgswigmore\_pi1.jobas we already used it in the tutorial. Additionally to the previously presented basic properties you can use the following options: .. ### BEGIN~OF~TABLE ### .. _view: view """" .. container:: table-row Property view Data type string Description The job element provides two view types. The first is called **All In One** and simply lists all job categories and jobs in one page. :: view = AIO The second one is called **Category and Job Single view** and displays first a list with all category names and their job titles and displays the job's details by clicking on the job link. :: view = CJS Default AIO .. _category-sort: category.sort """"""""""""" .. container:: table-row Property category.sort Data type string Description This property defines the order how the categories should be sorted before they are displayed. This could look like this: :: sort = DESC The *field* tag could be one or many of these options: - uid - sorting - name Default .. _job-sort: job.sort """""""" .. container:: table-row Property job.sort Data type string Description This property defines the order how the jobs should be sorted before they are displayed. This could look like this: :: sort = DESC The *field* tag could be one or many of these options: - uid - pid - text - title - file Default .. _icon-userFunc: icon.userFunc """"""""""""" .. container:: table-row Property icon.userFunc Data type string Description This user function creates a link to the document file defined optionally in a job offer. The file icon is only visible if such a document file exists. :: icon.userFunc = user_cgswigmore_userfunc_file_icon->linkFileIcon Default .. ###### END~OF~TABLE ###### .. _LOCATION: LOCATION ^^^^^^^^ Configuration of the location element will be done inplugin.tx\_cgswigmore\_pi1.locationas we already used it in the tutorial before. Additionally to the previously presented basic properties you can use the following options: .. ### BEGIN~OF~TABLE ### .. _uid: uid """ .. container:: table-row Property uid Data type int Description This property specifies the UID of the location record to be displayed. Default .. _image: image """"" .. container:: table-row Property image Data type ->imgResource ->stdWrap Description This property defines the format of the location's image in the output. An example configuration could look like this: :: image { width = 80 format = png quality = 100 } Default .. ###### END~OF~TABLE ###### .. _Known-problems: Known problems -------------- -None- If you find bugs in the extension please send a mail to:underline:``christoph.gostner@gmail.com `_` . .. _Changelog: Changelog --------- ... Version 1.0.0 \*:underline:``2606 `_` Bug fixed \* New documentation with a brief tutorial \* SysFolders are now correctly searched if the recursive option is set to 1 \* templates/CSS are redesigned and described in more detail \* some less important changes ... Version 1.0.1 \* new user function for publication and job icons available \* now only links are generated for the publication and icon if there is data to create a link (:underline:``2666) `_` \* feature complete - first stable release EXT: cgswigmore |img-11| - 2 .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. :border: 0 .. :height: 115 .. :id: graphics1 .. :name: graphics1 .. :width: 190 .. |img-2| image:: img-2.png .. :align: left .. :border: 0 .. :height: 88 .. :id: graphics2 .. :name: graphics2 .. :width: 557 .. |img-3| image:: img-3.png .. :align: left .. :border: 0 .. :height: 399 .. :id: graphics3 .. :name: graphics3 .. :width: 254 .. |img-4| image:: img-4.png .. :align: left .. :border: 0 .. :height: 125 .. :id: graphics4 .. :name: graphics4 .. :width: 589 .. |img-5| image:: img-5.png .. :align: left .. :border: 0 .. :height: 179 .. :id: graphics5 .. :name: graphics5 .. :width: 158 .. |img-6| image:: img-6.png .. :align: left .. :border: 0 .. :height: 403 .. :id: graphics6 .. :name: graphics6 .. :width: 669 .. |img-7| image:: img-7.png .. :align: left .. :border: 0 .. :height: 21 .. :id: graphics7 .. :name: graphics7 .. :width: 21 .. |img-8| image:: img-8.png .. :align: left .. :border: 0 .. :height: 112 .. :id: graphics8 .. :name: graphics8 .. :width: 116 .. |img-9| image:: img-9.png .. :align: left .. :border: 0 .. :height: 208 .. :id: graphics9 .. :name: graphics9 .. :width: 185 .. |img-10| image:: img-10.png .. :align: left .. :border: 0 .. :height: 247 .. :id: graphics10 .. :name: graphics10 .. :width: 267 .. |img-11| image:: img-11.png .. :align: left .. :border: 0 .. :height: 32 .. :id: graphics11 .. :name: graphics11 .. :width: 102