The Jamroom Search is a script that is part of the Jamroom Bonus Pack, that gives you a way to develop a custom “search engine” for your Jamroom site. It also offers a convenient front-end for use within your Jamroom (by the Master Admin as well as your Jamroom Artists). The core of the Jamroom Search is the “newsearch.php” script, with support template files located in the jamroom/templates/newsearch directory (after installation of the Jamroom Bonus Pack).

After installation, you will find the “newsearch.php” script is located in the root of your Jamroom directory, (i.e. jamroom/newsearch.php) and a full set of “default” templates wil be located in the jamroom/templates/newsearch directory.

There are 2 locations within Jamroom that contain configuration settings that affect te behavior of the Jamroom Search:

Quota Configuration
Within the Create Quota and Modify Quota form sections (Located in the Admin Menu), there is an option called “Allow Search”. If this is set to “no” for a Quota, then Artists that are part of that Quota will NOT show up in the search results. This setting is often used on Jamroom sites that charge for Artist Hosting, and may want to set this to “no” for their free sites they offer. Set to “yes” to enable searching for Artists that are part of the quota.

Jamroom Config
Within the Jamroom Config (Admin Menu → Jamroom Config), there is a setting called “Search Highlight Color”. This is the Default Highlight Color that Jamroom will use to “highlight” the search results. This color can be overidden on the URL with the “hilite_color” option (see URL variable options below).

There are several ways that the Jamroom Search can be used:

Within the Artist Menu
When you install the Jamroom Bonus Pack, you will notice that a new “search” button becomes available under the “options” section of the Admin Menu. Clicking on this will present you with the Search Menu on the right, where you can select the area of search as well as enter a search string. This gives the Admin a handy way of quickly searching through your Jamroom for anything you would like to see.

Using Jamroom’s built in Menu
Probably the easiest way to add a search form to your site, is to simply place a URL link to the newsearch.php, and let Jamroom handle generating the form interface that your visitors will use to search your Jamroom. For example, you could place an HTML anchor tag into your homepage like this:

<a href="jamroom/newsearch.php?mode=menu">Click Here to Search Jamroom!</a>

And this would create a link to the newsearch.php script that would generate a form interface for your visitors to use. Note the “?mode=menu” part MUST be there or the form won’t work. You can also pass in an (optional) “user_style” CSS sheet from Jamroom that you would like the form interface to be rendered with - i.e.

<a href="jamroom/newsearch.php?mode=menu&user_style=Jamroom_Blue.css">Click Here to Search Jamroom!</a>

Note that the user_style passed in MUST be a valid Admin Skin located in jamroom/styles. If no user_style option is passed in, the System Default Admin Skin is used to render the form interface.

From a Custom Form
One of the other ways of using the newsearch.php, is to embed it into your own custom search form. For example, lets say on the front page of your site you wanted a “quick search” box that would allow visitors to your site to quickly find an artist by Artist Name. In the HTML for your front page, you could place a small bit of code like this:

<form method="post" action="newsearch.php" enctype="multipart/form-data">
<input type="hidden" name="mode" value="retrieve">
<input type="hidden" name="search_area" value="artist_name">
<input type="hidden" name="header_template" value="your_custom_header.tpl">
<input type="hidden" name="row_template" value="your_custom_row.tpl">
<input type="hidden" name="footer_template" value="your_custom_footer.tpl">
<input type="hidden" name="error_template" value="your_custom_error.tpl">
<input type="text" name="search_string" value="">
<input type="submit" value="search">
</form>

And this would create a small search “form” that would send the text string that someone is searching for to the “newsearch.php” script for processing. The results would then be displayed using the templates you have defined in the “hidden” fields of the form. Note You can also pass any of the “hidden” variables in directly on the URL (i.e. “&header_template=your_custom_header.tpl”).

The Jamroom search supports 2 “modes” of operation:

1. menu
2. retrieve

menu
When the Jamroom Search script is called with the “menu” mode, it tells the newsearch.php script to generate the Form Menu, which allows the user to select the Search Area and enter a Search String to search for. This is the Default mode for the newsearch.php script - that is, if no mode option is given to the newsearch.php script, it will default to showing the Form Menu. Example:

<a href="jamroom/newsearch.php?mode=menu">Click Here to Search Jamroom!</a>

retrieve
The retrieve mode is the mode that is passed in to the newsearch.php script when you want to bypass the Form Menu, and go directly to displaying the results of a search. Example:

<a href="jamroom/newsearch.php?mode=retrieve&search_area=artist_name&search_string=sample">
Click Here to Display all artists with <b>sample</b> in their name!
</a>

Of course limiting your search results to only Artist Names that contain the word “sample” is not likely what you are looking to do, but it shows how the retrieve mode is used to bypass the Form Menu interface.

There are many different options (variables) that can be “passed in” to the newsearch.php script when it is called. This gives you great flexibilty over how the results of your search are displayed. The following URL variables are supported by the newsearch.php script:

