Creating and Using Custom Form Fields in your Jamroom

One of the exciting new features of Jamroom 3.1 is the ability to configure Custom Form fields for use throughout your Jamroom.  This allows you an almost limitless number of options to store additional information for the "items" in Jamroom.  For example, if you want to collect information about a Song's "Producer", you could create a custom form field for "song_producer", and Jamroom will collect, store and allow you to manipulate the data stored in that field in many different ways - including Ranking and Searching.  The options for the Custom Form fields are really limitless, and with some imagination can be put to almost any use.

Configuration

Using the Custom Form Fields is fairly simple and straight-forward - there is no installation or activation needed, as the Custom Form Field function is part of the Jamroom Core.  To access the Custom Form Field section, simply:

• Log in to your Jamroom as the Master Admin
• Click on the "Jamroom Config" option in the Master Admin menu.
• Click on the "Custom Form Fields" option located at the bottom of the selection list.

Once in the Custom Form Fields section, you will be presented with a list of choices.  These choices determine the "item" type that the Custom Form Field will be added to.  As an example, if you wanted to add a field for "Song Producer" to your Jamroom Song Create/Modify form, you would select the "Song Form" option from your available choices.  Since we've used "song_producer" a couple of times now as our example, that's what we'll stick with moving forward through this guide, and show you how to add and use this new field to your Jamroom.

Creating the Custom Form Field

Once you have clicked on the "Song Form" option, you will see a new form that shows any existing Custom Form Fields that have alreayd been created - if this is your first time in the Custom FIeld config for the "Song Form", you will only see the form for creating a new entry.  Using the idea of adding a "Song Producer" as a new song field, we would then do the following:

• Enter "song_producer" (without the quotes) into the "TITLE" field.
• Leave the "TYPE" field set at "Input Field" (the default).
• Click on "Save Changes" to create the new custom form field.

Once saved, your screen will refresh, and you will now see some additional information available that pertains to the new field you have just created.  This includes:

• "SEARCH_AREA" - this shows how the field would be named when used as a "search_area" to the Jamroom Ranking System.
• "THEME and RANKING" - this shows the variable that would be used in Jamroom Profile Theme templates, and Jamroom Ranking System templates.
• "DISPLAY NAME" - this shows the corresponding "title" that has been defined in the Jamroom Language file (this may or may not be set).

This information is helpful to allow you to use this custom form field in other aspects of your Jamroom - from allowing your visitors to "search" the new field, to allowing the custom fields to be used on your member Profile Pages.

Naming Custom Form Fields

By default, when you create a new Custom Form Field, Jamroom will simply show the name of the new form field created.  However, Jamroom does support a "descriptive name" as well as a "help" text area that you can add in for your Custom Form Fields.  You will notice that when you create a new For Field, that Jamroom shows you a "display" output that may look like this:

undefined in language file:


$language['band_test1']


$language['band_test1_help']

What this means when it says "undefined", is that you have not created a custom display title and help field in your jamroom/language/english.lang.php file (or whatever language file you are using).  What you would do is add the lines that Jamroom is showing you - i.e.

$language['band_test1'] = 'This is the Title';
$language['band_test1_help'] = "This is the help text that can give the user some additional information about the purpose of the field';

to the the bottom of your language file (make sure and change the "band_test1" and "band_test1_help" strings to match what your custom field is named).

Note that the lines must be valid PHP or you will get a BLANK SCREEN in Jamroom when you try to view the Control Panel.