Building a Website with MODx for Newbies- Part 10: Adding Search Functionality Using ajaxSearch
Welcome to part 10 of our series of tutorials on building a website with MODx CMS. So far we’ve looked at:
Part 1: Introduction to MODx
Part 2: Installing MODx
Part 3: Working with Templates
Part 4: Introducing Chunks
Part 5: Introducing Snippets
Part 6: Introducing Template Variables
Part 7: Introducing Ditto
Part 8: More Ditto
Part 9: Adding a Contact Form with eForm
So far things are looking good on our Learn MODx website, and we’re adding more functionality and hopefully building our skills with each of these tutorials. My hope is that by this point you’ve developed enough of an idea of the way MODx works that you’re moving on and exploring on your own, building and testing, and hopefully you know some things that I don’t about MODx and it’s workings 🙂 So far our website looks like this:
One of the things I find myself looking for in every website I visit is a search box or link. Whether the website is a massive knowledge portal such as Wikipedia, or a social networking site, a blog, or just a simple company website, having the ability to search the website and find the information I need without clicking through numerous links is very important to me. It then follows that I would like to add search functionality to the websites I build. This what we’re going to accomplish in this segment.
To add search functionality to our MODx website, I have opted to use the ajaxSearch snippet (version 1.8.1).
This is one of the snippets that you can opt to install when installing MODx, but if you find you don’t have it in your snippets folder, you can download it from the MODx repository and install it using the instructions at MuddyDogPaws.com, the website of the snippet’s creator Kyle Jaebker.
The first thing to do is decide where to place my search box. I have opted for the top of the right sidebar. Like all other snippets, ajaxSearch takes some parameters, and once you read through the documentation, you can see all the parameters and experiment with them.
Let’s start off by opening our right sidebar chunk (swansong_rightsidebar) for editing, and inside the div tag, right above the news updates section, create a search heading:
Under this, we’re now going to call the ajaxSearch snippet. If you look at the documentation, the given example has several parameters included. I’m going to break it down and start with few parameters, testing as I go, and then add parameters as needed.
My basic snippet call looks like this:
If we now save the chunk and look at our page, you can see the change:
The &ajaxSearch parameter is to enable or disable the ajax functionality. It’s default value is 1 (enabled). Test your search now and you’ll see your results. You can style them to look how you want them to by modifying some files as specified in the documentation. This is beyond the scope of the current tutorial but I plan to cover it in a later tutorial. Once you read up on this snippet, you’ll see all the different things you can do with the ajaxSearch snippet. For now, I just want to get basic search functionality working.
You can set this snippet up for ajax search or non-ajax search. For my purposes, I would like to use the non-ajax option, and want the search results to open in a new page. To make this happen, I will change the value of the &ajaxSearch parameter to 0 to disable it. This also means that I need to create a new document for the results appear in, and then point the snippet to that page.
So let’s do it! 🙂
Go ahead and create a new document and call it Search Results, and set it to the SwansongHome template (or whatever template you’re using). Turn off the rich text editor (you can do this by opening the Page Settings tab for the document and unchecking the Rich Text? box). Save the document and make sure it’s published. Also uncheck the Show in Menu box because we don’t want this page to show up in the menu. Note the ID of the new document. Mine is 12.
We’re now going to make some changes to our snippet call in the right sidebar chunk.
[!AjaxSearch? &ajaxSearch=`0` &AS_showResults=`0` &AS_landing=`12`!]
Let’s explain the parameters used here:
- As explained before, by setting &ajaxSearch=`0` we’ve disabled the ajax functionality.
- &AS_showResults=`0` – this sets it so that the results don’t show up with the snippet on the sidebar since I’m going to show them on the results page we created. The reason I have to specify this is that &AS_showResults has a default value of 1 (enabled)
- &AS_landing=`12` – specifies what page I want the search results to show up on. In my case it’s document ID 12, the search results page I created
The next thing we need to do is open the search result document we created and place the snippet call on that page also. Remember that you should have tinyMCE turned off. In the content area of the Search Results page, place the snippet call as shown below:
[!AjaxSearch? &ajaxSearch=`0` &AS_showResults=`1` &AS_showForm=`0`!]
First thing you’ll notice is the difference in the parameter value for &AS_showResults which is now set to &AS_showResults=`1`. This is because I now want the results to show on this page. I have also added a new parameter &AS_showForm and set its value to zero. The reason for this is that &AS_showForm tells the snippet whether to show the search form with the results. It has a default value of 1 (enabled) which means that the results page will appear with two search forms. Since I don’t want that, I have to specify that I want to disable it on the results page.
If we now test our search functionality, we should see some results. Here is a screenshot of my results after entering “php” in my search form:
There are several other parameters that we can use.
- From the documentation you can see the non-Ajax search will return only 10 results per page by default, but we can change that by setting &grabMax to a value higher than 10.
- If using the ajax version, the default max is 5 results per page, but you can change that using the &ajaxMax parameter.
- You can also &showMoreResults and &moreResultsPage parameters with the ajax search to show more results.
You can read about all these parameters in the links at the end of this post.
One more parameter setting I want to use here, since I’m using non-Ajax search, is the &showPagingAlways parameters. What this does is set the pagination option if the total number of your results exceed your max setting. You can use this parameter in two cases: when you’re using non-ajax search or ajax result with the &showMoreResults parameter set to `1` and a moreResultsPage specified.
So in my search results page, I will now add this parameter to my snippet call:
[!AjaxSearch? &ajaxSearch=`0` &AS_showResults=`1` &AS_showForm=`0` &showPagingAlways=`1`!]
Just for purposes of testing this parameter, I will temporarily set my &grabMax parameter to 3 and then search for php again.
As you can see now, since my search returns 4 results, I now have 2 pages of results with the pagination at the top and bottom of the page allowing me to navigate from page to page.
There’s a lot more to explore with the ajaxSearch snippet and we will address it again in the future, but for now we’ve moved a step further and have search functionality working at the Learn MODx website. At this point, our website now has a lot of the standard functionality that you expect from an ordinary website, and I believe that in the process we’ve learned a lot of the MODx basics.
I encourage you to explore and experiment with the ajaxSearch snippet and share your insights and questions with all of us. And as always, comments, corrections, and questions are always welcome 🙂
And don’t forget to grab your copy of the MODx Web Development book!
ajaxSearch Snippet – http://modxcms.com/extras.html?view=package/view&package=8
ajaxSearch homepage – http://www.muddydogpaws.com/development/ajaxsearch/features.html
ajaxSearch Support Forum – http://modxcms.com/forums/index.php/board,320.0.html
ajaxSearch Demo Site – http://www.modx.wangba.fr/index.php?id=51