URL Variable	Description
mode=(menu/retrieve)	the mode variable tells the newsearch.php which “mode” to operate in. If given the menu mode option, the Form Menu is displayed for the user to select the Search Area and Enter the Search string. If the retrieve mode is given, the Form Menu is bypassed and the script proceeds directly to displaying the results. Make sure when using the retrieve mode that you pass in a search_area and search_string or the script won’t know what to do!
user_style=(style.css)	(optional) This variable, when used in conjunction with the menu mode, tells the newsearch.php script to render the Form Menu with the style.css Jamroom Admin Skin style sheet (located in jamroom/styles). Note that the user_style must refer to a valid CSS file - i.e. “Jamroom_Blue.css”
header_template=(header.tpl)	(optional) This variable tells the newsearch.php script to render the results using this template as the “header” template. Note that the header template will be render FIRST, before any of the “rows” of matching results are displayed. If no header_template option is defined, no header is rendered.
row_template=(row.tpl)	(optional) This variable tells the newsearch.php script to render the results using the given row.tpl as the “row” template. The “row” template is the most important template in displaying your search results - it is how each “row” of results is displayed to the user. If no row_template option is defined, the “default” row template will be used based on the search_area. 1).
footer_template=(footer.tpl)	(optional) This variable tells the newsearch.php script to render the results using this template as the “footer” template. Note that the footer template will be rendered LAST, after any of the “rows” of matching results (and possibly header) are displayed. If no footer_template option is defined, no footer is rendered.
error_template=(error.tpl)	(optional) This variable tells the newsearch.php script to use the given error.tpl to render any errors that may come from the new search that are based on the User Input - i.e. “Your Search did not return any results!”. If no error_template option is provided, the default Jamroom “Error” screen is shown for errors.
hilite_color=(FFFFFF)	(optional) This 6 digit Hexadecimal color code (i.e. HTML color code) can be defined and tells the newsearch.php to use the hilite_color2) to “highlight” the search results. Note that if no hilite_color is defined, the newsearch.php will use the value of the “Search Highlight Color” from the Jamroom Config. Check out Visibone Webmaster's Color Lab for a good selection of web safe colors.
pagebreak=(number)	(optional) This variable tells the newsearch.php to create a pagebreak after every number of entries that are displayed in the search results. If a valid numerical value is not received, no pagebreak is used.
pagenum=(number)	(optional) This variable tells the newsearch.php which page of results to render. This option only makes sense if used in conjunction with the pagebreak option. If no pagenum option is defined, page 1 is assumed.
search_area=(area)	(required) If you are using the retrieve& mode, the search_area is required or else the newsearch.php script doesn’t know where to search. Valid options for the newsearch.php are: all_artist (search artist areas) artist_name band_name band_members band_location band_influence band_soundlike all_song (search song areas) song_name song_label song_credit song_album genre_name all_user (search user areas) user_nickname user_fullname all_radio (search radio areas) radio_name radio_description all_item (search item areas) item_name item_description item_email item_number all_event (search event areas) event_title event_description event_location all_image (search all artist photo gallery areas)* image_title* image_credits* image_caption* image_category* all_video (search video areas)* video_name* video_credits* video_caption* *(requires Jamroom Power Pack)
search_string=(string)	(required) This variable tells the newsearch.php what to search for in the Jamroom database (in the given search_area). Note that the string is not case sensitive. This variable is required if using the retrieve mode, otherwise you will get a search error that no search string was provided.
show=(number)	(optional) the show variable tells the newsearch.php to stop outputting results rows after number of results have been displayed. This prevents a very long list of search results from being displayed if someone searches for a very common string.
rewrite=(yes)	(optional) This variable is used to tell the newsearch.php script that if only a SINGLE results is matched by the search_string, and the search_area is “artist_name” or “band_name”, then instead of showing the user the results as displayed by the newsearch.php, the user is forwarded directly to the Artist Page for the artist that matches the search. This is commonly used by the Jamroom “Friendly URL‘s” in conjunction with Apache mod_rewrite.
order_by=(order_column)	(optional) This option allows you to “sort” the output of the search results based on a specific column name that was used as part of the SQL for the search.
order_direction=(ASC/DESC)	(optional) This allows you to define the DIRECTION of the sort that can be passed in via the order_by column. Valid values are ASC (ascending - numbers will be arranged lowest to highest and alphabet characters will be alphabetized from A-Z) or DESC (descending) which is the opposite of ASC.

The templates that are used by newsearch.php are Smarty templates, and allow for a great degree of customization.

You will find ALL of the templates that the newsearch.php script uses inside the jamroom/templates/newsearch directory. Note that since you must pass in the name of the template file(s) you want to use in your newsearch.php output, its possible to create a common set of “header” and “footer” template files that can be used over and over again. If you have already created a custom header and footer template for another Jamroom Script (such as the Jamroom Ranking System), you can copy those templates in to your jamroom/templates/newsearch folder and use them there as well ³⁾.

• Template Variables available in ALL template files
• Template Variables available in ARTIST template files
• Template Variables available in SONG template files
• Template Variables available in USER template files
• Template Variables available in STORE template files
• Template Variables available in RADIO template files
• Template Variables available in CALENDAR template files

These optional variables can be passed into the newsearch.php script using the “order_by=” option (see above) and allow you to customize the ordering of the results that are returned by the newsearch.php script.

• Optional SORT orders for use in ARTIST Search Areas
• Optional SORT orders for use in SONG Search Areas
• Optional SORT orders for use in USER Search Areas
• Optional SORT orders for use in STORE Search Areas
• Optional SORT orders for use in RADIO Search Areas
• Optional SORT orders for use in CALENDAR Search Areas