Support archive

Pimp the docs with examples

lehrerfreund 2 Nov 2012 13:24 question, complete

Hi,

I am EE-User from the first hour on, running a bigger site with numberless other add-ons, can do some php-coding etc.
I just bought Low Search and I really have big problems understanding how it works. To be honest: There is no other plugin where I had such problems understanding the concept.

For me it would be very helpful if there were some examples, like e.g. GWcode does ( http://gwcode.com/add-ons/gwcode-cate... ). let's say examples like setting up a search form where all/some categories are selectable als ceckboxes.

Also I have serious problems understanding the concept of "collections", although I worked on the docs 10 times. Is a collection only the selection of one channel? Why is there the possibility to make more collections for one channel?! Also an example would be very helpful here.

I also would appreciate a link to a page where there are some code-examples.

Don't take it personal, I believe that you again have produced a great add-on - everybody's telling that. But I myself have big problems diving in.

Replies

1. Low 2 Nov 2012 13:47

   No worries, ask away. I am planning on doing a couple of blog posts about Low Search. For now, I'll try and explain collections first.
   
   Collections are used to create an index of the entries in that collection. For keyword searches, the index is searched, not the actual entries themselves. Apart from selecting the Channel in a collection, you also set the weight for searchable fields in that channel, thus making certain fields "more important" than others.
   
   Channels and Collections have a one-to-many relationship. So, you can create multiple collections for a single channel. This is particularly useful for multi-lingual setups, where there are fields like, for example, "body EN" and "body ES". Native search would search all of those fields. With Low Search, you could create 2 collections for that channel, one which only applies weight to EN fields, and one for ES fields.
   
   In theory, you could take this further, creating a collection for Titles only, etc. Usually though, one collection per channel would suffice.
   
   Then, categories. Remember, what we're doing in a search like that, is effectively just setting the category="" parameter for the Entries tag. If you want to set that up with checkboxes in the search form, use something like this:
   
   

   <input type="checkbox" name="category[]" value="1"> 
    <input type="checkbox" name="category[]" value="2"> 
    <input type="checkbox" name="category[]" value="3">

   
   
   If you check all boxes, it will be as though you've set category="1|2|3". If you add the parameter require_all="category" to the search form, it will be as though you've set category="1&2&3".
   
   I'll look into adding a dedicated examples page to the docs. I can see how that's helpful.

2. lehrerfreund 2 Nov 2012 15:48

   Thanks for your fast reply, Low! This makes some things clearer. Perhaps I'll have to ask some other things, I will open a new thread then.
   
   Just one question to the categories right now: If I want to choose between some categories and all, how is this done? Look at the following code, here are 2 categories to select between. I want to add a third radio-Button for "all categories" to be searched. Do you have any idea how to realize this?
   
   

    
    {exp:low_search:form collection="lehrerfreund" search_mode="all" result_page="schule/sucheLowErgebnis" loose_ends="yes" encode="no" query=""} 
      <fieldset> 
        <label for="keywords">Keywords</label> 
        <input type="search" name="keywords" id="keywords" /> 
    <p>Suche eingrenzen auf</p> 
    {exp:channel:categories channel="lehrerfreund" cache="yes" refresh="60" disable="category_fields" show="1|2"} 
   
    <input type = "radio" name = "category[]" 
                     id = "{category_name}" 
                     value = "{category_id}" 
                     checked = "checked" /> 
              <label for = "{category_name}">{category_name}</label> 
    {/exp:channel:categories} 
        <button type="submit">suchen</button> 
      </fieldset> 
    {/exp:low_search:form} 
    

3. Low 2 Nov 2012 15:55

   Just think what you'd put into the parameter if you wanted to show all categories: you'd leave it out. Or an empty value. That's how you do this as well.
   
   Also, since you're using radiobuttons (which only returns 1 value) and not checkboxes (which return multiple), you can use the name "category" (without square brackets). So this is what you'd get, simplified, including the {if ... IN ()} conditional to remember the chosen category:
   
   

   <input type="radio" name="category" value="" /> 
    {exp:channel:categories} 
      <input type="radio" name="category" value="{category_id}" 
      {if category_id IN ({low_search_category})}checked="checked"{/if} /> 
    {/exp:channel:categories}

4. lehrerfreund 2 Nov 2012 22:59

   Thanks, this is the perfect solution. I still don't understand when to use name="category[]" (als you did above) and when to use Name="category" (as you did in your last example).
   questions over questions :-)

5. Low 3 Nov 2012 11:02

   That has to do with the way HTML forms are sent to the back-end. An input name with name="foo" is sent as a single string, while name="foo[]" is sent as an array of multiple values. Perhaps this helps: http://php.net/manual/en/faq.html.php...

6. lehrerfreund 3 Nov 2012 20:33

   In the case above - do I have to use the array or not? When I use radiobuttons I always submit only one value?!

7. Low 4 Nov 2012 12:49

   Exactly, radiobuttons only return a single value, so not using an array is fine.
   
   The most obvious use of an array is a multiple select field, eg.
   
   

   <select name="category[]" multiple="multiple"> 
      <option value="1">Category 1</option> 
      <option value="2">Category 2</option> 
      <option value="3">Category 3</option> 
    </select>

   
   
   Here, the name of the input field is only defined once. If you would define it as name="category", only the last selected value will be posted. If you define it as above (an array), all selected values will be posted.
   
   Same goes for checkboxes with the same name: only the last selected value will be posted, unless you name it "some_name[]".

8. lehrerfreund 4 Nov 2012 12:52

   Thanks for the explanation, now everything (?!) is clear to me!
   (my case solved)