.. done

Small Group Finder Step 4 - Create the XML File
===============================================

If you have not read the Overview about how the Small Group Finder works, or Steps 1 and 2,
you will want to do so before proceeding.

.. seealso::
    | :doc:`SmallGroupFinder`
    | :doc:`SmallGroupFinderStep1`
    | :doc:`SmallGroupFinderStep2`
    | :doc:`SmallGroupFinderStep3`

Create the Small Group Finder XML file
--------------------------------------

This file is where you enter the ID #(s) for **Division(s)** you are using for your small groups,
and the name of the **Layout** and **Gutter** files you just created.

Step 1
    Go to `Administration > Special Content > Text Content` tab, and click `+ New Text File`.
    Enter the File Name as ``SGF-Main.xml`` and click `Submit`.

.. note::
    This is not the same tab as the one used for the layout and gutter. The XML file is created
    on the Text Content tab, and the layout and gutter were created on the Html Content tab.

Step 2
    Copy and paste the following into the text box:

    .. code-block:: xml
        :linenos:

        <?xml version="1.0" encoding="utf-8"?>
        <SGF divisionid="14,18" layout="SGF-Layout" shell="SGF-Shell">
            <SGFSettings>
                <SGFSetting name="Title" value="Community Groups" />
                <!-- the settings on the next lines, 6-11, apply when no shell file is listed on line 2 -->
                <SGFSetting name="SubmitText" value="Find Groups" />
                <SGFSetting name="ShowHeaders" value="true" />
                <SGFSetting name="TextSize" value="18" />
                <SGFSetting name="FontFamily" value="Verdana,Arial,Helvetica,sans-serif" />
                <SGFSetting name="BGColor" value="#FFFFFF" />
                <SGFSetting name="FGColor" value="#000000" />
            </SGFSettings>

            <!-- the list of filters that are used for searching... the name is the org extra value -->
            <SGFFilters>
                <SGFFilter name="SGF:Gender" title="Gender" locked="false" lockedvalue="" />
                <SGFFilter name="SGF:Childcare" title="Childcare" locked="false" lockedvalue="" />
                <SGFFilter name="SGF:Location" title="Location" locked="false" lockedvalue="" />
            </SGFFilters>
        </SGF>

    Shown below are optional settings that can be added to your XML file is desired. If used, all
    these should be inserted in the Settings section (on a new line between `<SGFSetting>` and `</SGFSetting>`).

    .. code-block:: xml
        :linenos:

                <!-- optional setting for a subtitle -->
                <SGFSetting name="Subtitle-Content" value="SGF-Subtitle" />

                <!-- optional setting to limit groups to only those of the OrgType defined -->
                <SGFSetting name="OrgTypes" value="Community Group" />

                <!-- optional setting to specify a field by which the finder groups will be sorted -->
                <SGFSetting name="SortBy" value="SGF:Neighborhood" />

                <!-- these optional settings go together to provide exclusions for certain orgs...
                     so only those with an org extra value of "Status" == "Open" will show up -->
                <SGFSetting name="ShowOnlyName" value="Status" />
                <SGFSetting name="ShowOnlyValue" value="Open" />

    Below are explanations for these optional settings:

    Optional Subtitle Text (line 2)
        If you wish to include text under your Small Group Finder title, you can create an HTML
        special content file and include the desired text. Then use the **Subtitle-Content** setting
        to point to the HTML file.

    Include Only Specified Involvement Types (line 5)
        To include only involvements of a specified Involvement Type in the group finder,
        include the setting **OrgTypes** with a value of the desire Involvement Type. For
        example, to include only groups of the type Community Groups, give the setting the
        value `Community Groups`. If multiple involvement types are entered, separate them
        with commas.

        .. Important::
                When the **OrgTypes** setting is used, it *overrides* the **divisionid** setting. All qualifying
                groups with the specified involvement type(s) are included in the finder, even if they are not
                in a division specified in the **divisionid** setting.

    Define How Groups Are Sorted (line 8)
        You can specify a particular extra value field to sort the groups in the finder.
        For example, if you give this setting the value `SGF:Neighborhood`, the groups will be sorted
        alphabetically by the values in the **SGF:Neighborhood** extra value.

    Exclude Groups from the Finder (lines 12-13)
        You may want to exclude certain groups in the specified division from appearing in the
        Small Group Finder. A group might be full, for example, or only intended for participants
        that you invite. You can use the **ShowOnly...** settings to define an additional criterion
        for inclusion in the group finder. Omit these lines if you will not use this feature.

        .. caution::
          The extra value name ("Status") used in the example code above is only an example. 
          You can name this whatever you like, but the name you enter in the XML file must
          exactly match the name of the extra value you have created, including any prefix
          (such as "SGF:" if you are using that prefix for all your Small Group Finder extra
          values).

