The following is for site developers/administrators who want to setup this extension on their system.
A number of constants are setup so you can customize the extension to fit your needs.
To change the constants, you can either use the Constants Editor or change them in TypoScript. Both ways are shown below. First though you will need to create a new template. If you already have a template, then proceed to the Edit Constants or Change Constants in TypoScript below.
First, before you edit constants, you will need to create a new template. Creating a template is easy.
Click on the page with the WEC Servant Matcher in the page tree.
Go to the Template action in the main menu. Click on “Info/Modify” in the upper right drop-down menu.
Choose “Click here to create an extension template” under “Create Extension Template”.
You can “edit the whole template record” and setup the name or change constants. See below.
Here are the steps to do that:
Select the page where your WEC Servant Matcher is installed
Select the Template icon
Choose Constant Editor in the drop down in the upper right.
Choose PLUGIN.wecservant_pi1 from the Category.
Choose one or more of the constants by clicking on the checkbox. Doing this indicates that you want to change that constant. When you are done selecting items, click the Update button.
Change the values to what you want. Click on Update button again to save them.
You can now preview your page and see the changes.
Below is a screenshot of what you will see in the Constants Editor:
You need to have a template defined in the installation of your Extension, or you can edit the root template for your site. If you have not created a template, see the above how to create a new template.
1) Select the page where your Servant Matcher is installed.
2) Select the Template icon.
3) Choose Info/Modify in the drop down in the upper right.
4) Choose “Click here to edit the whole template record”.
5) Now you can add to the Constants or Setup field.
An example to add would be:
page.templateFile = fileadmin/wec_servant/my_wecservant.tmpl
6) You can then preview your page and see the changes.
The following are the constants available to change in the Servant Matcher extension:
PROPERTY | DATA TYPE | DESCRIPTION | DEFAULT |
templateFile | string | The template file. | EXT:wec_servant/pi1/wecservant.tmpl |
totalWidth | string | The width of the display area for the wec_servant extension | 650px |
displayItemWidth | string | The width of the display item. A display item is a ministry opportunity that is shown. | 100% |
displayItemLabelWidth | string | The width of the label (left side) for the item. | 25% |
displayItemTextWidth | string | The width of the text (right side) for the item. Why this does not add up to 100% is to take into account the margin/padding on the CSS divs. | 73% |
displayItemBackColor | string | The background color for the the display item. | #FFFFFF |
displayItemBackColor | string | The background color#2 fo the the display item. This is used if you want to alternate background colors. Leave blank if you just want one color. | #E0E0E0 |
formWidth | string | The width of the signup form. | 90% |
formLabelWidth | string | The width of the label (left side) in the signup form. | 20% |
formInputWidth | string | The width of the input field (right side) in the signup form. | 78% |
formTextAreaHeight | string | The width of a text area. | 80px |
formBackColor | string | The background color of the signup form. | #E8E0F0 |
btnBackColor | string | The background color for a button. | #888888 |
btnColor | string | The foreground(text) color for a button. | #FFFFFF |
btnHoverBackColor | string | The hover background color for a button. | #AC0000 |
btnHoverColor | string | The hover text color for a button. | #FFFFFF |
skillColWidth | string | The width for each column for skill listing. If you want two columns, make it 50% (or half of your total width). If you want four columns, make it 25%, or one column, make it 100%. You can also use fixed widths here. These are only needed if you use skills. [optional] | 33.00% |
emailAtSubstitute | string | The character(s) to replace the @ symbol in the display of any email addresses. This is used for spam protection when email addresses are displayed. The default @ is the @ character. You can also use “(at)” or “.at.” or whatever you would like. This is only for the display – the actual mailto is encoded with Typo3. | @ |
maxMatchesToShow | string | The maximum number of matches to show. This is only useful if you have a large number of entries and want to limit the amount. This was added so that the server does not slowdown too much in doing matches. | 250 |
staffDirectoryPage | integer | You can link to the WEC Staff Directory single page of a staff member by setting the page id to the WEC Staff Directory. You can get this page id from the Backend of your site. You may want to link to a single view of the staff directory page if you have setup. Note: If this constant is set, then the extension loads in WEC Staff Directory tables to match the fe_user id with the staff directory id. The link is through tx_wecstaffdirectory_pi1[curstaff]=#. | |
viewMinistryOpps | string | If you would like the Servant Matcher to show Ministry Opportunities right away, and not be concerned with matching, then you can set this constant to the given ministry/usergroup and it will show all matching. If you set it to 'all' or -1 then it will show all ministry opportunities. | |
The template file is where the template is stored to determine how the Servant Matcher will be displayed. It contains HTML code along with Template Markers that show where the data is inserted. In the template file, you will find several template sections – one for the main page, one for an item view, one for the signup form, and another for the admin menu.
The following details the template sections and template markers. You can modify these to suit your needs. To create your own, just copy the whole template section, rename it to whatever you would like (i.e., ###TEMPLATE_NEWTYPE###) and then alter the content and setup as you would like.
TEMPLATE MARKERS | DESCRIPTION |
###TEMPLATE_PAGE### -- the main page | |
###JAVASCRIPT_CODE### | An internal field that must be present for the toggle skills to work. |
###TITLE### | The title of the page that is from the Flexform Title. |
###ADMIN_LINK### | Where to put an admin button...which only those defined in Administrator will see. |
###VIEW_SAVED_MINOPPS_LINK### | The button / link that will allow you to view saved ministry opportunities. |
###PRINT_SAVED_MINOPPS_LINK### | The button / link that will allow you to print saved ministry opportunities. |
###RESPONSE_MSG_TEXT### | Any message that is shown for errors or responses on actions that the user made. |
###FIND_BY_MINISTRY_HEADER######FIND_BY_MINISTRIES_HEADER######FIND_BY_NEEDS_HEADER######FIND_BY_LASTADDED_HEADER### ###FIND_BY_SKILLS_HEADER### | These are the headers (text info) for showing the Find By.... The actual text is defined in locallang.php. |
###FIND_BY_MINISTRY######FIND_BY_MINISTRIES### ###FIND_BY_NEEDS### ###FIND_BY_LASTADDED### ###FIND_BY_SKILLS### | These are the actual selection interface for each. For skills and find_by_ministries, this is checkbox list of options. For all others, it is a drop-down menu list. |
###TOGGLE_FIND_SKILLS######TOGGLE_FIND_SKILLS_OFF### | If you do use the skills and you have a lot, you may want to hide the skills unless they click on a button. If you wrap these template markers around the FIND_BY_SKILLS, this will allow that. |
###TOGGLE_FIND_MINISTRIES######TOGGLE_FIND_MINISTRIES_OFF### | You may want to hide the full ministries list until they click on the “Show...” button. If you wrap these template markers around the FIND_BY_MINISTRIES, this will alow that. |
###DISPLAY_RESULTS_HEADER### | This is the header for the display results. |
###DISPLAY_RESULTS### | This is the actual listing of “display items”. |
###SIGNUP_BTN### | The signup button. |
###COMMITMENT_BTN### | The commitment button. |
###LAST_10_ADDED_BTN### | A button that when clicked on will show the last 10 updates of ministry opportunities. You may want to use this instead of FIND_BY_LASTADDED for simplicity. |
###FIND_URGENT_NEEDS_BTN### | A button that when clicked on will show the Urgent Needs. You may want to use this instead of the drop-down if you just mark your priorities as Urgent/Normal. Also, you can change the name “Urgent” in the locallang file so this can be “High Priority” or whatever you would want to call it, but will show the highest priority needs. |
###VIEW_SINGLE### | Allows to view an item separately in its own view. Will put a 'View This' (can change text in locallang -- view_single) link. |
###TEMPLATE_DISPLAYITEM### -- showing one item (ministry opportunity) | |
###ITEM_EVENODD_DISPLAY### | The style that must be attached to the displayItem div if you want to support alternating display colors for each item in the list. If alternating colors are not used, this can still be used for setting the background color. |
###MINISTRY_INFO######NAME######DESCRIPTION######PRIORITY######LOCATION######TIMES_NEEDED######MISC_DESCRIPTION######QUALIFICATIONS######SKILLS######CONTACT_INFO######CONTACT_PHONE######CONTACT_EMAIL### | The actual data for the item. This will only display if the field is actually displayed. |
###SHOW_MINISTRY_INFO######SHOW_NAME######SHOW_DESCRIPTION######SHOW_PRIORITY######SHOW_LOCATION######SHOW_TIMES_NEEDED######SHOW_MISC_DESCRIPTION######SHOW_QUALIFICATIONS######SHOW_SKILLS######SHOW_CONTACT_INFO######SHOW_CONTACT_PHONE######SHOW_CONTACT_EMAIL### | Whether to show the field. If the field is turned off / hidden, then the whole field (label + data) will not be shown. The field is hidden through a display:none in the CSS. |
###ITEMLABEL_MINISTRY_INFO######ITEMLABEL_NAME######ITEMLABEL_DESCRIPTION######ITEMLABEL_PRIORITY######ITEMLABEL_LOCATION######ITEMLABEL_TIMES_NEEDED######ITEMLABEL_MISC_DESCRIPTION######ITEMLABEL_QUALIFICATIONS######ITEMLABEL_SKILLS######ITEMLABEL_CONTACT_INFO######ITEMLABEL_CONTACT_PHONE######ITEMLABEL_CONTACT_EMAIL### | The label for an item. The default comes from locallang.php in the extension folder. |
###TOGGLE_ITEM######TOGGLE_ITEM_END### | If you only want some information shown initially, and then if they want more, they can click a link (i.e., “Display More Info”) to see the rest. This allows shortened display listings without having to go to a new page. |
###SIGNUP_BTN### | The signup button. |
###COMMITMENT_BTN### | The commitment button. |
###SAVE_ITEM### | The link checkbox which will allow the user to save the item for later. In this way, they can look at a variety of items and sections, and save only the ones they are interested in. Note that this function uses cookies to maintain the list. |
###EDIT_BTN### | A button that will only show if can edit this ministry opportunity. This will only be available to administrators and the person who is the main contact for the given ministry opportunity. |
###SHOW_CONTACT_STAFFLINK######ITEMLABEL_CONTACT_STAFFLINK######CONTACT_STAFFLINK### | If the staffDirectoryPage constant is set, then these are filled in. The CONTACT_STAFFLINK is a link to the WEC Staff Directory page. You can change the link text or the label through locallang 'contact_stafflink' and 'itemlabel_contact_stafflink'. |
###TEMPLATE_SIGNUPFORM### -- form to signup or make a commitment | |
###ACTION_URL### | The URL to go back to this page and handle the form. This must be in the template. |
###HIDDEN_VARS### | For hidden vars that wec_servant uses for internal purposes. Please keep this otherwise the form will likely not work. |
###FORM_HEADER### | The title of the signup form and any other header information you may want to include. |
###FORM_ERROR### | If there are any errors from submitting a form (i.e., a required field is missing), this will show those errors. |
###SIGNUP_TEXT### | The text shown AFTER they signed up for one or more ministry opportunities.. |
###SIGNUP_INSTRUCTIONS### | The instructions of how to signup. |
###SHOW_REQUIRED_TEXT### | The instructions shown if there are required fields. |
###SHOW_NAME### begin/end###SHOW_EMAIL### begin/end ###SHOW_PHONE### begin/end ###SHOW_ADDRESS### begin/end ###SHOW_MESSAGE### begin/end | This is a wrapped area that will be hidden if it is not selected in the display signup field in the Flexform. We use wraps like this (as opposed to ###SHOW_MINISTRY_INFO### above) because some of the sections have multiple fields. |
###FORM_NAME### ###FORM_EMAIL### ###FORM_PHONE### ###FORM_ADDRESS### ###FORM_CITY### ###FORM_STATE### ###FORM_ZIP### ###FORM_EMAIL### ###FORM_MESSAGE### ###FORM_ATTACHMENT### | This is the form label fields that will show up if the section is shown. |
###FORM_NAME_REQUIRED### ###FORM_EMAIL_REQUIRED### ###FORM_PHONE_REQUIRED### ###FORM_ADDRESS_REQUIRED### ###FORM_MESSAGE_REQUIRED### | This is for if the given field is required, then the ###FORM_REQUIRED_MARKER### will be added. By default this is a red * (asterisk). |
###VALUE_NAME### ###VALUE_EMAIL### ###VALUE_PHONE### ###VALUE_ADDRESS### ###VALUE_CITY### ###VALUE_STATE### ###VALUE_ZIP### ###VALUE_EMAIL### ###VALUE_MESSAGE### ###VALUE_ATTACHMENT### | This is the given value for the form. These may be filled in by default if any of the information is known. Or if they submitted the form and had incorrect or missing fields, these will be used to keep the values in the form. |
###VALUE_RADIO_BUTTON_VALUE### | You can preserve the radio button values in your form (when there is an error) by putting this in the <input> field. The format is all uppercase of radio button NAME + _ + radio button VALUE. For example: <input name="tx_wecservant[Is_married]" type="radio" value="Yes" ###VALUE_IS_MARRIED_YES###> Yes <input name="tx_wecservant[Is_married]" type="radio" value="No" ###VALUE_IS_MARRIED_NO###> No |
###SUBMIT_BTN_TEXT### | The submit button text value for the form. |
###CANCEL_BTN### | The cancel button for the form. |
###TEMPLATE_PREVIEW### -- allow to setup a preview of a given servant matcher | |
###PREVIEW_TITLE### | The title / header for the preview. |
###PREVIEW_ITEM_LIST### | The list of items for the preview |
###GO_BTN### | The name of the button/link to go to the Servant Matcher |
###PREVIEW_ITEM### | The wrap for showing a single preview item. |
###NAME### | The name of the given ministry opportunity. |
###DESCRIPTION### | The description of the given ministry opportunity. |
###TEMPLATE_ADMINMENU### -- form(s) to do the admin menu | |
###ADMIN_>>>>>### | These are the admin sections that are not explicitly detailed for now. You can look at the template code and determine most of them from that. You can change the admin menu by deleting or changing items, but it does not currently support any additions. |
This extension has extensive CSS support of all parts that are displayed. Some CSS can be put in directly to the template file, if needed. However, we recommend that you change the CSS and setup your own file if you will be modifying the look extensively. The CSS file can be found in ext_typoscript_setup.txt file in the extension directory (usually this is at: typo3conf/ext/wec_servant/ext_typoscript_setup.txt).
You can override the CSS by creating your own CSS file and putting it in the fileadmin folder. You can edit and then upload it using the Filelist utility. We would recommend to put it in a location like fileadmin/wec_servant/. After you go to Filelist, you have to create the wec_servant folder if it does not exist. Then upload the CSS and/or template files there. To let the extension know about this new location, you need to set the TypoScript page variable headerData to include the CSS file. You can do this by changing the TypoScript Setup for a page. You also must clear out the old CSS references. An example is below:
# Clear out the existing CSS
plugin.tx_wecservant_pi1._CSS_DEFAULT_STYLE >
# Include the new CSS file on your page.
page.headerData.10 = TEXT
page.headerData.10.value = <link rel="stylesheet" type="text/css" href="fileadmin/wec_servant/myextension.css"
Some CSS elements of note that should be mentioned are:
CSS ELEMENT | DESCRIPTION |
|---|---|
.tx-wecservant-content | main content wrapper |
.tx-wecservant-header | main header |
.tx-wecservant-navbar | where the save/print min. opportunities links are |
.tx-wecservant-button | the display of a button |
.tx-wecservant-displayItem | the display of a ministry opportunity item in a list |
.tx-wecservant-multiList | for skills, the display of multiple checkbox items in rows. |
.tx-wecservant-selectForm | the layout for the select dropdown menu(s) for choosing ministry, needs, and last added. |
.tx-wecservant-form | the signup form design & layout. |
The text for this extension has been placed in the typo3conf/ext/wecservant/ folder under pi1/locallang.php file and locallang_dp.php file. You can extend to support different languages by adding translations to this file.
To configure a different language, you should refer to the TYPO3 documentation and check out the http://typo3.org/documentation/tips-tricks/multi-language-sites-in-typo3/ one-pagetree.
As an overview, you would set the following in TypoScript:
# Set up the language variable "L" to be passed along with links
config.linkVars = L
# For German/Deutsch language, sys_language.uid = 2
config.sys_language_uid = 2
config.language = de
config.locale_all = de_DE
# For Dutch language,
config.sys_language_uid = 1
config.language = dk
config.locale_all = danish
You can add any additional information you want in your signup form. The basic fields of name / address / email / phone can be added to or changed to whatever you would like. You can setup the form to handle input text, checkboxes, radio buttons, text area, or other form inputs.
For an example template that has over 30 fields, you can look at the one in wec_servant/pi1/wecservant-ging.tmpl. This is used by Ginghamsburg church.
To do this, all you need to do is:1) Add to the template file You should preferably have your own custom template file – you can add additional fields in the ###TEMPLATE_SIGNUPFORM###2) Additional fields must be in the format: ... name=”tx_wecservant[field_name]” .... whatever name you use as field_name, it must use underscores (no spaces). The name you use, will be output in the email sent. So [is_married] will be shown as “Is married” in the email. Or [how_many_children] will be “How many children”.Also, if you want values put in, then you must put ###VALUE_field_name### in. This will only be filled in if it has the value, which is only the case when the user entered in values, and one was required.Some examples of form inputs include:
For selecting radio buttons about what service they attend:
<input name="tx_wecservant[attend_service]" type="radio" value="Sun 9:00am" > 9:00am<input name="tx_wecservant[attend_service]" type="radio" value="Sun 10:15am" > 10:15am<input name="tx_wecservant[attend_service]" type="radio" value="Sun 11:30am" > 11:30am<input name="tx_wecservant[attend_service]" type="radio" value="Sun 6:00pm" > 6:00pm
For whether they are married or not:
<input name="tx_wecservant[Is_married]" type="radio" value="Yes"> Yes<input name="tx_wecservant[Is_married]" type="radio" value="No"> No
For comments:
Enter Your Comments: <textarea name="tx_wecservant[other_comments]" cols="30" rows="3"></textarea>
3) Requiring fieldsIf you want certain fields to be required to be filled in, you can add an asterisk to the end of the field name. So tx_wecservant[is_member+] would mean that the is_member field is required. The plus sign (+) will not be printed out on the field name or in the output email. But if the user does not fill in this field, it will ask them again to fill in the field. An error message that comes back will be like: “The 'Is Member” field needs to be filled in before you submit this”. All text fields will require at least one character of input. A dropdown menu will require a selection other than the default (zero value). For checkbox input, the field being required is not useful and so is not supported as required.
If the field is a radio button, the system will require that the user select one of the radio buttons in the group. However, to make a radio button required, what you need to do is add a hidden one with a + sign in addition to the radio buttons. This will let the system know that this is required. An example required radio button entry is:
<input type="hidden" name="tx_wecservant[Is_married+]">
4) The limitationsWith this system, you cannot format the email easily. They will be listed in whatever order is in the form. Also, there is no validation on the form values...other than if they have values. Yet you can add whatever fields you want.
If you want to allow someone to signup to serve but no ministry fits or they want a custom ministry– then this allows that. What you have to do is this:1) Create a link either in your header text (Flexform Text tab under Header Text) or in your template with:#yourURL#/?makeCommitment=-2 or #yourURL#/?showInterest=-2 or you can add the makeCommitment or showInterest to your form too.2) Then you need to make sure that the constant in locallang.php is set for 'admin_emai'l and 'admin_name'. If set, then these will be used. An alternative is that you can use the notify_email option in the Administrator tab of the Flexform. This will send to the notify_email instead.
3) You will receive the signups at the 'admin_email' constant or 'notify_email' config. It's that easy!
You can link directly to all the ministry opportunities associated with one ministry or with one or more skills. You may want to do this so that on a ministry page, you can link to ministry opportunities only associated with that ministry. Or if you want only certain skills/interests/etc. associated (perhaps Weekend Worship or *any* Youth events), you could add a link to those directly. Below is how you can do this:
You just need to add 'showministry=[ministry name]' parameter to your url. First, you must know the URL to your Servant Matcher. In the example below, you must replace 'http://www.yoursite.org/serve/' to where it is on your website. Then you just need to add showministry="ministry name". If your ministry name has spaces, then replace the spaces with the '_' character. If there are other parameters in the URL, you may need to use &showministry=[ministry name] instead of ?showministry=[ministry name]. ? is used for the first parameter and & is used for additional parameters.
http://www.yoursite.com/serve/?showministry=Childrens_Ministry
If you want to add the full code to an HTML element, you could link with something like:
<a href="http://www.yoursite.com/serve/?showministry=Worship">Serve with the Worship Team</a>
You can add showskills_all (have to match all skills) or showskills_any (will match any skills listed). You can just have one skill, or several, depending on your needs. If you do have more than one skill, you can separate them with the | character. If you have characters in the skills/interest name, then use '_' instead of a space. Each skill will be the text representation given in the Skills list. Some examples will clarify:
http://www.yoursite.com/serve/?showskills_all=Youth|Bible_Study
http://www.yoursite.com/serve/?showskills_all=Weekend_Worship|Greeting.
<a href="http://www.yoursite.com/serve/?showskills_any=Gardening|Discipleship">You can grow people or plants</a>
If you do not have or do not want to support emails for your contacts, or you have a generic contact, then you still want to get the emails that are sent. This extension provides two different ways of handling email:
In the Flexform for the WEC Servant extension, you can go to the Adminstrator tab and look for the "Notify email to receive ALL contacts". You can set one or more emails here. Make sure they are specified in the right format, i.e. "myemail@email.com".
If you set an email here, you will receive all contacts, including ones that are set. If you have certain contact email's set and others not, you may want to use the method below.
If you want a default email set, then you can set the 'adminEmail' local language variable. This is the fallback/default email. You can set this by editing your extension template on the WEC Servant page -- go to Templates->Info/Modify in the Backend. If an extension template does not exist, you can create a new one. Then you would add the following to the SETUP field in the template:
tx_wecservant_pi1._LOCAL_LANG.default {adminEmail = myemail@mail.com
}
