Wikibooks

Umbraco/Samples and Articles/Implementing Search

< Umbraco | Samples and Articles
This page may need to be reviewed for quality.
edit

Introduction

edit

This article describes how to implement a basic content search in Umbraco.

Please send any comments or corrections to df at darren hyphen ferguson dot com.

Pre-Requisites

edit

You should have some experience of creating Umbraco Templates and Document types.

You will need to download the following files:

Umbraco Utilities: http://old.umbraco.org/frontpage/download/extensions/umbracoutilities.aspx [file no longer exists]

Umbraco XSLT Search: http://www.learningmill.org/bonus/umbraco/SearchResults%201.0%20with%20XSLT.zip [file no longer exists - visit http://old.umbraco.org/frontpage/download/extensions/umbracoutilities/umbsearchresult.aspx for instructions][file no longer exists]

Finally, you'll need some pages in Umbraco. Obviously, if you don't have anything to search, you won't have any results!

Install Umbraco utilities

edit

Rename the Umbraco utilities zip file that you downloaded and rename it as umbracoUtilities.umb (Windows sometimes automatically adds a .zip extension)

Log in to your Umbraco installation as a user that has access to the Developer tab.

Right click on the 'Macros' Icon in the 'Developer' pane and click 'Import package'.


 


In the resulting popup window use the 'Browse' button to locate umbracoUtilities.umb and then click the 'Load Package' button.


 


On the following screen you will need to check the 'Accept License' checkbox and click the 'Install Package' button.


 


Assuming that all goes well you will be presented with a confirmation screen telling you that Umbraco utilities was successfully installed.

You will be prompted to populate the Search index which you should do.

Creating a search form document type and template

edit

In order to search Umbraco content you will need a form that makes an http post of a search term. The form input containing this search term should be named 'search' and is typically an HTML input element with it's attribute type set to text.

You may include your form in a master template, or navigation XSLT file, but for the purpose of this turorial we will assume that the search form resides within it's own template.

Click on 'Settings' in the Umbraco dashboard. in the 'Settings' pane on the left hand side right click 'Document Types' and then click 'Create'.


 


In the resulting popup window type 'Search Form' (or whatever you like) into the 'Name' text field and check the 'Create matching template' checkbox. Click the 'Create' button.


 


If you are familiar with Umbraco you may want to add some Tabs and Properties to your new Document Type at this point. If you are relatively new, don't worry, you can always come back and do this later.

In the 'Settings' pane on the left hand side of the Umbraco GUI click on the plus icon to the left of the 'Templates' folder to expand the list of templates. Locate and click on the 'Search Form' template that you created in the previous step of this example.


 


Paste the following into the 'Template' textarea: 

<html>
	<head>
		<title>Search Umbraco</title>
	</head>
	<body>
		<form method="get" action="/result.aspx">
			<input type="text" name="search"/>
			<input type="submit" value="Submit"/>
		</form>
	</body>
</html>

Click the 'Save' icon (which looks like a floppy disk).

This is really basic web dev stuff, no trickery here. If you feel the need to add CSS classes, Javascript validation or anything else here, feel free. The only thing that you may need to modify is the form action. The action /result.aspx specified above assumes that you are able to create a page at the root of your umbraco content tree. Don't panic if you can't. I will mention how to replace this URL later.

Creating the search page

edit

Click on the 'Content' icon in the Umbraco dash board. Right click on the Top level content node in the 'Content' pane on the left hand side of the Umbraco GUI. Click 'Create'.


 


In the resulting 'Create Page' popup select the 'Search Form' Document type that you created in the previous step using the 'Choose Document Type' drop down. In the name text field type 'Search' and then click the create button.


 


Note: if you don't see your Document type in the list of options then there are obviously issues with how you have set up the structure of Document types within Umbraco. Resolving this problem is outside of the scope of this tutorial, but is quite simple to resolve and the fine folks on the Yahoo mailing list will no doubt set you straight within minutes.

We are starting to get somewhere now. You will see that the Search node has appeared in the 'Content' pane on the left hand side of the Umbraco GUI. You will see that it is greyed out, so click on the 'Save and publish' icon (a globe and a floppy disk combined).


 


Note: It's a cosmetic issue, but you may not want your Search page icon to be a folder. You probably know how to change this, but if not it's back to the mailing list again.

We've nearly got this section wrapped up, but let's just check that our Search page works ok. Due to a small bug in Umbraco, you'll notice that the 'Link to document' in the right hand frame of the GUI still says 'This item is not published'. To remedy this, click on your search page in the left hand 'Content' pane and the 'Link to document' should change to say '/search.aspx'.

Click on the 'Link to document' URL and you should see something like this:

File:Searchform.jpg

Ok, it isn't very pretty, but we are well on our way.

Creating a Search results document type and template

edit

We created a document type and template for the search form and the basic steps for creating your Results document type and template are exactly the same. I'm not going to repeat all the diagrams here, so if you struggle, just use the step by step diagrams and instructions in the previous section.

