Hello Friends,
Its been >15 days i did not publish the next chapter as i was traveling on the weekends, but i wanted to make sure i release Part-4 today.
Previously we talked about high-level over view of coveo and what are the building blocks of it and what are some of the most important steps we should know before starting on coveo, As i said earlier as coveo has huge documentation and its a big sea of functionalities, but my purpose is to cover a crash course topics and how easily you can get started with coveo.
So i am thrilled today as i want to cover the hands on where we will create a search page from scratch and we will see what configurations are involved in that process and how indexing is being done and how ultimately data is being shown on the page from coveo index.
Search Page Requirement : I will be creating a simple search page for candidates, so consider a business scenario where i have a huge pool of records in my database where candidates are stored (Probably in Sitecore), now as a hiring manager i want to build a search engine where i can easily search candidates, apply different search filters, view their details.
Now having said above, If we want to start with the fundamental first, We will need following things
1) Item Template : We will need an item template for candidate where all the possible fields that we want to include or show on page will be there, Basically this is the template for which we intent to index the data as well as want to filter out this template in coveo rule editor.
2) Coveo Index and Field Configuration : As in previous parts we saw what are the essentials and what are important configurations of coveo, so now first thing what we will do is we will make our fields indexable in coveo index
NOTE: in my previous parts i have covered how to set up coveo for your organizations and what will be the farm name and where the index data will go etc. i will use my existing farm which i have created called "D-Farm" in which i am planning to index my data
Now to add specific fields to coveo index configurations, we will go to "Coveo Indexing Manager" from Sitecore's control panel like below
Once we are into Indexing manager, you will see your master and web coveo indexes, we will not touch them or rebuild them right now, we will just click on "Fields" option and will make sure our template's fields are also marked as indexable here, see following screen
Configure our template's fields to be indexable
Click on "Fields" and it will list all the available template, we can filter our specific template by searching that into the search box as shown below, and it will list all the fields of the template, we should tick mark those fields which we want to index.
Now after selecting fields, click "Apply and restart", this will update the "Coveo.SearchProvider.Fields.Custom.config" file in our wwwroot\<<Site>>\App_Config\Coveo folder
NOTE: This file is responsible to tell coveo indexer which fields to index, and you should check this file in source control, because you will want to send this file in the deployment so these settings are readily available in higher environments and you do not need to do above process on other higher environments.
3) Now once we are satisfied with the configuration, we can now create Sitecore item using our template, so we can index those data, so i will skip that part here, as those are standard Sitecore items created from our candidate template.
4) Now before we assemble anything on the page, we should first make sure that our data is getting indexed and our coveo configurations etc. are just in place, there are couple of ways to do it
- We can use our Sitecore's indexing manager where all the indexes are listed and we can index data into different indexes from there, here we will find our coveo_master_index and coveo_web_index, we could trigger indexing from this screen
- We can go to control panel and coveo indexing manager and from there we can rebuild the indexes which will ultimately build the indexes
- We can right click on the parent node of our Sitecore item and select option, "Re-index tree" from developer toolbar
5) Now We can go to
Coveo Cloud , It will prompt you to login with different options, your organization or you individual need to have license for this to login, in my initial posts i have explained how to register etc.
Here i am considering you already have your organization set up and your farm set up, in my case its "D-Farm", i will go and login into portal and will try to search our data in index to make sure if they are available in index or not
As you can see above i am able to see that my data are now indexed and i can now start on the front end part to assemble coveo components as data are indexed, one more thing also need to check if all fields are indexed or not, you can click on the search result to go into the record and see all the fields which were indexed.
NOTE: If you do not see your records indexed, you might need to see logs and troubleshoot which is a different topic, which we will cover in future post, but you can use coveo's health check functionality like below to see if coveo is working fine
Clicking on "Diagnostic" will show you all the very details where you can see if things are fine or you need further troubleshooting.
Show time: Now, consider that your data is rightly available in coveo and now you are all set to assemble the components on to the page, very first step is to install the coveo package (In my previous blog post
Part-2 i have shown what are the components that ships and gets installed in the package and how can you create different coveo items from it.)
So please refer to previous post PART-2 to know how we can get access to coveo components and their templates and functionalities, so we can start assembling them, also if you read my
Part-1 which mentions what are the mandatory components to get started, so now let's start assembling the components
Creating a Search Page and assembling of components
As i said earlier in one of my post that there is a documentation available from coveo about following best practices or things to consider before you start, if you have not yet seen
Part-3 , find that
PDF link here, to read more about what coveo recommends.
Now i will straight away move towards practical implementation of how to assemble coveo components.
Choosing a layout for displaying results
Coveo provides its default view to render the results, but in almost 99% cases in real project, there will be a need where you will need your custom design and custom HTML you want to display for results
For example in my project, my need was to show the results like 3 cards in one row, and it should show 12 cards on the page by default, meaning 4 rows of 3 cards each and there will be see more button a user can click and see other results by clicking "See more" button and it will again load another 12 cards.
Let me show you the layout i was intending to build (Though the amazing design was already given to us, by designers, we now needed to convert them into working HTML). Just to give you more idea, i am putting the wireframe down below
As you can see the page is intended to have these two columns, on left you can see facets, We will talk about facets in coming future post, and on right hand side you can see 12 cards, each card will show details of a candidate, and on see more there will be lazy loading of another 12 cards, on top we have sorting via which we can sort results.
Now, we are interested only in right hand side today in this post, We will be creating our own custom html and tell coveo to use our custom HTML instead of its default html to render the cards.
To full fill above need, we will need to assemble few coveo component on our page and configure them so that they read from our index as well as show our custom HTML too.
We will be talking about three most important components here to achieve the right hand side part
1) Coveo Search Resources
- We already have talked about this component in
Part-1, but to give you highlights, this is a mandatory component for any coveo search page and it is needed so that it can load coveo specific JS and CSS, You can read more on my Part-1 or on coveo documentation.
2) Coveo Search Interface
- This is the main component that we will need to use, remember i talked about writing a rule specific to our candidate template to read and display only candidate specific records out of the full index (index can have data of multiple template but we only want to show candidate data.), this is the component which gives us the ability to write rule and filter results from the index before displaying in the browser.
Also When you add this component on the page few other components will automatically be added onto the page like "Automatic boosting", "Query Filter", "Query Ranking" etc. we will not talk about them here, you can read more on coveo documentation online.
3) Coveo Results List
Responsible for displaying results, It provides configuration to select two layouts Card and List, There is also a possibility of giving user a choice to select between those two. (using Coveo Result Layout component).
4) Coveo Results Template
Coveo provides two out of the box templates types, As i said above in the post, if you want to have control over the html and the structure how the results are displayed, this is the component provides that, Both of below template enables "Underscore.js" syntax.
This is physical file based template, meaning we can create our own HTML file and put it on specific folder and later on tell coveo to use that template, we will see that soon.
This is data source driven template, so it needs the html script to be in the data source from where the component can pick what structure to display.
Phew !!! Hope things are clear till now, Now its time to assemble those component from experience editor and connect them with index as well as configure result template and other things, basically we should have the page up and running with us after the blog post.
NOTE: Remember coveo provides its own placeholders when different components are dragged-dropped, in my case i will be adding other containers and column splitters etc. too in those placeholder just to make sure i get the desire out put using import/export of that page and our FEDs can style it and i can import it back into my Sitecore.
Assembling components
Ok, now i will just create an item where i want to use as my search page, and assemble all those components, because i am using SXA, i already have a partial design which my context page item is using, so i will assemble those on the page design
Very first thing i will do is i will create a partial design where i can put all my components, and i will put all the mandatory components first which are Coveo Search Resources, Coveo Search Interface, Coveo Search Result List
As i have said once you add coveo components, it gives its own placeholders where you can put other components.
As you can see in above image, i am just putting this component in "main" placeholder of our partial design
Next, step is to add other components like below
Another component i would like to put is "Coveo Search Interface", you can see in the backdrop of the image, coveo search resource is also there and after that we will add "Coveo Search Interface".
Now, the moment you add "Coveo Search Interface", It also adds some default components as well as opens up the placeholder where we can put other components like below
Now, we will add the container and the columns splitter, remember its not coveo specific but because my page style required to have column splitter i am adding that, and on left we will have FACETS and on right hand side we will have our resulting cards.
Before we assemble "Coveo Result List" and "File Result Template", We will need to create those configuration data source item in coveo global settings item in Sitecore, so we will first create them and after that we can give those data source in corresponding components
Coveo Global Components Settings
You can download the sample coveo items from coveo example page, and if you have installed coveo package you can also create these items from choosing from insert option and selecting appropriate coveo template to get all below items, I have already explained that in
Part-2. so whatever the way you do, you will end up with getting all coveo data source items like below
Now, i will show settings and configuration which are must to get the desire results
As we talked before, we will be using "File Result List Template", that means we will have our own custom HTML template created on the disk in the folder "C:\inetpub\wwwroot\<<Site>>\Coveo\Hive\templates", so i will create a cshtml file and give that file name in one of the datasource settings.
Custom File Result List HTML file
On above path i,e "C:\inetpub\wwwroot\<<Site>>\Coveo\Hive\templates" i will create my custom template file which will have coveo specific syntax to read data from index, and as we already have seen that out data is in index, so you can find my HTML below (below is just small part of my HTML)
This HTML will differ from project to project depending on how you want to show one specific record, in my case this is the HTML of one specific card, i will save this file on the location mentioned above and give it a name "MyCustomFileResultTemplate.cshtml"
Now, we should create a data source configuration for our "Coveo Search Template" and create a new file result list datasource and configure our new template name into it which we created above.
And once data source item is created, we can give name of our new custom template there, so instead of default template we can have our custom HTML rendered like below
NOTE: Remember we will select all these data sources when we assemble components on our partial design, so it will automatically get these configurations instead of default behavior.
Now next up is to create data source item for "Coveo Search Interface", this is very important because out of all the indexed document, we only want to show our candidate specific data on the page, Remember in the starting of this blog i mentioned we will use "Item Template" to be filtered, we can do that be below configurations
NOTE: There are other different settings that you can tweak in different data source items, but i will put it on you to check and try on your end
Now, We have the needed items created, so let's go back to our partial design and add "Result List", and "File Result Template" components and configure our data sources
Let's first add "Search Result List", Before that Let's change the data source of "Coveo Search Interface" to point to our recently created data source so that it filter our results from all the other data
so let's open our partial design and find "Coveo Search Interface" and edit its data source and give following (Path of the newly created one above)
Now, Lets add Coveo File Results List component on to the page in existing coveo place holder and provide the data source which we have created for it above with our custom result template so it displays the result as we want
After selecting the proper data sources and our custom template, the page should look something like below, remember before doing these, i already had couple of export given to FED and i also had lot of imports hence the things are coming styled for me, in normal case, there will not be any custom CSS apart from coveo, you will need to give those pages to FED to style them as per your need.
NOTE: as i said earlier, my look and feel needed me to put column splitter in existing coveo placeholder and inside left and right column, we will put out components, so on right hand side i have placed our coveo file result list, coveo result list components.
As you can see the data is already started showing up from the index, and also its showing as per our custom html template.
Now this page can be given to FED and they can style it and we can import it back to get it perfectly styled on our end
In next post i will show you how to create facets on left hand side and in coming posts, i will also show you how can we write client side coveo events to do some very important tasks
Hope this was useful for all of you.
