Sesat > Docs + Support > Development using the SFC > Tutorial - Building Sesam.com

This tutorial will go through building a Sesat Skin from scratch to completion.
It repeats the basic building of the "sesam.com" skin found at sesat-kernel/generic.sesam/sesam.com

6 easy steps to build your own search engine website.

Create the project, a la the "Skin"

We will create the new skin from an existing archetype found within sesat-kernel. So we must checkout and build sesat-kernel & its skin-archetype first.

svn co http://sesat.no/svn/sesat-kernel/trunk sesat-kernel
cd sesat-kernel
mvn install -DskipTests=true
cd skin-archetype
mvn install -DskipTests=true

Now we can create our new skin:

cd ../..
mkdir test-skin

You should now have:

\-|
  |-sesat-kernel
   \-skin-archetype
  |-test-skin

Then do (you should replace -Dversion=2.18-SNAPSHOT with the version you see in sesat-kernel/pom.xml):

cd test-skin
mvn archetype:generate -DarchetypeGroupId=sesat -DarchetypeArtifactId=sesat-skin-archetype \\
-DarchetypeCatalog=local -DgroupId=sesat -DartifactId=pom.sesam.com \\
-Dversion=<current sesat-kernel version>-SNAPSHOT -Dpackage=no.search.sesat

    From Author: make sure you are using maven-archetype-plugin:2.0-alpha-3 or greater. Versions before that have some confusion between archetype:generate and archetype:create goals. Take a peek in ~/.m2/repository/org/apache/maven/plugins/maven-archetype-plugin/ if unsure. Add "-up -U" to the mvn archetype:generate command above to update to a later version.

You should now have under test-skin a directory "pom.sesam.com" and under that the files:

LICENSE.txt  pom.xml  query-transform-config  query-transform-control  result  result-handler-config  result-handler-control  search-command-config  search-command-control  velocity-directives  view-config  view-control  war
Troubleshooting
If these directories do not exist then "mvn archetype:generate ..." didn't work properly. You can workaround this by extracting the appropriate pom.sesam.com-X.Y.tar into the test-skin directory.

You can now cd into this new maven project that has all the possible skin components set up ready to go.
This tutorial will really only deal with the "war" submodule.
Try building the new maven project:

cd pom.sesam.com; mvn install -DskipTests=true
Some users report that -DskipTests=true doesn't work, if so revert to the older and deprecated -Dmaven.test.skip=true.

Create Business definition: modes.xml

We are going to use yahoo's search for our main result list. This is purely business logic so it all goes into modes.xml
Add to test-skin/pom.sesam.com/war/src/main/conf/modes.xml (inside the <modes></mode>):

    <mode id="default-mode" analysis="false" inherit="default-magic">
        <yahoo-web-command id="default-yahoo-web-command"
                           appid="YahooDemo"
                           field-filters="site"
                           host="yahooWebHost"
                           language="en"
                           port="yahooWebPort"
                           result-fields="Title AS title,Summary AS body,Url AS url,ClickUrl AS clickurl"
                           results-to-return="10">                                            
            <result-handlers>
                <field-chooser target="title" fields="title,url"/>
                <regexp field="url" target="site" regexp="http://([^/]*)/?"/>
            </result-handlers>
        </yahoo-web-command>   
    </mode>
    <mode id="international" evaluation="false" inherit="default-mode">
        <yahoo-web-command id="globalSearch" inherit="default-yahoo-web-command"/>
    </mode>

This defines two "modes". The first "default-mode" is both the template to build off and the guts of the configuration to the yahoo search command.
The second, "international", is the mode we'll actually be working with but it just inherits everything from "default-mode" for now. This layering approach is often a good idea for good house-keeping.

There are three result-handlers configured in this example. Result-handlers are used to manipulate (post-process) results once they have been fetched.
find-file-format adds a field to each result whose value is the mimetype guessed from the result's URL (which comes from the clickurl field).
field-chooser will assign the title field if it is null the value of the url field. A useful fallback mechanism.
regexp will assign the site field the regular expression capturing match against the clickurl field.

Note: in our repository version of generic.sesam/sesam.com/war/src/main/conf/modes.xml you'll see the yahoo-web-search elements commented out and replaced with similar yahoo-idp-search elements. The YahooIdpSearchCommand is a more powerful search interface to yahoo's indexes than their "Contextual Web Service", but you need to enter a contract with Yahoo to use it.

Create Presentation definition: views.xml

