EXT: WEC Servant Connector¶

Features¶

Major features include:

• Flexible ways to connect people to your ministry opportunities – use whichever way fits your church/ministry.
• Flexible ways to respond – by commitment or contact form and/or by phone/email information listed.
• Easy-to-setup, add, and modify.
• Customizable look, layout, and colors.
• Each ministry area can have a link in its own section that will just show opportunities for its ministry
• Admin support where staff/owner can add/update their own opportunities that they are in charge of

Example Uses¶

The following are real-working examples of this extension:

http://www.ginghamsburg.org/serve/ -- this uses a variety of skills and is the basis for many of the great features and options

Screenshots¶

Below are some examples of what the Servant Matcher extension could look like:

This is the Ginghamsburg Servant Catalog

This shows how you can search by skills/interests

This is the new version 2.0 look for Servant Matcher

What Is The Web-Empowered Church?¶

The Web-Empowered Church (WEC) is a ministry of Christian Technology Ministries International ( www.CTMI.com ) The mission of WEC is to innovatively apply WEB technology to EMPOWER the worldwide CHURCH for ministry.

WEC is helping churches around the world expand evangelism, discipleship, and care through the innovative application of internet technology. WEC web-based tools and training are helping make church ministries more efficient and effective, and they are extending ministry impact to a world in need of Jesus. We are helping to fuel a worldwide movement using the internet to point the world to Jesus Christ, to grow disciples, and to care for those in need. Our vision is to use the web to empower the Church so it can truly be a twenty- four hours per day, seven days per week ministry that is unconstrained by walls, distance, or time.

If you would like to find out more about WEC or our tools, or support us in any way, please go to our website at: www.WebEmpoweredChurch.org .

Install The Extension¶

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.

Create Or Set The Data Folder¶

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.

Add The Extension¶

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.

Configure Options¶

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 buttonand selecting that folder.

Example of the Servant Matcher FlexForm

The following is a description of each option that is available in the FlexForm:

MAIN

Add New Ministry¶

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:

Add New Or Update Existing Contact¶

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 user s, 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.

Add New Ministry Skills¶

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:

Add New Ministry Opportunities¶

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:

Setup the Template¶

Change The Look¶

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 Filelistutility. 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. TypoScript In the template's TypoScriptConstants 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.

Test It Out¶

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.

Change Group Type Names¶

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:

F.A.Q.¶

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.

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.

TypoScript Reference¶

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.

page.templateFile = fileadmin/wec_servant/my_wecservant.tmpl

Template File¶

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.

<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

Multi-language¶

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 TYPO3documentation 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

Extending your signup form¶

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.

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 fields* If 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 limitations With 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.

Allow to signup for custom ministry¶

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=-2or 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!

Linking directly to ministry or skill(s)¶

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:

http://www.yoursite.com/serve/?showministry=Childrens_Ministry

<a href="http://www.yoursite.com/serve/?showministry=Worship">Serve with the Worship Team</a>

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>

Handling Contacts without Emails¶

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:

tx_wecservant_pi1._LOCAL_LANG.default {
    adminEmail = myemail@mail.com
}

Changes¶

All template and CSS files have been moved to the folder wec_servant/template/ . To ensure access to the new template system, TypoScript (TS) has been written into the template’s constants for both the template and CSS files:

plugin_tx_wecservant_pi1.templateFile = EXT:wec_servant/template/wecservant.tmpl

plugin_tx_wecservant_pi1.baseCSSFile =  EXT:wec_servant/template/pluginstyles.css
plugin_tx_wecservant_pi1.cssFile =  EXT:wec_servant/template/wecservant.css

The pluginstyles.css file is used as the CSS foundation for most WEC plugins using new templates. This allows custom styling across many WEC plugins for the site's template. It also simplifies and compacts the CSS when multiple WEC plugins are installed. In addition, if the wec_styles plugin is installed, it accesses the pluginstyles.css from wec_styles first. This ensures improvements in pluginstyles.css are incorporated site-wide. Otherwise, if wec_styles is not installed, then it uses the pluginstyles.css from this plugin.

Upgrading an Old Custom Template¶

If you have an old custom template, you will need to upgrade it. You can choose to either upgrade using the old templating system or using the new templating system. Upgrading to the new system is work- intensive, but offers a significant improvement in the look. We suggest referring to the new template at: wec_servant/template/wecservant.tmpl and the new CSS in wec_servant/template/wecservant.css .

If you choose to remain with the older system, you can find the template files at wecservant-old.tmpl and the CSS file at wec_servant/static/ts/setup.txt .

To upgrade using the old templating system, the main issues you will likely encounter will be:

• The handling of buttons have changed. If you examine the button code you will see that your current buttons will not work right.
• Everything is more semantic HTML. For instance, list views use <ul><li> instead of multiple <div> tags.
• Each section is appropriately called using a consistent naming convention (plugin[*]), e.g., pluginNav, pluginHeader, pluginFooter, pluginSection, pluginAside. We have used HTML5 tags as the base for class names when possible.

To upgrade to the new template system, we strongly suggest using the new template as a foundation and adding CSS or objects to the template as desired. The CSS and HTML structure of the template has changed so significantly that we advise starting from scratch rather than trying to change an existing template.

Using the New Template System¶

If you want to use the new default template and have installed v1.x, use the TYPO3 Template tool and access the page where the +ext template for the *WEC Servant Matcher Template* is included (generally on the same page as the WEC Servant Matcher plugin). Click the template's edit icon and select the Includes tab. In the Include Static field, delete the *WEC Servant Matcher (old) Template* (older templates were renamed for easy identification). Next, add the *WEC Servant Matcher Template* .Save the template record and clear the caches (the lightning bolt icon at the top right of the TYPO3 toolbar). Test each page that has a WEC Servant Matcher installation. Once you've included the new template, modify the look by accessing the Plugin's Display tab.

Creating a Custom Template¶

To create a custom template, we recommend beginning with the *wecservant.tmpl* and *wecservant.css* files as models. To change the look of an entry, use one of the wecentry[1-3].css files in the folder wec_servant/template as a model.

Once you've made your changes, go to the +ext template and in the SETUP section (or you can use the Constant Editor), you can set the *plugin_tx_wecservant_pi1.cssFile* to the location of the new css file, and *plugin_tx_wecservant_pi1.templateFile* to the location of the new template file. The wec_servant extension will then use your new template and/or CSS.