miva merchant plug-in modules from viking coders ...if checked, the url of the standard miva...

http://www.vikingcoders.com

Search Manager This module gives you great control over your store’s Search screen. It provides more robust searching. The Concept... This module is configurable to allow customers to search by product, product attribute, and category, as well as additional fields if using our Additional Product Fields Manager. Note about compatibility with other modules: This module will integrate with our template modules, or with any other module that supports OpenTokens – the module’s functionality can be called into store pages using tokens. This module uses tokens. A primer on tokens can be found here. Installation Instructions are at the end of this document. Accessing the Module... After installing the module, click on the System Extension link in your Miva Merchant Admin, and click on the Search Manager link in the right-hand screen. This is where you will make all configurations for the module.

http://www.vikingcoders.com/docs/listings.html

Search Manager – Last Update 05/19/05

Setting Options When you first access the module’s admin, you will be presented the module’s standard Options screen.

Enable module? This option enables the Search Manager module. Left unchecked, your store will not utilize its features. Replace Standard Search? If checked, the URL of the standard Miva Merchant Search button will be routed to the new Search screen (to screen code SRCHM instead of SRCH.

Note: This does not “redirect” the page, so any hard-coded links to the search screen will need to be updated to go to Screen=SRCHM instead of Screen=SRCH.

Number of results to display: You can limit the number of results to display on the screen before the shopper has to click the Next or Previous buttons. After adding product: If you use the standard add buttons included by the module, you can send the customer back to the search page or to the basket screen when a product is added to the basket. Treat product’s w/attributes as separate items? This option will treat product attributes as actual line items in the search results.

Attribute code by which to separate: You can signify an attribute code to use as a separator for products. Search on default option only? You can also set the module to search only on the attribute’s default option.

Use template formatting? You can either use the standard layout and functionality the module provides, or opt to use template formatting so you can modify the layout and functionality. If you want total control over the search screen, check off template formatting.

Copyright 2005. All Rights Reserved.


Assigning Search Types You can dictate which search options are checked off by default when the shopper performs a search. Template formatting will allow you to actually remove options you don’t want used at all. Here, though, you will merely set the defaults. To set the defaults, just check them off. When using the Search Category feature, you have the option to search the header and footer, which can be very useful if you use HTML to further describe the contents of a category. The AND operator will run a search and display results when ALL keywords are in the product, category or attribute. Checking only Keywords will run a search and return results when something matches ANY of the terms. The Keywords option will search the keywords you may setup for Products. By default, category keywords are automatically searched.

Shoppers can select their search options. You have control over what is selected by default. It is recommended that Case Sensitive is not a default option.

Page Sections Show Category Tree? If you want to display the category tree on the search screen, check off this box. Page Title: You can enter a title for the page, which will display in the browser’s Title Bar.



Buttons and Graphics You can customize your own graphics for standard buttons used. The various buttons are Search, Next, Previous, Add to Basket, Add One to Basket, Buy One Now, Reset (resets the search form) and Sort. You can upload the graphic and use the alt text to insert an alt tag into the url for the button (so when a mouse is held over the button it tells the shopper what it does). If you don’t want to upload your own graphics, the alt fields will be used to display standard gray form submit buttons.

Logging Searches The module can log searches for the store, so you can later see what terms are being used. Generate Log File? To turn logging on, check off this box. Log file name: This is the path and name of the file. By default you’ll want the file written to the store’s Miva Data directory, commonly in the Merchant2/00000001/export directory. By default the file name is searches.dat. Export Template: This is the format in which the log file will be saved. By default the tokens %date%|%searchterms% are used to save the Date and the Search Terms. This template will export something like: 2003/06/19 12:00:00|bananas

2003/06/19 12:00:30|kumquat The following tokens can be used in the Export Template:

%date% displays the date and time %searchterms% displays the search terms %customer_id% displays the customer's id (not the code) if they are logged in %basket_id% displays the customer's basket id %session_id% displays the customer's session_id


Before They Can Search… Before ANY search results can be displayed, the module needs to build a database of all your products, categories, attributes, etc (basically anything that is searchable). Not performing this step will result in errors on the screen.

Rebuilding the Data Rebuilding the Product Data is vital for first time operation of the module. If you are wanting shopers to search on the product attributes and any Additional Product Fields (requires the Additional Product Fields Manager module) you need to check these boxes off. When rebuilding, you need to click the Rebuild Product Data link. The Update button will NOT rebuild the data. For Categories, you may also want to check off to rebuild the headers and footers and click the Rebuild Category Data link. Delete Data before rebuilding? If you’ve made a lot of changes to the store via importing, including removing products, you may want to delete the current data before rebuilding. Pack Databases: The Search Manager’s database files can be packed manually. To do this, check off the Pack Databases box and click Update.


How Often Should I Rebuild Data? Whenever you add products, categories, attributes, etc. to the store via the Miva Merchant admin, this data is automatically built in the database files. When you import data, however, it is not. So any time you import any of your data into your store, including when you use StoreMan or an import module, you need to rebuild the data in order for that content to be searched.


http://www.vikingcoders.com/go.mv?ID=DEN_PRODFIELDS


Working with Templates You can opt to use template formatting for the display of all parameters of the Search Screen. Default code is included to get you started.

Before modifying any of the templates, we recommend you copy and paste the code for each to text files, so you’ll have a backup copy to play with. We also recommend you view the front end of the store’s Search screen often so you can quickly catch any mistakes.

To work with the templates, click the Templates link in the Search Manager’s admin area.

Template Breakdowns The Search Screen templates are broken down so you can have control over each element. Each template area controls one specific element of the page. Here’s a breakdown of what each section controls. Main Template: This is the template for the overall screen. Other template areas are called into this screen via the use of pre-defined tokens. You can use HTML in this section. You can also code other custom HTML forms, but they must reside outside of the search form used in this template. Category Row Template: This area is called into the Main Template via the %catresults% token. If the %catresults% token is not in the Main Template, then the content of this template will not display on the screen. This template controls how the rows of categories will be displayed on the screen. You can modify this template to display three across by using table cells and modifying the result number. For example:

<tr> <td %bgcolor%>%catresult|01|%</td> <td %bgcolor%>%catresult|02|%</td> <td %bgcolor%>%catresult|03|%</td> </tr>

This would display three columns of results on the screen.

Category Template: This template controls how each category result appears on the screen. For example, if you wanted to precede each category name with a graphic, you could use something like this:

<img src="graphics/00000001/pointer.gif"> %catnameL%

This would display a pointer graphic, followed by a space, then the category name (hyperlinked to the actual category screen).



Product Row Template: This area is called into the Main Template via the %rows% token. If the %rows% token is not in the Main Template, then the content of this template will not display on the screen (i.e. no products will display at all, even if they are applicable to the search). This template controls how the rows of categories will be displayed on the screen. You can modify this template to display three across by using table cells and modifying the result number. For example:

<tr> <td %bgcolor%>%product|01|%</td> <td %bgcolor%>%product|02|%</td> <td %bgcolor%>%product|03|%</td> </tr>

This would display three columns of results on the screen.

Product Template: This controls how each product will display on the screen. You can use HTML and tokens to customize the display, provide a link for more details, and so on. Refer to the tokens listing and Customization Tips section for further assistance. Attributes Main Template: If you have opted to make product attributes searchable, then this template will call the attribute rows to appear on the screen. In order for this to work, you need the %attributes% token in the Product Template (above).

The only token necessary in this template itself is the %rows% token. Attributes Row Template: This template controls how the attribute rows appear on the screen. Attribute Templates: The following templates give you control over how each specific attribute type (select, radio, checkbox, etc.) will appear on the screen.



List Background Colors: You can specify the hex color (or use the color popup to select one) for the list displays (if you use them). These settings allow you to alternate colors in lists – similar to what’s done on Miva Merchant’s Product List screen.

Third-Party Modules You can assign Third-Party Modules to the Search Manager module. If you are familiar with our other template modules, then the instructions are the same. To assign a third-party module, click the Third-Party Tokens link.

This listing shows all of the modules that have been registered and their respective tokens. The tokens themselves can be changed and this will affect the "full token to use". The xx in the full token represents the "position" of the token. It tells the module to which the token position the token belongs. In some modules this position may be a number and in some others it may represent more descriptive text. The link in the "instructions" column will open a new window which displays any instructions provided by the module's developer to help in the placement of the tokens.

Information displayed when you click on the instructions button is dependent upon instructions registered by the developer. Should they be absent or incorrect, you’ll need to contact the developer of the module. Not all third-party modules support tokens, and registration of ones that do not will not make a difference. NOTE: Not all third-party modules can be called in with tokens. Modules must be coded a certain way, so you may need to check with the developer to see if the module can be called in this way. Alternatively, Search Manager does allow the usage of OpenTokens, so you could use module tokens registered with the OpenUI if you so desire. We recommend, however, to use the Third-party token registration whenever possible.

Locating the Module Code To locate the code of a module, do the following:

1. In your Miva Merchant admin, click the arrow next to Modules. 2. Locate the module in the listing and click it’s link.

3. Note the CODE that is listed in the right-hand screen. This is what you need to put in the Module

Code box on the Third-Party Tokens tab.



Placing Third-Party Tokens The most common third-party token used in Search Manager is from the Additional Products Fields Manager. You can register this module with Search Manager and place conditional calls or standard tokens where you wish in the Product Template. For example, if you have an additional field labeled ISBN, you could place the token %module|prodfields|ISBN|% in the product template area so you can display the ISBN in your search results.

Keywords When the Search Manager module is installed, new tab links for the module are placed in the edit Category and Product screens in the Miva Merchant admin. Using keywords is not required, but they can help when you need to include different search terms you don’t want appearing to the shoppers. To access the keywords area, go to edit any category or product in your admin, then click the Search Manager link on the right. When Searching… When a search is submitted, searching categories will automatically search the keywords. However, searches on products will only search the keywords fields if you have checked off Keywords as an option (or included in as a default option in the template formatting). The Format: You can enter any text you want in the keywords field, so if you want to add several terms separated by a delimiter (like the comma), you can. You can also include complete sentences, and use it more like a “backend, searchable description”. Here’s a trick, too. You can use delimiters to break your keywords field content it up into "phrases". So if you want the customer to be able to find the word "clown" and "nose" separately but NOT the phrase "clown nose", you could separate those terms with a delimiter such as: clown|nose. SEO: The keywords field is not the same as META Keywords, which are used for Search Engine Optimization. This field is searchable by this module, and does not affect any results shoppers may get for your site when using a search engine.

Note: There is currently no way to bulk import the keyword fields. Many users use a third-party module to import into the databases.





Additional Product Fields The Search Manager supports using additional product fields only with the Additional Product Fields Manager module. It will search, provide results and display the content of these fields.

The module will not search any custom product fields you may have created via the OpenUI Custom Product Fields feature, but you can use OpenTokens to display those fields.

If you are using this module, you’ll see an Additional Product Fields link in the module’s admin. Here you can decide which fields can be searched, and set any default “checked off” options. You can also, if using template formatting, control how the checkboxes and fields are displayed to the shopper. This template will display the fields if you have the %addfield% token in your Main Template. When you want to display content based on whether or not that field has something in it you could use the conditional token:

%begin_if|len('%module1|DEN_PRODFIELDS|field|%')|% it has something in it

%end_if%





Tokens This module uses tokens to display specific data. Following is a list of standard pre-defined tokens used for this module.

NOTE: These are not OpenTokens. They are tokens specific to the Viking Coders template modules and do not require special settings for normal display of information.

Tokens may be added to the module as needs arise. As they are added, this documentation will be updated. Note the date on this documentation to see if updated documentation is available.

Main Template The following tokens are supported for usage in the Main template area that corresponds to the outline of the Search Screen.

%beginform% ...

%endform%

These tokens denote the beginning and end of the main form needed by the module. All of the tokens in the following block must be located between these two tokens. You cannot place any html forms between these tags.

%searchbox|xx|% Displays the input field for the customer to enter search term(s). The xx will determine the width size of the field. For example, %searchbox|05|%.

%searchboxX|xx|% This token permits you to add additional search fields to the form. And each separate field will contain its own respective data when the page is refreshed. X denotes a number between 1 and 9 and xx is the field size. Eg. %searchbox1|22|%, %searchbox2|20|%, etc.

%searchbutton% Displays the search button. The button will use the "Image for 'Search' button" if one has been configured. Otherwise a standard form button will be displayed using the "alt for 'search' button" text.

The following 6 fields provide the customer with radio buttons that they can select to choose to sort the search results. The x can be either h, d, or a. If h is used, the field will be hidden and that sort method will be used. However, in that case you must be careful not to use multiple tokens which use 'h'. If d is used, then that option will be checked by default. If 'a' is used, that option will be unchecked.

%sort_nameup|x|% sorts by name alphabetically upwards

%sort_namedown|x|% sorts by name alphabetically downwards

%sort_codeup|x|% sorts by product code alphabetically upwards

%sort_codedown|x|% sorts by product code alphabetically downwards

%sort_idup|x|% sorts by product id numerically upwards

%sort_iddown|x|% sorts by product id numerically downwards



%sort% Displays button which will process the result sorting. The button will use the "Image for 'sort' button" if one has been configured. Otherwise a standard form button will be displayed using the "alt for 'sort' button" text.

%reset% Displays button which will "reset" the form (i.e. clear out the entered values without carrying a search). The button will use the "Image for 'reset' button" if one has been configured. Otherwise a standard form button will be displayed using the "alt for 'reset' button" text.

%begin_searchlist% ...

%end_searchlist%

The contents between these two tags will be used to display a drop down selection list from which the customer can select the term to search for. The format for the contents is: default value|term1|term2|term3|...|% The default value has NO search term and is merely used for display . If it is left out (but the first | must still be used) then the first term will be used as the default and the search will ALWAYS include a term from the dropdown list. Eg. the tokens: %begin_searchlist%select one|house|duplex|condominium|apartment% %end_searchlist% will produce the search box: Top of Form

house

Bottom of Form

%begin_searchlist#% …

%end_searchlist%

Here, the # represents a number from to 9. These tokens work exactly like the %begin_searchlist%...%end_searchlist% tokens above except that the term selected from the list will NOT appear in the search box after the search is submitted. In addition, the term selected will appear as 'selected' when the customer is returned to the search page after doing the search.

The following tokens will display the checkbox options to the customer so they can select whether or not to search that field. If you leave a token out of your template but for which you set the "Search option default" (on the main Options tab), then a hidden field will be added to the form and the search will take place as if that option had been selected

%ctgy_opt% the option to search the categories

%and_opt% the option to do the search using the AND boolean operator (i.e. the search will return only those results which contain all of the search terms). Otherwise, the OR operator is used (i.e. the search will return all results which include ANY of the search terms)

%keys_opt% the option to include the product key words in the search. The category key words are always searched when the categories are searched.

%case_opt% the option to make the search case sensitive

%phrase_opt% the option to search the entered terms as a phrase

%name_opt% the option to include the product name in the search

%code_opt% the option to include the product code in the search

%thumb_opt% the option to include the product path to the thumbnail in the search



%image_opt% the option to include the product path to the image in the search

%price_opt% the option to include the product price in the search

%desc_opt% the option to include the product description in the search

%weight_opt% the option to include the product weight in the search

%attrib_opt% the option to include the product attributes in the search

The following tokens are available when the Additional Fields Manager has been installed. Otherwise they will simply be removed and ignored.

%begin_addfields% …

%begin_addfields%

The contents between these two tags will be displayed only if the Additional Fields module is installed and you have given the customer the option to search one or more of those fields.

%addfields% Displays the list of fields from the Additional Fields Manager. The list is composed of a copy of the "Template for %addfield% listing" (bottom of the Additional Product Fields tab in the module's admin) for each additional field that you have given the customer the option to search

%addfieldoption|fieldcode|%

Displays a checkbox for the customer to choose whether or not to include the additional field added by the Additional Fields Manager. The field that the checkbox represents is determined by the "fieldcode" included in the tag. So, if you have an additional field with the code title, you would use the token %addfieldoption|title|% to display a checkbox to the customer so they can select whether or not to include that field in the search.

The begin_if form of tokens are all conditional and the contents between them are displayed ONLY if that condition is true. For example, the contents between the %begin_ifcats% and %end_ifcats% tokens is displayed ONLY if you have configured it so that the customer has the option to apply the search to the category OR you have denoted that option as default. Otherwise, the contents are not displayed.

%begin_ifcats% …

%end_ifcats%

The contents between these two tokens is displayed ONLY if you have configured it so that the customer has the option to apply the search to the category OR you have denoted that option as default.

%begin_ifcatresults% ...

%end_ifcatresults%

The contents between these two tokens will be displayed ONLY if the categories were included in the search and at least one category was found that matched the search criteria

%begin_ifnocatresults% …

%end_ifnocatresults% The contents between these two tokens will be displayed ONLY if NO categories were found which meet the criteria.

%begin_ifnoresults% …

%end_ifnoresults% The contents between these tokens will be displayed ONLY if the product search resulted in NO products being found.


http://vikingcoders.com/go.mv?ID=ADDFIELDS


%begin_ifresults% …

%end_ifresults% The contents between these tokens will be displayed ONLY if the product search results in at least one found product

%catresults% Displays the listing of found categories. It is replaced with a copy of the "Category row" template.

%rows% Displays sufficient copies of the Product row template to display the results (up to the configured number to display).

%results% Displays a copy of the Product template for each product found. Note: You cannot display the products in a tabular form with this token.

%sessionurl% Replaced with the Merchant variable g.Session_url

%session_id% Replaced with the Merchant variable g.Session_id

The following tokens are used to display a Previous button when the number of found products exceeded the number displayed and there was a previous page of results.

%begin_previousform% ..

%end_previousform%

The contents between these two tokens will be displayed if there is previous page of results. They denote the beginning and ending of a form so no html form can be provided between these tokens and they cannot overlap with the %begin_nextform%/%end_nextform% or %endform% tokens.

%previous% Displays a button which will send the customer back one page of results. The button will use the "Image for 'previous' button" if one has been configured. Otherwise a standard form button will be displayed using the "alt for 'previous' button" text.

%begin_nextform% …

%end_nextform%

The contents between these two tokens will be displayed if there is a next page of results. They denote the beginning and ending of a form so no html form can be provided between these tokens and they cannot overlap with the %begin_previousform%/%end_previousform% or %endform% tokens.

%next% Replaced with a button which will send the customer forwards one page of results. The button will use the "Image for 'next' button" if one has been configured. Otherwise a standard form button will be displayed using the "alt for 'next' button" text.

The following tokens will be replaced with the face, color, and size of the fonts configured within Merchant admin for the header and body. These can be used to match the search page to the remainder of your store. They include the full element of the tag. For example, the token %hdrfontcolor% will be replaced with COLOR="fontcolor".

%hdrfontcolor% replaced with COLOR="headercolor"

%hdrfontface% replaced with FACE="headerface"

%bdyfontface% replaced with FACE="bodyface"

%bdyfontsize% replaced with SIZE="bodysize"



The following tokens can be used to control the background color of table cells. In each case they are replaced with the string: bgcolor="color"

%hdrcolor% replaced with the parameter for color where the color used is the table background color as configured in Merchant admin for the header.

%bgcolor1% replaced with the parameter for the color configured in the module's admin(bottom of the "Template" tab for List Background for color#1.

%bgcolor2% replaced with the parameter for the color configured in the module's admin(bottom of the "Template" tab for List Background for color#2.

Category Row Template These tokens are supported in the Category Row Template.

%sessionurl% replaced with the Merchant variable g.Session_url

%session_id% replaced with the Merchant variable g.Session_id

%bgcolor1% replaced with the "Background color #1"

%bgcolor2% replaced with the "Background color #2

%bgcolor% alternately replaced with the "Background color #1" and "Background color #2"

%catresult|xx|%

To replace the %catresults% token in the Main template, the module takes a copy of the Category row template and populates the %catresult|01|% position with the first category, then the %catresult|02|% position with the second category, etc. until there are no more positions in that row. It then displays that row and starts over with a new copy of the Category row template. Again, replacing the %category|01|% token with the next consecutive category, etc.



Category Template These tokens can be used in the Category Template area.

%catname% category name

%catnameL% category name linked to intitial category page

%catcode% code

%catcodeL% code linked to initial category page

%category|field|% can be used to directly display the categories.dbf "field". For example, %category|code|% will display the category code.

%store|field|% can be used to directly display the stores.dbf "field". For example, %store|name|% will display the store name.

%enccategory|field|% can be used to directly display the categories.dbf "field". However, all characters will be converted to their HTML entity equivalents. Useful for using the category data in a URL. For example, %enccategory|code|% will display the category code.

%encstore|field|% can be used to directly display the categories.dbf "field". However, all characters will be converted to their HTML entity equivalents. Useful for using the category data in a URL. For example, %category|code|% will display the category code.

%cattreeimage% category tree image

%cattreeimageL% tree image linked to initial category page

%ctgy_hdr% category header (as configured in standard admin)

%ctgy_ftr% category footer (as configured in standard admin)

%cattitleimageL% category title image linked to initial category page

%cattitleimage% category title image






Product Row Template






%product|xx|%

To replace the %results% token in the Main template, the module takes a copy of the Product row template and populates the %product|01|% position with the first product, then the %product|02|% position with the second product, etc. until there are no more positions in that row. It then displays that row and starts over with a new copy of the Product row template. Again, replacing the %product|01|% token with the next consecutive product, etc.

Product Template

%prodname% Product name

%prodcode% Product code

%prodnameL% Product name, hyperlinked to the product’s page.

%prodcodeL% Product code, hyperlinked to the product’s page.

%prodprice% Product price

%prodcost% Product cost

%prodweight% Product weight

%proddesc% Product description

%prodimage% Product’s large image

%prodthumb% Products thumbnail image

%prodimageL% Product’s large image, hyperlinked to the product’s page.

%prodthumbL% Product’s thumbnail image, hyperlinked to the product’s page.



%stocklevelcode% The products inventory level code.

%stockmessage% The product’s inventory stock level message.

%stocklevel% The product’s inventory stock level.

%prodqtybox|xxx|% An HTML field box to collect the quantity to add to the basket. The xx is the minimum quantity to display in the field. Note however, that the customer can change this to be any quantity they want (including lower than the initial value)

%prodadd% A button to add the quantity to the basket. Replaced with the "Add to Basket image" if configured. Otherwise replaced with Merchant's "Add to basket" image

%prodaddone% A button to add the quantity to the basket. Replaced with the "Add 1 to Basket image" if configured. Otherwise replaced with Merchant's "Add 1 to basket" image

%prodbuyone% A button to add the quantity to the basket and take the customer to checkout. Replaced with the "Buy one now image" if configured. Otherwise replaced with Merchant's "Buy one now" image








Attribute Templates

Tokens usable in the Main Attributes template

%rows% Replaced with the HTML for the Attribute row template

Tokens usable in the Attribute row template

%attribute|xx|%

To replace the %rows% token in the Attributes main template, the module takes a copy of the Attribute row template and populates the %attribute|01|% position with the first attribute, then the %attribute|02|% position with the second attribute, etc. until there are no more positions in that row. It then displays that row and starts over with a new copy of the Attributes row template. Again, replacing the %attribute|01|% token with the next consecutive attribute, etc.

Tokens usable in the individual Attribute type templates

%prompt% replaced with the Attribute prompt

%options% used only in Radio attr. template: replaced with the HTML for the Radio option template

%fields% replaced with that attribute type's HTML field

%attrprice% the attribute price

%attrcost% the attribute cost

%attrimage% the attribute image



Static Search Forms You can add a static search form to your store. Many users like putting a search form in the category tree or in a right column, or even in the navigation bar. This is useful when shoppers will commonly use the search tool.

Adding a Standard Form To add a "static" search form to your store you can use HTML form tags. This is similar to the static search form used for the standard Miva Merchant search screen.

<FORM METHOD = "post" ACTION ="http://www.yourstore.com/Merchant2/merchant.mvc?> <INPUT TYPE = "hidden" NAME = "Store_Code" VALUE = "storecode"\> <INPUT TYPE = "hidden" NAME = "Screen" VALUE = "SRCHM"> <INPUT TYPE="hidden" NAME="Search_desc" VALUE="0"> <INPUT TYPE="hidden" NAME="Search_name" VALUE="1"> <INPUT TYPE = "hidden" NAME = "BrokSearch_Have_List_Fields" VALUE="1"> <b>Search for:</b><INPUT TYPE="text" NAME="Search_search" SIZE="15" VALUE=""> <input type="image" name="submit"> </FORM>

This form will search the description and name by default. Note: If you are running Miva Merchant version 4.13 or lower, the first line should read:

<FORM METHOD = "post" ACTION ="http://www.yourstore.com/Merchant2/merchant.mvc?> The "Search_desc" and "Search_name" variables represent the search options (i.e. search description and search name). A value of 1 means that field will be searched. There are other fields you can also use, and their code is self-explanatory: Search_attrib Search_weight Search_desc Search_price Search_image Search_thumb Search_code Search_name Search_phrase Search_case Search_keys Search_whole Search_and Search_ctgy



Searching on Additional Fields To search the fields of the Additional Products Fields Manager, you need to use the Field ID of the field as it is listed on the Additional Product Fields link in the Search Manager admin. This is not the code or the prompt that you created, but an actual number. If you click the Additional Product Fields link in Search Manager, you’ll see a listing of any additional fields you created. The list will look like:

1. Author 2. Publisher 3. ISBN

Thus, if we wanted to search the Author field, we would include the following in our search form: <input type="hidden" name="SearchAdd_1" value="1">

Restricting Categories You can restrict which categories are searched by using a simple input field: <input type="hidden" name="CategoryRestrict" value="cat1"> In this example, cat1 needs to be the Category CODE, and including this field will tell the module to ONLY search this particular category for results. To restrict a search to multiple categories, separate each category code with a comma: <input type="hidden" name="CategoryRestrict" value="cat1,cat2"> If you want to give the customer the option of restricting the search, you could use checkboxes. Here’s an example: <input type="checkbox" name="CategoryRestrict" value="cat1"> Category 1 <input type="checkbox" name="CategoryRestrict" value="cat2"> Category 2 Note: When you restrict a search to a single category, it will find only products in that category and will NOT find products in sub-categories of that category. You can however, restrict the search to multiple categories by concatenating the category codes together. So if you want the search to find the products in FRUIT and all products in sub-categories of FRUIT, say APPLES and PEARS, you would need to restrict the search to the sub-categories as well. For example, a search of this form will find "juicy" in the name and description of products in those three subcategories: http://yourstore.com/Merchant2/merchant.mvc?Store_Code=code&Screen=SRCHM&Search_name=1&Search_desc=1&CategoryRestrict=FRUIT,APPLE,PEAR&HF=1&Search_Search=juicy




Creating Search URLs It is also possible to provide a URL/Link which contains the terms to be searched. Here’s an example. http://www.yourstore.com/Merchant2/merchant.mvc?Store_Code=storecode&Screen=SRCHM&Search_name=1&HF=1&Search_Search=dog As with the search form, the Search_name=1 means that the name field would be searched. You could add other fields by adding those to the url: http://www.yourstore.com/Merchant2/merchant.mvc?Store_Code=storecode&Screen=SRCHM&Search_name=1&Search_desc=1&HF=1&Search_Search=dog If you want to search a term with spaces in it you need to replace the spaces with the +. So to search dog catcher you would have Search_Search=dog+catcher It is actually possible to shorten the URL/form but it gets a little more complex. The search options are passed to the page in the variable SearchOptions, which is a "binary" representation of the options. So if ALL options had been selected by the customer it would look like 11111111111111. If only the AND option had been selected, then it would look like 00000000000010. The positions, left to right, are: Search_attrib position 1 Search_weight position 2 Search_desc position 3 Search_price position 4 Search_image position 5 Search_thumb position 6 Search_code position 7 Search_name position 8 Search_phrase position 9 Search_case position 10 Search_keys position 11 Search_whole position 12 Search_and position 13 Search_ctgy position 14 So to search the name and description you would have the URL: http://www.yourstore.com/Merchant2/merchant.mv?Store_Code=storecode&Screen=SRCHM&SearchOptions=00100001000000&HF=1&Search_Search=dog Similarly, there is a "binary" string for the Additional Fields (if used): AddOptions (eg. AddOptions=1101). In this case the positions, left to right, represent the id's So if you want to automatically search field ids 1 and 4, you would have AddOptions=1001. If you do not have a field with a particular id (eg. if you didn't ahve a field id 3), simply represent that field w/ a 0. So to search Additional Fields 1 and 2 your URL would become: http://www.yourstore.com/Merchant2/merchant.mv?Store_Code=S&Screen=SRCHM&SearchOptions=00100001000000&HF=1&AddOptions=11&Search_Search=dog This may seem longer than the original URL but that URL only searched the name field and this is as long as the URL will get regardless of the number of options you want to include.



Troubleshooting Search Manager

Runtime Error A common mistake by users is not building the data for first time usage of the module’s search functionality. This will commonly display an error on the screen that resembles this: Runtime error in /…/4.24/modules/system/BROK_SEARCH.mvc @ [00000071:000000ea]: Line XXXX: MvDELETE: Runtime error in /…/4.24/modules/system/BROK_SEARCH.mvc @ [0000006e:0000066e]: Line 8516: MvDELETE: It’s important to make sure you build the databases when you enable the module for the first time.

No Search Results If no search results are returned, here’s a few things to look for.

1. Make sure the databases have been built. If you’ve done this previously and only some products are not returning, then rebuild the data.

2. Make sure you don’t have an option configured that is restricting the results. For example, if you

have the case sensitive option as a configured options, results may not be returned properly. Some users mistakenly code search forms and urls without including the proper strings, such as searching the product description.

3. The module will not distinguish between whole and partial words. This means if you search on the

word “red” the module will find and display results containing the words “bred”, “red” and even “predilection”. I have the module configured but the search does not appear to be returning the correct search results. Any ideas?

4. The module cannot distinguish the difference of plural and singular forms. Searching on the word

“book” will return results of the word “books,” but searching on the word “books” will NOT return “book.”

5. Try packing the module’s databases. This is done in the module’s admin under the Rebuild Data

tab.

Searching Additional Fields If Additional Fields are not being searched (because the results aren’t correct), the first thing to try is rebuilding the database fields, making sure that you have the "Rebuild Additional Fields Data" option checked off before your click on "Rebuild Product Data". Also, if you're using the "template formatting" option, make sure that you have the %addfields% token in the template, inside of the %beginform%...%endform% tokens. Even if you are not giving the customer the option to select which of the additional fields to search in, it is still required that the token %addfields% be in the template so that the hidden fields which tell the module which fields to search in are included.



Rebuilding Data Errors Question: When I attempt rebuild my databases (on the "rebuild data" tab) I get an error that the file can't be found. Is this caused by the way I have Merchant set up? My merchant.mvc file is in my script root: http://mydomain.com/merchant.mvc and my module root is /Merchant2/ The problem is definitely the way you have your Merchant directories set up. The module attempts to figure out the direct pat to itself by taking the path to merchant.mvc: http://mydomain.com/merchant.mvc Then cropping off the executable: http://mydomain.com It then adds to this the Merchant version, eg. /4.12/ and the path to the module so it ends up with the path: http://mydomain.com/4.12/modules/system/BROK_SEARCH.mvc In a normal Miva Merchant store, the version subdirectory is in the same directory as the excecutable so it works. In this case it obviously does not. Unfortunately, there’s no way to modify the module to generically account for this particular setup of Miva Merchant. So you will need to either put a copy of the module where Merchant is looking for it: http://mydomain.com/4.12/modules/system/BROK_SEARCH.mvc or modify the module file (only an option in Merchant versions 4.13 and lower) by adding the line: <MvASSIGN NAME="l.thisscript" VALUE="http://mydomain.com/Merchant2/4.12/modules/system/BROK_SEARCH.mv"> immediately before the line in the "ThisScript"function: <MvFUNCRETURN VALUE="{l.thisscript}"> So it would look like: <MvASSIGN NAME="l.thisscript" VALUE="http://mydomain.com/Merchant2/4.12/modules/system/BROK_SEARCH.mv"> <MvFUNCRETURN VALUE="{l.thisscript}">


Customization Tips Though it looks simplified, Search Manager is a very robust, highly configurable module. This section discusses advanced techniques for customizing the module’s layout and functionality. It’s recommended that you become familiar with the core concepts of this module by understanding the prior sections of this documentation. This will give you a better “edge” on performing advanced tasks.

Excluding Products If you have certain products in the store you don’t want appearing in any search results, you can use the  tag in any portion of the product’s description field. This will keep the product from displaying in any search results. You can also exclude products in certain categories from appearing in results. This is similar to restricting results to specific categories. To do this, you’ll need to use tokens, which are placed in the Main Template:

%catexclude|hidden|catcode|% will exclude from the search results products in the category with the category code "catcode". To exclude products from more than one category, list multiple category codes for the catcode, separating each by commas (eg. catcode1,catcode2,catcode3). In the alternative, you can have a separate token for each category that you want to restrict the search to. %catexclude|checkbox|catcode|% will offer the customer the option to exclude products from the category with "catcode". Multiples of this token can be used to present multiple checkboxes and the customer can select more than one. %catexclude|radio|catcode|% will offer the customer the option to exclude products from the category with this catcode. However, the option will be displayed as a radio button. If you use multiple of this type of token, they customer will be able to choose only one category to exclude. %begin_catexclude% <Select one>|catcode1|catcode2|catcode3| %end_catexclude% will display a drop down selection list from which the customer can choose a category to exclude from the search. The content between the %begin_catexclude% and %end_catexclude% are used to create the drop down list. The first item in that list is the "select one" option and choose it will have NO affect on the search. If you do not want to have a "select one" option simply begin the list with the delimiter |.


Searching By Price Ranges This module can search for prices within a particular price range. To add this capability to the module, you need to use the "Use template formatting?" option (on the "options" tab). Within the form in the "Main template" area (i.e. between the %beginform% and %endform%) you can place the token: %pricerange1|xx|% to display a search field, xx characters long, to collect the bottom of the range. Similarly, you use the token: %pricerange2|xx|% to display a search field, xx characters long, to collect the top of the range. The module will then restrict the search to only those products which have a price between the value entered into the two fields (actually, it will return all products which have a price equal to or greater than the value in %pricerange1|xx|% and lower than or equal to the value in %pricerange2|xx|%. If no value is entered into the %pricerange2|xx|% field, then the search will return all products with a price higher or equal to the value entered into the %pricerange1|xx|% field. The module will also take into account the other options and any search term entered into the search field. So if you enter "banana" into the search field and a price range of 0 to 30, the module would find only products in the price range from 0 to 30 AND with "banana" in the searched fields. However, it is not necessary that some value be in the search field (eg. not necessary that the form variable Search_search have a value). If not search term is entered, the module will return all active products in that price range. By way of example, to offer your customers the ability to restrict the results to products with a price only within a particular range, you could add the following to your "main template" between the %beginform% and %endform% tokens:

Prices from: %pricerange1|3|% to %pricerange2|03|% It's also possible to offer the price range capability by adding form fields directly to the template. You can use the variables, Search_pricerange1 and Search_pricerange2, to collect the data for the lower and upper price ranges, respectively. For example:

<input type="text" name="Search_pricerange1" value=""> <input type="text" name="Search_pricerange2" value="">

You can also use the variable, Search_pricerange (i.e. without the 1 or 2 suffix), which must have a value in the form "lower price:upper price". This is for use in Select type lists and radio buttons. For example, to offer the ability to select price ranges from a select list, you could add to the "main template" (again between the %beginform% and %endform% token) the html:

<select name="Search_pricerange"> <option value="0:10">$0 to $10</option> <option value="10:20">$10 to $20</option> <option value="20:30">$20 to $30</option> <option value="30:">over $30</option> </select>

NOTE: The price used is the value in the Products database for the product; it does NOT take into account discount for price groups, etc.



Attribute Pricing: If you’re products have a $0.00 price (because you’re handling pricing by product attributes) you can set the module to search by the price of the attributes. To do this, you need to make sure you’ve checked off the option to treat product/attribute combinations as separately searched items. The price of each of these searched items is the product price + the attribute price. With this option enabled, you can search by price range and the product will show up in the results if the total price (product + attribute) of one of its attributes falls in the range. A note about the treat product/attributes option—it can do this for only a single attribute (but each of that attribute's options will be a separate item). To designate which of the product attributes is to be used to separate there is a field "Attribute code by which to separate". Enter the attribute code of the attribute in that field (note that with this approach if you have multiple products which you want to "separate" by an attribute, the products have to have the same attribute code for it to work). The third option is "Search on 'default' only". With this option enabled, instead of separating the attribute into a separate item for each of its' attributes, it creates only a single item using the attributes default option. For example, if you have an attribute "size" which has 3 options, small, medium, and large, each with it's own price 10, 20, and 30, you could enable the "Treat product w/ attribute as separate items" option, enter "size" into the "Attribute code by which to separate" field and the Search Manager would treat the product as 3 different items w/ three different "prices": small $10 medium $20 large $30 So if you provide the option to search by price range, the product would show up in all price ranges into which one of these prices falls.

Sorting Results Automatically The module, by default, allows the customer to choose how the results can be sorted. However, you can also set a default sorting method. The following tokens can be used.

%sort_nameup|x|% %sort_namedown|x|% %sort_codeup|x|% %sort_codedown|x|% %sort_priceup|x|% %sort_pricedown|x|%

To sort products by the same order they are sorted in your Miva Merchant admin, you can use the tokens:

%sort_orderup|x|% %sort_orderdown|x|%

In the sorting tokens, the x can be either h, d, or a. If h is used, the field will be hidden and that sort method will be used. However, in that case you must be careful not to use multiple tokens which use 'h'. If d is used, then that option will be checked by default. If 'a' is used, that option will be unchecked.



If you want to set sorting in a static search form, use the tag: <input type="hidden" name="BrokSearch_sort" VALUE="name|up"> This one will sort by name upwards. You can extrapolate the other values by the type and direction. For example, to sort by code downwards, you would use: <input type="hidden" name="BrokSearch_sort" VALUE="name|down"> The other values are: name|up sorts by name alphabetically upwards name|down sorts by name alphabetically downwards code|up sorts by product code alphabetically upwards code|down sorts by product code alphabetically downwards id|up sorts by product id numerically upwards id|down sorts by product id numerically downwards order|up sorts by admin order upwards order|down sorts by admin order downwards

Suppressing the Search Form You may want to suppress the search form on the results page. What you can do is place: %begin_if|(NOT g.Suppress) OR NOT len(g.Search_search)|%....%end_if% around the search form (i.e. around the %beginform%...%endform% and between the %beginform% and %endform% add the hidden field: <input type="hidden" name="Suppress" value="1"> This will hide the search form if the page is displaying results.

To suppress a static form you may have creating in the category tree or navigation bar, you would need to use OpenTokens to set a conditional to not display the form when on the SRCHM screen.

Out-of-Stock Products If you’re using Miva Merchant’s Inventory Feature, you can control how out of stock items display by using the %begin_outstock%...%end_outstock% tokens. These display content between the two tokens only if the product is out of stock. Then use %begin_instock%...%end_instock% to display content if the product is IN stock.. To totally suppress the display of the product if it is not in stock, put %begin_instock% at the beginning of the "Product template" and put %end_instock% at the very end of the "Product Template".


Displaying Numbered Results While Search Manager will not provide paging (like in the Category Page Templates module) you can display the number of results and the range the shopper is viewing. This option requires that you have the "use template formatting" option set "on". With that option you can add tokens to the template to display what you're after. The tokens: %displaystart% (displays the "count" of the first product displayed) %displayend% (displays the "count" of the last product displayed) can be used to display the: "Items 1-20" as "Items %displaystart%-%displayend% The token %totalproducts% displays the total number of products in the results and the token %totalpages% displays the total number of pages of results.

Checkbox Search Terms You can use check boxes to allows shoppers to quickly add or use search terms. For example, if you use: <input type="checkbox" name="Search_search" value="apple"> Apple <input type="checkbox" name="Search_search" value="orange"> Orange <input type="chedkbox" name="Seach_search" value="banana"> Banana The shopper could check off the “apple” box and the search results will return anything with the word apple in the searched fields. This can be done even if nothing is entered into the search term. One reason you might use this is if you use a special code in product descriptions to denote a type of product. Using checkboxes like this can help narrow down the results.

Using Drop-Down Select Menus Using menus can help make the search task easier on the shopper, and there are different things you can do. Controlling the AND flag: It is possible to create an html drop-down that allows the user to determine the state of the AND flag. First, in the template, surround the %and_opt% token with comment tags:

 Then code something like this:

<select name="Search_and"><option value="1">All of the words</option><option value="0">At least one of the words</select>


Additional Product Fields: If you want to preset a list so shoppers can choose values to search for in additional fields, you can use a <select> form. For example, if you have additional fields for color and size, you may want to restrict searching to allow them to locate items only available in Large Red. Assuming that Color has an ID of 1 and Size has an ID of 2, you would code lists like this:

<select name="SearchAdd_1"> <option value="">Any</option> <option value="red">Red</opton> <option value="blue">Blue</option> </select> <select name="SearchAdd_2"> <option value="">Any</option> <option value="small">Small</opton> <option value="large">Large</option> </select>

Conditional Displays You can conditionally display text in the search results. %begin_if|g.Variable EQ 1|% This text displays only if the Variable is 1 %end_if% Similarly, you can display text if the Variable is NOT 1 with: %begin_notif|g.Variable EQ 1|% This text displays only if the Variable is NOT 1 %end_notif% of course this can also be done with the %begin_if| token: %begin_if|NOT (g.Variable EQ 1)|% This text displays only if the Variable is 1 %end_if% So, for example, if you wanted to display content only if a product’s weight was set at 3, you would use:

%begin_if|Products.d.weight EQ 3|% This product has a weight of 3! %end_if%



Removing Link Variables Three tokens have been created so you can provide “simplified” links that won’t include additional variables (like Category_code=) in the urls when linking to product pages from search results. %prodnameSL% %prodcodeSL% %prodthumbSL% These can replace the %prodnameL%, %prodcodeL%, and %prodthumbL% tokens.

Integration with Search Friendly Links Many Miva Merchant users utilize the Search Friendly Links module. Though these methods are not supported (as the SFL module is by another developer), the following has been provided by JMH Web Services (http://www.jmhonline.net). Can I manually construct search links with the search friendly links from Copernicus including with additional product fields manager and price ranges? The following are examples that can be used. Be sure to replace /storecode/ with your store code! 1. Search Screen - <a href="/page/storecode/SRCHM">Search Products</a> 2. Search Name Field – <a href="/page/storecode/SRCHM/Search_name/1/HF/1/Search_Search/jackets">Search for Jackets</a> (This searches for Jackets. If you want to search for more than one word, include a plus sign + /Search_Search/jackets+sweaters) 3. Search Name and Description – <a href="/page/storecode/SRCHM/Search_name/1/Search_desc/1/HF/1/Search_Search/jackets">Search for Jackets</a> 4. Search an Additional Product Field – <a href="/page/storecode/SRCHM/HF/1/AddOptions/1/Search_Search/brown">Brown Clothes</a> 5. Search Name Field and a Price Range of $5 dollars or less - <a href="/page/storecode/SRCHM/Search_name/1/HF/1/Search_Search/jackets/Search_pricerange/0:5">Search for Jackets $5 or less</a> You can add as many options as needed. Use the above examples as a template. It goes /some variable/some value. Is it possible to use search friendly links from Copernicus with Search Manager results including additional product fields manager? The following are examples that can be used. Be sure to include %OUI% at the VERY beginning of any field that you use with this code! 1. In the Templates / Category Template area, use this code for the category name link: <a href="%VAR(module|CBSSFL|ctgy_URL_d)%">%catname%</a>



Installing Search Manager

1. In the Miva Merchant Admin Menu, click the next to Modules. 2. Click Add Module.

3. Use the upload button to upload the BROK_SEARCH.mvc (or .mv if running MM version 4.13 or

lower) to the store.

4. Once uploaded, click the Add button.

5. Click the next to your store’s link.

6. Click the System Extension link.

7. In the right-hand screen, check off the box next to Search Manager and click Update.

8. At the top of the screen, click the Search Manager link.

9. Enter your license key and agree to the terms.

10. Click Update.

Updating/Upgrading Search Manager From time to time updates may be made to fix issues or add more features. To see if there are updates available for this module, you can click the upgrades link in the module’s admin at any time. If one is available, you can download the file and follow the instructions on updating the module.

Obtaining Support Standard support for this module is offered free of charge via the Support Desk. Standard support covers initial installation issues, confliction issues and standard usage of the module. Some issues may be considered advanced, such as requests that require custom coding or configuration. Services are offered for this type of support or work. Please inquire. Before contacting support, please double-check your settings against this document, and visit the Module’s FAQ section.


http://www.vikingcoders.com/helpdesk/faq.php?parent=143

miva merchant plug-in modules from viking coders ...if checked, the url of the standard miva...

Documents