The configuration for how these results from yahoo will appear on the page comes from views.xml.
A "tab" does not have to be a tab in UI terms, here it simply refers to a page, tab, or vertical that layers on top of one of our modes.
Add to war/src/main/conf/views.xml (inside the <views></views>):

      <tab id="default-sesam-com" inherit="default"/> <!-- placement for a global skin css -->
    <tab id="international" inherit="default-sesam-com"
            key="g" 
            mode="international" 
            page-size="10"
            rss-result-name="globalSearch">
        <navigation>
            <navigation id="offset">
              <result-paging id="offset" command-name="globalSearch" page-size="10" number-of-pages="10" hitcount-source="totalhits"/>
            </navigation>
        </navigation>
        <layout main="sesam.com/main.jsp" front="sesam.com/index.jsp">
            <include key="header-element" template="sesam.com/head.jsp"/>
            <include key="header-element-extra" template=""/>
            <include key="top-col-one" template="sesam.com/searchbar-top.jsp"/>
            <include key="main-col-three" template="sesam.com/globalSearch.jsp"/>
            <include key="bottom-col-one" template="sesam.com/offsetPager.jsp"/>
            <include key="bottom-col-three" template="sesam.com/footer.jsp"/>
            <include key="bottom-col-two" template="sesam.com/searchbar-bottom.jsp"/>
        </layout>
    </tab>
Skin properties

war/src/main/conf/configuration.properties contains skin defining properties:

# Site attributes
site.parent=@sesam.site.parent@
site.locale.default=en
site.issitesearch=false
site.defaultTab=g
yahooWebHost=search.yahooapis.com
yahooWebPort=80
# disable fast token evaluation. HACK while we wait for SEARCH-3540 Anonymous TokenPredicates & Token Evaluator SPI.
tokenevaluator.port=0

The filtered properties come from the pom.xml
There six different profiles (in addition to the default "development" profile) that can be used for server testing and production environments as you wish.
The property here sesam.site.parent is crucial and must match the name of the web application, as deployed, that is the parent skin.
The yahoo properties relate to the host and port attributes previously mentioned in the yahoo-web-search element in the modes.xml.
The tokenevaluator.port property is set so to disable the FAST token evaluation while SEARCH.3540 is still in progress.

These default values the archetype created can be used in this tutorial.

Design templates

Each of the templates specified in views.xml must be created, along with the main.jsp and index.jsp. The main template's path is relevant war/src/main/webapp/pages/. The templates are all relative to war/src/main/webapp/fragments/layout.

These templates are rather self explanatory so links are given to each: http://sesat.no/source/xref/Sesat.Kernel..trunk/generic.sesam/sesam.com/war/src/main/webapp/WEB-INF/classes/pages/sesam.com/index.jsp http://sesat.no/source/xref/Sesat.Kernel..trunk/generic.sesam/sesam.com/war/src/main/webapp/WEB-INF/classes/pages/sesam.com/main.jsp http://sesat.no/source/xref/Sesat.Kernel..trunk/generic.sesam/sesam.com/war/src/main/webapp/WEB-INF/classes/fragments/layout/sesam.com/searchbar-top.jsp http://sesat.no/source/xref/Sesat.Kernel..trunk/generic.sesam/sesam.com/war/src/main/webapp/WEB-INF/classes/fragments/layout/sesam.com/globalSearch.jsp http://sesat.no/source/xref/Sesat.Kernel..trunk/generic.sesam/sesam.com/war/src/main/webapp/WEB-INF/classes/fragments/layout/sesam.com/offsetPager.jsp http://sesat.no/source/xref/Sesat.Kernel..trunk/generic.sesam/sesam.com/war/src/main/webapp/WEB-INF/classes/fragments/layout/sesam.com/footer.jsp http://sesat.no/source/xref/Sesat.Kernel..trunk/generic.sesam/sesam.com/war/src/main/webapp/WEB-INF/classes/fragments/layout/sesam.com/searchbar-bottom.jsp

These templates are internationalised, the message values (from <search:text.. tags) can be found in war/src/main/conf/messages_en.properties: http://sesat.no/source/xref/Sesat.Kernel..trunk/generic.sesam/sesam.com/war/src/main/conf/messages_en.properties

Design css

Some of the css definitions come from the existing css in generic.sesam: http://sesat.no/source/xref/Sesat.Kernel..trunk/generic.sesam/war/src/main/css/tab/default.css

Everything specific to the sesam.com skin is found in the default-sesam-com.css, which is the reason there exists the "default-sesam-com" tab in views.xml as each ancestor in the tab's ancestry imports a matching css:

http://sesat.no/source/xref/Sesat.Kernel..trunk/generic.sesam/sesam.com/war/src/main/css/tab/default-sesam-com.css

Finished!

Yes it's all that easy.
If you define the system environment variable CATALINA_BASE when you build ("mvn install") the warfiles should have automatically been copied into $CATALINA_BASE/webapps/
So, after building, inside the webapps directory there should exist: ROOT.war, generic.sesam.war, localhost.com.war
Given that you have something like "127.0.0.1 localhost.com" in your /etc/hosts file you should now be able to fire up your container (eg tomcat) and browse http://localhost.com:8080/





For more documentation on skin development see Development using the SFC.

 © 2007-2009 Schibsted ASA
Contact us