To setup and use the Servant Matcher extension, you will need to do the following:
Install The Extension
Create Or Set the Data Folder
Add The Extension
Configure The Options
Add New Or Update Existing Contacts
Add New Ministries
Add New Skills (optional)
Add New Ministry Opportunities
Change The Look
Test It Out
Change Group Type Names
The following will take you through each step:
The first step you need to do is to install the extension – WEC Servant Matcher (wec_servant) -- with the extension manager. You can get it by going to Tools section and choosing “Ext Manager” on the main action menu (usually on left-side). Then in the dropdown Menu at the top, select “Import Extensions” in the Menu at top. Then type “wec_servant” or “wec” in the “Extensions in TYPO3 Extension Repository” and click on the “Look up” button. You should then find the Servant Matcher extension.
If you have never installed this, then you will see a red arrow to the left of “WEC Servant Matcher” and you can click on that to install. If it has been installed (it may be if using the WEC Starter package, depending on your version), you can click on the green arrow to the left of the extension or the name of the extension and then load the newest version by clicking on the Import/Update button. It is highly recommended to install the new extension in the "local" folder (LOCAL: typo3conf/ext/wec_servant).
When you do install it, please be sure to Import Static Data after it is installed. You will see this on the Servant Matcher Information page in the Extension Manager as well as right after you install the extension.
You can now create a new Storage Folder or use the global Storage Folder that will have your data for the Servant Matcher in it. We recommend to use a new Storage Folder because there can be many records and you can keep everything in one place. Also, with separate Storage Folders, you can make different Servant Matchers with different data. It is certainly possible to place all the data in the global Storage Folder too – the extension works with either option.
If you want to put the Servant Matcher information in its own Storage Folder, you can do this by: create a new SysFolder by going to the page where the Servant Matcher is installed. Choose “Create New Record” and “Page (inside)” as the New Record type. At the New Record, choose SysFolder as the type of new record. Add a title like “Servant Storage” and you will likely want to un-hide it by clearing the Hide Page checkbox. Once you are done, go ahead and Save this record.
To add the extension, you can create a new page first by choosing “Create new record” and choosing “Page (inside)” as the New Record type. Unhide the page and name it in the Pagetitle with something appropriate. Or, if you already have an existing page to add it to, just select the page.
Then to actually add the extension to the page, click on “Create new record” and choose Pagecontent for the type of New Record. When it brings up the new Pagecontent element, select "Insert Plugin" as the Type, and then choosing “WEC Servant Matcher” in the Plugin drop down menu. You can also name it here in the Header and put something just for reference like “servant matcher”. So this does not display, be sure to set the Type: under Header to “Hidden”. When you are done with this, save and close it.
After you create a page and add the extension, you can bring up the Flexform so that you can change options, you must edit the Servant Matcher pagecontent.
One very important setting that you must do is let the extension know about the data storage folder you have set. You can do this by setting the Startingpoint in the Main tab. Set it to the “Servant Storage” Folder you just created or the global Storage Folder by clicking on the Choose File button and selecting that folder.
The following is a description of each option that is available in the FlexForm:
MAIN
FLEXFORM OPTION | DESCRIPTION |
|---|---|
Title of Servant Matcher | What you want displayed at the top and used in email description. This is optional but allows you to add it here. |
Allow To "Find By Ministry" (dropdown) | Can search by drop-down ministry list. This ministry list is based on all ministries that are in fe_groups that are of type=Ministry. |
Allow To "Find By Ministries" (checkbox) | Can search ministry list shown using checkboxes. User can select multiple ministries. This ministry list is based on all ministries that are in fe_groups that are of type=Ministry. |
Allow To "Find By Priority/Needs" | Can search by Priority/Needs from drop down list. The values available are: “Normal”, “Urgent”, “High”, “Low”, and “Special”. These priorities can be changed in the pi1/locallang.php and locallang_db file and can be set to any naming convention you would like. |
Allow To "Find By Last Added" | Can search by “Last added” from a drop down menu. The options are “In Past Week”, “In Past Month”, “In Past 3 Months”, and “In Past 6 Months”. |
Allow To "Find By Skills" | Can search by list of skills. All skills are shown as checkboxes. They can be grouped in sections when set with groupBy field for each skill. If you do not have any skills available or this is not checked, then you will not be able to “select by skills”. |
Template File | Select and choose the template file for this Extension page. If you do not define one, then the default template will be used. You can also define a template through TypoScript constants and/or the Constant Editor (see below). |
Startingpoint | Choose which Data Folder you want the data to be stored in and retrieved from. We highly recommend you set this up and keep all data in one place. If you do not choose a Startingpoint data location, then it will store and pull data from the current page. |
OPTIONS
FLEXFORM OPTION | DESCRIPTION |
|---|---|
How Can Respond? | Will choose how you want people to respond: - No form – if just want them to respond by email, address or phone # given. - Interest form – the user can send an email to contact saying they are interested in opportunity - Commitment form – the user can send an email to contact saying they are committed - Interest + Commitment – if you want both options available |
Show Ministry List At First (otherwise hide) | This will show the Ministries list at first (selected by choosing Find By Ministries in Main tab). The default is to show it, but you can have it so it is in the toggled hidden state where the user has to click on it to show the ministries. |
Show Skills List At First (otherwise hide) | This will show the Skills list at first (selected by choosing Find By Skills in Main tab). The default is not to show it, but you can have it so it is shown right away. |
Show All Of Description? | If you want the full description to be listed, choose this. Otherwise, the default is to show a shortened description where they have to click on “More” to see the rest of the description. The More opens up in CSS the full description. The purpose of this option is if you have many opportunities available, you can see and scan 20+ easily in a shortened form. |
Can Save For Later? | If you want them to be able to save a ministry opportunity for later, then check this. If they can save it for later, they can browse and choose as many as they want. This is a nice feature to allow, but if you want a simplified interface or do not have many opportunities (i.e., < 30) , then you can disable this. |
Require Login For Signup/Commitment? | If you want the user to be logged in before they can signup/commit then check this. If this is checked, then the buttons will not display unless they are signed in – you may want to note that in your instructions. |
FIELDS
FLEXFORM OPTION | DESCRIPTION |
|---|---|
Fields to DISPLAY for showing opportunities | You can customize which fields will be displayed for opportunities. If this is not set, then all fields in the template will be used. |
Fields REQUIRED for signup form | You can select certain fields as required for the signup form. If these fields are required, the user must enter something in the field(s) before it can be sent. If this is not set, then no fields are required. |
Fields to DISPLAY for signup form | You can select which fields to display for the signup form. If this is not set, then all fields in the template will be displayed. |
ADMINISTRATOR
FLEXFORM OPTION | DESCRIPTION |
|---|---|
Administrator(s) UID or username (sep. by comma) | List of any administrators for this extension. The administrator(s) will have access to the admin menu and all of its functions. You can list the Typo3 fe_user UID or their fe_user username. Separate each by a comma if there is more than one. i.e., jsmith, mswanson, efallow, 214 An additional option is that you can set an admin so that they only have access to a given ministry(s). To do so, you add a : after the username/user_uid and then list the ministry name. If there are spaces in the ministry name add a “_'. This must match exactly with what is in the fe_groups. If you want multiple ministries, then list each one with a | separator. An example should be helpful:i.e., jsmith:cell_group_ministry,mswanson, efallow:childrens_ministry|youth_ministry,214 |
Contact name for all outgoing email | The contact name for all outgoing email. |
Contact email for all outgoing email (i.e., admin@web.com) | The contact email for all outgoing email. If it is left blank, then the contact person for the opportunity will be used. If there is none for that, then the default <nobody@nowhere.com> is used. |
Notify email to receive ALL contacts | If you want to receive all interest requests and commitments at one email address, you can set this to a valid email address. With this set, all emails will ALSO be sent to here as well as the contact person. If there is no contact person or this is a custom ministry, then the notify email will receive it if set. |
PREVIEW
FLEXFORM OPTION | DESCRIPTION |
|---|---|
Is This A Preview Only? | Mark if this is a preview. A preview is a shortened view of a list of ministry opportunities based on a given ministry. It is useful to put on other pages, not the main Servant Matcher page. Note that if you set this, you will only see a preview and the options below will be used. |
Title Of Preview | The title that is above the preview. |
Preview Button Name | The button/link text that is at the bottom of the preview. This will take you to the actual Servant Matcher page that is linked in (see below). |
How Many To Preview (0 = just a link)? | How many entries for the given “ministry” to show. If you just want a link, you can set this to zero and you will just see a link that will go to the Servant Matcher page. |
Length for Description Field? | How many characters of text you want to show for each entry. This is the description field that can be 200+ characters, and so you will likely want to limit it. The default length is 64 characters. |
Which Ministry To Preview? | The ministry you want to preview. If you do not choose one, then it will show all ministries. |
Choose Servant Matcher Data Folder | This should be set to where you have the Servant Matcher data located. |
Choose Servant Matcher Page To Link To | This should be set to the page you want to link to. If it is not set, then there will be no link – you can add your own on the page. |
TEXT
FLEXFORM OPTION | DESCRIPTION |
|---|---|
Header Text | For any header text that goes on the main form, you can add it here. You can include any HTML code that you would like. This is optional. |
Contact Form Header/Instructions (optional) | You can add any instructions or header that you want on the top of the contact/commitment form. |
Contact Email Header text (optional) | If you want to include a header text before the main contact email that is sent out when a user submits the Contact form. Note that this form is sent to the Contact person(s) email. |
Contact Email Footer text (optional) | If you want to include any footer text after the main contact email that is sent out when a user submits the Contact form. |
After you are done setting the options, then you need to save the data by clicking on the Save or Save & Close icon button.
To add a new ministry, you just go to your “global” Storage Folder and "Create New Record" and choose "Website usergroup". This is a fe_group (front-end group) in the Typo3 terminology. You will want to put this in the “global” folder as opposed to the Servant Storage folder because usergroups are global and can be used in various places.
You will want to create a usergroup that has a Type of Group = Ministry. Note that if you want to change the terminology for calling these Type of Groups, see below for “Change Group Type Names”. Looking at the structure of a record, you will see the following fields:
Field Name | Field Description |
Grouptitle | The title of this ministry. |
Description | Description of what this ministry area is all about [optional] |
Access Type | Type of access for this group. Usually will be marked public. |
Type of Group | The type of group this is. You can create your own types. This must be marked Ministry. |
Administrator list | A list of administrators that have access to it. |
You can also change a given Website usergroup to a ministry by just setting the “Type of Group” to Ministry.
To create a new contact, you just go to your “global” Storage Folder and "Create New Record" and choose "Website user". This is a fe_user (front-end user) in the Typo3 terminology. If you create this in your Servant Storage folder, the users will not be accessible outside of this extension and so it is recommended to put these in your global Storage folder. If you already have existing site with Website users, you can just edit these and set them as Ministry Contacts.
If you are creating new users, you need to set the username, name, password, and select a group(s). There is only one necessary field for the Servant Matcher that you need to set in the Website user field: it is the “Is Ministry Contact” field and is found at the very bottom.
Field Name | Field Description |
Is Ministry Contact | A checkbox where you will set this and this will then allow the extension to know this is a contact and they can be selected. |
If you have already created contacts or have existing users, you can then just edit the fields and set the “Is Ministry Contact” field so they are now recognized as Ministry Contacts for the Servant Matcher.
Skills can be actual skills or interests (i.e., “Woodwork”, “Teaching”, “Computers”, “Musician”, etc.), or passions (i.e., “Helping Homeless”, “Missions Work”, “Youth”, etc.) or spiritual gifts (“Teaching”, ”Leadership”, ”Administration”,”Giving”, ”Helping”, ”Evangelism”, etc.) or times ("Weekend","Wednesday night", "Saturday", etc). You may also add on demographics or age groups interested in (i.e., “Singles”, “Youth”, “Children”). The Skills system is very flexible, and should suit many needs. However, it will take some thought & planning to set it up well for your church or ministry.
If you are wanting to use “skills” for your ministry opportunities, you will need to create these skill records. To do this, you can just go to your Data Folder and "Create New Record" and choose "Ministry Skills". Looking at the structure of a Ministry Skill record, you will see the following fields:
Field Name | Field Description |
Skill Name | The name of the skill, interest, or spiritual gift. |
Any additional description | Any additional description of the skill/interest/gift [optional] |
Group this by | Any grouping to group by – put the group name here. This will put the group name as the header of the list of skills for this group. Note that you must match the text for this exactly for skills to be grouped together. [optional] |
Sort order | Any sort order (descending, from highest to lowest) so 1 is lowest and 100 is highest. This sort order will effect the total sort order. If items are grouped, then the item with the highest sort order will be used for sorting. [optional] |
Required group | If this is a required group. then you can set this. If it is required – what it means that at least one option out of the given skills in this group must be selected. If one is not selected in a required group, then the extension will give an error until one is selected. The values for this are:0 (default) : not required. If this is the case, you do not need to enter anything.1 : yes, this group is required. 2: yes, this group is required and this is set on as a default. You can have more than one set as the default in a group. |
To create this content, you just go to your Servant Storage folder and "Create New Record" and choose "Ministry Opportunity". Note that you can create this in your current page where the wec_servant extension is IF it is used in only one place/page. However, if you have it on more than one page or used throughout your site, then we would recommend to save these Ministry Opportunities in the Global Storage Folder.
Looking at the structure of a Ministry Opportunity record, you will see the following fields:
Field Name | Field Description |
Name Of Ministry Opportunity | Main title of this ministry opportunity. |
Description | Description of what person will do. You can have linebreaks and HTML tags in this. |
Ministry | Selection of all ministries that are available. Points to fe_group table where type is = Ministry. |
Contact Person | Contact person available. You must have people setup as fe_users and then set the is_ministry_contact field. |
Location | Where this is located at. |
Days/Times Needed | What times needed for. |
Priority Of Need | Select the priority. Normal / Urgent / High / Low / Special (optional) |
Skills / Interests Needed | List of skills available. Whatever has been created as a WEC Ministry Skill will be listed here. |
Contact Info (if needed) | Any extra contact info (beyond the contact person) |
Misc Description | Any additional information to describe this opportunity. You can have linebreaks and HTML tags in this. |
Qualifications | Any qualifications needed for this opportunity. You can have linebreaks and HTML tags in this. |
Start | The date the opportunity should start at [optional]. Leave this blank if the ministry opportunity has no start or stop period. |
Stop | The date the content should finish [optional]. Leave this blank too if the ministry opportunity has no start or stop period. |
Note that you can add linebreaks and HTML tags (i.e., <b>, <i>, <span style=”color:#RRGGBB”>...etc) to format some of these fields better. The fields that support this are: description, Misc Description, and Qualifications.
In general we recommend installing an extension template record to the Servant Matcher page. This extension template will store the Template constants. To install an extension template record, see the How-To at: http://webempoweredchurch.com/support/howtos/single/add_an_extension_template_record.
The static template contains the information used by the web browser to display the Servant Matcher. The Servant Matcher static template can be installed in your site's main Template Record. The name of the Static Templates required by the Servant Matcher is WEC Servant Matcher template.
Internet Link: Instructions for adding the Static Templates can be found in the how at http://webempoweredchurch.com/support/howtos/single_howto_article/add_a_static_template.
You can either refine or totally redo the look for the Servant Matcher to fit your needs. Using the Template system and Constant Editor, you can create a new look for the overall page. You do this by changing the template and by setting the color, font, and CSS constants. The default template is called wecservant.tmpl and is in the extensions folder under /pi1 (typically typo3conf/ext/wec_servant/pi1). You can edit and create your own template file and then upload it using the FlexForm configuration when you set up your page.
If you do edit the template file or create your own CSS file, we recommend that you put it in its own location outside the extension folder. You can edit it and then upload it using the Filelist utility. We also recommend to put it in a location like fileadmin/wec_servant/. You have to create the wec_servant folder in the root of fileadmin. To let the extension know about this new location, you need to set the templateFile variable. You can do this in one of the following ways:
a. Choose the Template file in the FlexForm
You can open up your pageContent and you will see the FlexForm. On the “Main” link, you can choose the Template file. See above in “Configure Options” for complete details. Note that if you set it this way, that whenever you make a change, you will have to set this file in this way.
b. TypoScriptIn the template's TypoScript Constants section, set
page.templateFile = fileadmin/wec_servant/my_wecservant.tmpl
Note that using this way, you can easily change the template and just clear Cache to try different settings.
c. Constant Editor
See below in the Configuration section to see how to change the templateFile constant.
You can also just edit the constants to change the position, color, and text font and size for much of the WEC Servant Matcher extension. The constants that can be changed are listed in the 1.4.2 Configuration section. You can set these in the Constants Editor or directly in TypoScript.
Once you have setup all the previous information, you can now test out the extension. To test it, you can select the page where the wec_servant extension is on, and then click the “View” action in the action bar. Or you can right click on the page with the wec_servant extension, and choose View. This will open it up in a new window.
If you like how it looks, you are ready to go. Most likely, you will want to make changes in the look, layout, or add new ministry opportunities or skills. You can go ahead and add as much as you would like, save it, then test it out over and over until you are happy with it.
The wec_servant extension already comes with three predefined Group types: Ministry, Class, Small Group. If you want to change the name of these or create or delete the given ones, you need to go to your root folder. This is usually done by clicking on the World icon at the very top of the page tree. Then find the listing for “Group Type”. You will see these listed, and you can add more, change these, or even delete these. Note that the Servant Matcher extension is setup to work with the Ministry Group Type so do not delete that – just rename it. The other group types are not currently used but for future extensions.Looking at the structure of a record, you will see the following fields:
Field Name | Field Description |
Name of Group Type | The title of this group type. Examples of types for churches and ministries might be: Ministry / Small Group / Class / etc. |
Description of Group Type | Description of what this group type is [optional] |
The following are questions that may help you better understand and use this extension:
Q: When I get to creating a new Ministry Opportunity, the Ministry field is blank? Or the Contacts or Skills are blank?
This problem may be caused by one of two problems: 1) Make sure that the Group Types are loaded in. Go to the Extension Manager, select the WEC Servant Matcher and Import the Static Data.
2) The Startingpoint page is not set. Go to the Flexform for the Servant Matcher and set the Startingpoint to the folder that has the Ministry data.
Q: How can I setup skills right? I am not sure I understand how that all works.
A: The skills system allows you to set “skills” for each ministry opportunity. These “skills” can be actual skills or interests or passions or spiritual gifts or whatever fits you. You can even mix them together. The goal is to create something that is helpful to people using your website and this Servant Matcher.Perhaps easiest way is for an example or two to explain the “skills”. Also, we would recommend that you check out www.ginghamsburg.org/serve to see how they are used in a variety of ways.
Ministry Opportunity | “Skills” / Interests |
|---|---|
Teach Children's Class on Sunday Morning | Teaching, Children. |
Church Fix-up Day | Yardwork, Cleaning, Hauling, Serving, Repairing. |
Small Group Leader | Teaching, Facilitating, Church Member. |
Greeter For Sunday Service | Friendly, Helping Others. |
Feed Homeless At Soup Kitchen | Helping, (passion for) Homeless/Disadvantaged/Poor, |
Usher | Helping Others, Responsible. |
Q: How can I configure for different needs/priorities? Why should I use this?
A: The needs/priorities allow you to alert your ministry group of certain needs that are higher priority than others. So, if you have an immediate need, you can let them know. You may not want to use it, but this is available. It is easy to set and update the priority in the Admin or Backend interface.
If you would like to change the names of the priorities, you would need to change the locallang.php file and the priorityLevel0...priorityLevel5 values. And also change the values in locallang_db.php in the pi1/ folder of the extension under tx_wecservant_minopp.priority.I.***. If you want to shorten the list, you can delete those you do not want, and the system should handle it. You can add up to 9 different needs/priorities.
Q: How do I put the opportunities on my other ministry pages?
A: It is not too difficult. You just need to create a new PageContent element with the wec_servant plugin. And you will go to the Preview section in the Flexform and set it as a Preview. You must point back to the page of the original Servant Matcher data. It should be that easy and definitely check out the options for Preview.
If you would like to make the Preview look different, you can stylize the template of preview in ###TEMPLATE_PREVIEW### in the wecservant.tmpl template file.
Q: I already have a Typo3 site setup, how can I update for existing users and groups?
A: You should go through the “Website user” list which is usually found in the main “Storage Folder” of your website. You can search that for any staff or people who should be contacts. Then edit the user record and set the “Is Ministry Contact” field for each one that is a contact. Once you do that, they will appear in the list of contacts.
Q: How can my staff keep their own opportunities up-to-date?A: If they are set as contacts (Is Ministry Contact), then all they need to do is login to their account on your website, and then go to where the Servant Matcher is setup. They can then look for the ministry opportunities and if they can edit one, they will see an “Edit” button. Once they click on this, they can change and update any of the fields for this opportunity.
Only users who are set to “Admin” can actually add new opportunities or delete existing ones. You can set up Admins in the Admin menu by setting their “Is Ministry Contact”.
Additionally, you can setup in the Backend, so that users can edit the Backend records and create these ministry opportunities. The Front-End way just makes it more flexible for users.
Q: What if someone wants to signup but no opportunities fit with them ?A: That is a good question and we added a way to handle this. Please look at the Allowing To Signup for Custom Ministry in the Configuration section below.
Q: I want to add linebreaks and/or style options to the Description and other fields. How can I do that?A: You can now add linebreaks and some HTML tags to the Description, Misc Description, and Qualifications fields for the Ministry Opportunity record. An example of this might be:
This is a <b>description</b> of this opportunity. It has three key parts:
#1 part 1 here
#2 part 2 here
#3 part 3 here
This is a <span style=”color:#FF0000”>red lettering</span> here.
Q: How can I allow to view a single item?A: You can add the ###VIEW_SINGLE### marker to the template. It is not included by default. Also, if you know the ministry opportunity you want to link to directly, you could hardcode a link such as http://www.mysite.com/serve/?tx_wecservant[single]=42 where 42 is uid of the ministry opportunity you want to link to.
More questions coming as they are received...please send us yours!