In the settings section of Umbraco Create a document type called 'Search Result' with a matching template.

In the 'Content' section of Umbraco Create a page of type 'Search Result' called 'Result'. Save and publish the page. Click on the page in the left hand 'Content' pane so that you can see it's URL which confirms that it has been published (remember when i mentioned that you may want to change the form action? Well this is the url you need).

Now we have a search form that submits to a page that will show the search results. It's time for the final step. Adding the search functionality.

Adding search functionality

edit

Creating the search XSLT

edit

In the Umbraco 'Sections' Pane, click on 'Developer'. In the 'Developer' pane on the left hand side of the GUI right click 'XSLT Files' and click 'Create'.


 


In the resulting popup window Check the 'Create Macro' checkbox and type 'SearchResult' in the Filename text box. Click the 'Create' button. Note: You can leave the 'Choose a template' drop down as it is because we will be updating the newly created file in the next step.

Extract 'SearchResults 1.0 with XSLT.zip' to your local PC. Using your favourite text editor copy the contents of 'SearchResults.xslt' to your clipboard.

In Umbraco click on the SearchResult.xslt file that you have just just created in the 'Developer' pane on the left hand side of the GUI. Paste the contents of your clipboard into 'Source' textarea replacing the existing contents.


File:Pastexsl.jpg


Click on the save icon (that looks like a floppy disk).

Note: There will be plenty of time to customise this XSL later, this tutorial just focuses on getting a basic search working.

Setting up the search Macro

edit

In the 'Developer' pane on the left hand side of the Umbraco GUI expand the list of Marcos by clicking on the plus icon next to the 'Macros' folder. Locate the Macro that you created in the previous step (X S L T Search Result) and click on it.


File:Selectmacro.jpg


Note: I am unsure why Umbraco adds the spacing into 'X S L T Search Result' but it doesn't matter.

Click on the 'Parameters' tab and enter the following parameters for your Macro. 

ALIAS          NAME                           TYPE
------------   ----------------------------   ------------
source         Source                         contentTree
search         Search String                  text
maxPerPage     Results to display per page    number
searchFields   Umbraco fieldnames to search   text
page           Page Number                    text

You should end up with a screen that looks like this:


 


Ensure that you save the changes by clicking on the save icon (that looks like a floppy disc).

Insert the Macro into the Search Result Template

edit

Let's go back and edit our 'Search Result' template. In case you'd forgotten, you click on 'Settings' in the Umbraco 'Sections' pane and it's in the Templates folder.

Right now, it should be empty, so lets put some skeleton HTML in. Just paste the following into the 'Template' textarea: 

<html>
        <head>
                <title>Search Umbraco</title>
        </head>
        <body>
               
        </body>
</html>

Place your cursor in the textarea between the open and closing body HTML tags. Click on the 'Insert Macro' button (the icon look like two angled HTML tag brackets, you will get a tooltip when you rollover the button the confirm it is the right one.


File:Beforemacro.jpg


In the resulting popup window choose 'X S L T Search Result' from the drop down list and click 'OK'.


 


The following screen asks for some values for the Macro parameters. These demand a little explanation.


File:Macroparamsb.jpg


By clicking on 'Choose Item' next to the Source parameter you can browse Umbraco's content tree and specify a node under which the search should be performed. I have tried, but I can't seem to get this working from the root node. Maybe someone out there knows how?

The value '[@search]' in the 'Search string' field tells us that the search term is going to be supplied as an part of the HTTP request (remember the text input called 'search' that we created in the form right at the beginning of the tutorial?).

'Result to display per page' is exactly what it says. Just make sure that you specify a number. I've used 10 for this example.

'Umbraco fieldnames to search' is again fairly self explanatory, but you will have to supply field names that are relevant to your own Umbraco installation. You can specify as many fields as you like as a comma delimited list.

'Page Number' has the value '[@page]' which means that it will be part of the http request. The XSLT file we installed earlier takes care of paging through results, so you don't need to do anything special.

Click the OK button, and notice how Umbraco has inserted a Macro tag into our template.

The final But VERY IMPORTANT step is to surround the Marco tag with Umbracos 'ASPNET_FORM' tag so it looks like this: 

<?ASPNET_FORM>
<?UMBRACO_MACRO macroAlias="XSLTSearchResult" source="-1" search="[@search]" maxPerPage ="10" searchFields="Keywords,Description" page="[@page]"></?UMBRACO_MACRO>
</?ASPNET_FORM>

Thats it! Make sure that you save the changes to your template by clicking the save (floppy disc) icon.

edit

Browse back to the search page you created and have a go. If it doesn't work, then please let me know what I missed out in the article.

Conclusion

edit

I hope you found this helpful.

Articles like this only evolve, if those who read it send me updates, errors, bugfixes and so on, or as this is a Wiki, just update as you see fit.

Retrieved from "https://en.wikibooks.org/wiki/Umbraco/Samples_and_Articles/Implementing_Search"