Step 3
    After you paste the text into the new text file, there are changes you will need to make.
    These are listed below.

    - Enter the `Division ID #` *inside* the quotation marks in line 2
      after ``divisionid=``.
      If you are using multiple Divisions, comma-separate them without a space.
      Example: ``divisionid="23,24"``
    - On that same line, enter the `Layout Name` inside the quotation
      marks after ``layout=``, **only** if you named your file something
      other than SGF-Layout.
    - The same thing is true for the shell.
      Enter the `Shell Name` inside the quotation
      marks after ``shell=``, **only** if you named your file something
      other than SGF-Shell.

Step 4
    The **filters** are the drop downs that will display on the finder,
    if you added Ad Hoc `Extra Values` with the prefix SGF: on each of the Organizations.
    We include some basic filters in the above text.
    The order in which you see these in the XML file,
    is the order in which they will display on the finder.
    You can cut and paste to change the order.
    Notice that all of these are set as ``locked=false``.
    If you want a filter that cannot be changed,
    you can set it to `true`.
    You may want to contact support for help with that
    and to learn more about how that works.

    Example: **<SGFFilter name="SGF:Gender" title="Gender" locked="false" lockedvalue="" />**

    - In this example, we have an Extra Value named `SGF:Gender` on each organization,
      with values on each org are either ``Male``, ``Female``, or ``Coed``.
      The *title* is what will display as the title / label of the drop down.
      the name and the title do not have to be the same.
      However, the ``name`` must match exactly with the Extra Value on the orgs.
    - If your Extra Values are different,
      just edit the name and title.
      If you have more Extra Values that you want to use for filters,
      just copy one of those entire lines of text
      and paste if below one of the others.
      Then edit the **name** and **title**.
    - If you are not using filters,
      just remove the name and title
      from one link and leave it there
      as a template, in case you want
      to use them in the future.
      Then delete the other lines of text
      that begin with <SGFFilter.

Step 5
    There are several lines of text for Settings.

    - The `Submit Text` is the text on the button
      they will click to filter for a group.
      You can rename it from ``Find Groups`` to ``Click Here``
      or whatever you like. It just needs to be fairly short.
    - `Show Headers` can be set either ``true`` or ``false``,
      depending on whether or not you want to display this text at the
      very top of the page: **Select Group Options**,
      and **Search Results - Group(s) Found**.
    - `Text Size` can be increased or decreased,
      and affects all the text on the page.
    - The other settings relate to fonts and colors.
      If you know HTML you can edit those as needed.

Step 6
    After making all the edits listed above,
    click `Save Content`.

Check Out your Small Group Finder
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the URL you will use https://\ **YOURCHURCH**.tpsdb.com/SmallGroupFinder/Index/Main

This is also the link you will post on your website.
Be sure to replace **YOURCHURCH** with the name of your church as it appears in your TouchPoint
URL.
Also, if your XML file is named something other than **Main**,
be sure to use that in place of Main.

If you created multiple XML files in order to post
different finders on specific websites (such as Adults, Students)
you would name each XML file something different, but the name must still begin with ``SGF-`` and
have the ``.xml`` extension.

The name you use is the name that goes at the end of the URL.

.. note::
    The name that you use in the URL after /Index/,
    does not include ``SGF-`` nor ``.xml``.

|
|

+--------------------+------------------+
| **Latest Update**  | **06/21/2022**   |
+--------------------+------------------+

Added Caution text at end of Step 2.