SobiPro Templating How To…
I am not against anyone making money from their great work and the developers of SobiPro are no exception. However I do believe that if you are providing a solution that is supposedly for free that it comes with some basic documentation on how to use the product. However to access this basic documentation a ‘club’ membership is required which I feel is wrong, but that is only my view, yours may be different. During my use of SobiPro I have been compiling a list of how to references on using the SobiPro Template framework and the template language (XSL) used.
UPDATE: Yesterday I decided to trial a Club Membership and bought a 1 month membership to see what the documentation was like, and to be honest I was pleasantly surprised and really do believe that a 1 or 3 month membership is worth it as the documentation is very good. It fills the gap between what I already knew and what I have been trying to work out. So if you can afford a single months membership I suggest you get it, or better yet a 3 month membership. The only thing that they need to consider adding is an upgrade path from a Bronze to Silver to Gold which I think will assure ongoing payments by users as they notice the true value of the documentation.
Anyone that has previously used Sobi2 prior to SobiPro would have seen the great documentation provided on the Sigsiu website of which, through the use of that documentation, many were able to make their sobi2 site look, work and play as they wanted it to, it was what made sobi2 so great. That documentation gave quite detailed descriptions, guides and examples on how to create, edit and customise the templates used for the front end of the Sobi2 system. Unfortunately that information is not being provided for SobiPro unless you obtain a SobiPro Club Membership with a minimum cost of 30 Euro for a single months access. The developers have decided that any and all documentation is only provided via a Club Membership. that is fine and that is their choice, but I feel the basic documentation should be provided freely with SobiPro just like it was for Sobi2. Please do not take me the wrong way of not supporting developers for their work, I have bought quite a few add-ons for the previous sobi2 solution and would have again with SobiPro if it went down that same path.
So anyway while starting to use SobiPro I have been compiling my own set of ‘template’ guide notes for SobiPro so that I can refer to them when I need to for any other future SobiPro sites. This list is not exhaustive and only covers those template functions I have needed so far and therefore is not a complete list of template functions and how to’s. I am also not an XSL expert by any stretch of the imagination but I am learning thanks to SobiPro. I also need to point out that all of the information has been gathered from actually using SobiPro with some trial and error to see the end results. Much of the detail is actually freely available from within the included templates (vehicle section template) of the base SobiPro install, you just need to know where to look. I have not yet purchased a Club Membership so I have no access to any of that documentation, even if I did I would not divulge the content that is beyond the basics of SobiPro core as that would not be right. I need to be clear that I am not seeking to take anything away from the SobiPro developers, but rather help other SobiPro users too understand how the template system works and hopefully it will enable them to better utilise SobiPro, just as we were able to do with Sobi2. If of course the SobiPro developers decide to make the core documentation that contains what I have below and more public, then that is great and is in my view what should have been done in the first place..
Please also note the following is from my own use and testing, there may be more efficient ways of doing some of the below which I have yet to discover and test. If you are a SobiPro user feel free to submit additions to this post, but please if you have bought a membership do not provide any non core documentation content as that is what you (and others) should be paying for to support the ongoing development of sobi* in general.
Please, I need to be clear here that I am not out to be destructive or negative towards SobiPro or Neo and Trinity at Sigsiu.net. Far from it, I would like to support it more if I could and I hope by helping others that I am doing just that and not simply seen as being ‘destructive’ as Neo has mentioned here. I would be very happy to buy a Club Membership ‘IF’ the price for that membership was more reasonable.
Differences between Vcard and Details view
When looking to insert fields into the vcard and the details view there is two small differences between the two.
For vcard view the fields are added by simply prefixing the field you want with field/
For the Details view you need to prefix the fields with entry/field
Some of this is shown below in the examples provided.
Getting a field label:
On the Card view;
<xsl:value-of select="fields/field_NAME/label" />
On the Details view;
<xsl:value-of select="entry/fields/field_NAME/label" />
The field_NAME is the actual field name that you wish to have the label for.
Adding text within a field area:
Surround the text with the following code
Where YOUR TEXT is any text you want displayed in or around the field label or field data.
Displaying a fields data:
On the Card view;
<xsl:value-of select="fields/field_NAME/data" />
On the Details view;
<xsl:value-of select="entry/fields/field_NAME/data" />
field_NAME is the field to which you want the data displayed
Displaying an Image field:
For a single image in the vcard use the code
<xsl:copy-of select="fields/field_item_main_image/data" />
For a single image in the detail sview use the code
<xsl:copy-of select="entry/fields/field_item_main_image/data" />
Where field_item_main_image is the name of the image field you want displayed.
Display a web site URL field as a link (updated).
The field label is of course optional.
For the Card view
<xsl:value-of select="fields/field_web_site/label" /><xsl:text>: </xsl:text> <a> <xsl:attribute name="href"> <xsl:value-of select="fields/field_web_site/data/a/@href" /> </xsl:attribute> <xsl:value-of select="fields/field_web_site/data" /> </a>
For the Details View
<xsl:value-of select="entry/fields/field_web_site/label" /><xsl:text>: </xsl:text> <a> <xsl:attribute name="href"> <xsl:value-of select="entry/fields/field_web_site/data/a/@href" /> </xsl:attribute> <xsl:value-of select="entry/fields/field_web_site/data" /> </a>
Where field_web_site is your web site field.
Conditional Publish Statement:
If you wish to check a value and if correct publish or if not then not publish the code is simply
<xsl:if test="fields/YOURFIELD/data = 'THEVALUE'"> <xsl:value-of select="fields/YOURFIELD/data" /> </xsl:if>
<xsl:if test="entry/fields/YOURFIELD/data = 'THEVALUE'"> <xsl:value-of select="entry/fields/YOURFIELD/data" /> </xsl:if>
The value is whatever you want to check if something is equal to it, for example is the field equal to 100, you would add 100 in the THEVALUE location. Take note also that there is no elseif in XSL, you can use otherwise (shown in next how to example) or you can nest additional if statements if you want it to check for more values.
Outputting content without html being shown:
In the xsl value section add the following after the field data
so for example on the card view use
<xsl:value-of select="fields/field_item_detail/data" disable-output-escaping="yes"/>
Or on the details view use (though I do not think you need to for the details view, but here it is anyway)
<xsl:value-of select="entry/fields/field_item_detail/data" disable-output-escaping="yes"/>
Truncating a fields output:
<xsl:choose> <!-- if YOURFIELD is greater than the MAXLENGTH --> <xsl:when test="string-length( YOURFIELD ) > MAXLENGTH "> <!-- print out the truncated value followed by "..." --> <xsl:value-of select="substring( YOURFIELD ,0, MAXLENGTH )"/>... </xsl:when> <xsl:otherwise> <!-- otherwise print out the whole, un-truncated string --> <xsl:value-of select=" YOURFIELD "/> </xsl:otherwise> </xsl:choose>
Replace YOURFIELD with the field name that you want to have truncated, e.g. fields/field_item_detail/data
Replace MAXLENGTH with the maximum length of the output you want, e.g. 80.
Show more than 15 sub-categories:
If you want to show more than the max subcategories set by the sections General Configuration simply open up the your SobiPro template folder and locate the common/category.xsl file and edit line 28
Change the +1
<xsl:if test="position() < ( $subcatsNumber + 1 )">
to whatever number you want it to be, e.g. + 30
<xsl:if test="position() < ( $subcatsNumber + 30 )">
Now up to 45 sub category items will display (if you selected 15 in the General Configuration)
Choosing one value over another, conditional result
This is useful if you want to test a value to have a value and if not then use an alternative value. For example if I want to check to see if the listing is in a US State I can have two fields, one for US States (field_state) and one for Non US States (field_non_us_state). I have a select drop down box for all US states, but also one for Non US State. When a user enters their record they can enter either the US State or they can select Non US State and then enter the non US State in the field provided (field_non_us_state). Now I want to show the correct data for that record, being either the US state or the Non US State, to do this and to cover both options I can have something like this. Remember the field display differences between Card view and Details view shown above.
<xsl:choose> <xsl:when test="fields/field_state/data = 'Non-US-State'"> <xsl:text>, </xsl:text><xsl:value-of select="fields/field_non_us_state/data" /> </xsl:when> <xsl:otherwise> <xsl:text>, </xsl:text><xsl:value-of select="fields/field_state/data" /> </xsl:otherwise> </xsl:choose>
The above will check via a choose command to see if the first value is correct and if so it will apply that data, if not it will then move to the next option and that being the US State. It is kind of like an IF statement but less messy as it will choose the correct result.
Adding the Category Name to the page heading (content).
When you view a page within your SobiPro front end you will see the section name as the component heading name on all pages, while this is good I wanted to also add the category name to that title as well. So instead of just having Business Directory at the top of the page I can now have Business Directory – Category Name. It is very simple to do.
In your template folder and the category folder select the view.xsl file and add
- <xsl:value-of select="name" />
<xsl:value-of select="section" />
to end up with
<xsl:value-of select="section" /> - <xsl:value-of select="name" />
The Result will be your SobiPro Section name and then the Category name.
If you want the same also added to an entries details page (entry/details.xsl), the code for that is slightly different, add
- <xsl:value-of select="entry/categories/category" />
<xsl:value-of select="section" />
so you end up with
<xsl:value-of select="section" /> - <xsl:value-of select="entry/categories/category" />
Now you will have the Section and category name displayed on the top of the page.
Outputting the date of entry or date of update in a format you want.
I wanted to display the date an entry was added and last updated which is easily done by using the following (for details page)
<xsl:value-of select="php:function( 'SobiPro::Txt', 'Date added' )" />:<xsl:text> </xsl:text> <xsl:value-of select="entry/created_time"/><xsl:text> | </xsl:text> <xsl:value-of select="php:function( 'SobiPro::Txt', 'Last time updated' )" />:<xsl:text> </xsl:text> <xsl:value-of select="entry/updated_time"/>
However the output of the date comes out like this 2011-08-09 00:00:00
I wanted it to only show the date and as date/month/year, to do this I was able to change the date format by using the built in FormatDate function, like this
<xsl:value-of select="php:function( 'SobiPro::FormatDate', 'd/M/Y', string(entry/updated_time) )" />
You can use different date formats by using the correct date codes for php found at http://php.net/manual/en/function.date.php.
Note if you want to add the dates to your vcard you will need to change;
Replace the jquery modal box with mootools slimbox.
The example provided to start me off is what is provided in the ‘vehicles’ template, the code for the modal jquery pop up image is written as
<div style="float: right;" id="SPGallery"> <a class="modal" > <xsl:attribute name="href"> <xsl:value-of select="entry/fields/field_image/data/@original"/> </xsl:attribute> <xsl:copy-of select="entry/fields/field_image/data/*" /> </a>
You will need to edit the details.ini file and replace
js_files = "jquery,details,box"
js_files = "slimbox"
css_files = "default,details,box"
css_files = "default"
Now the code I am using in my details.xsl file to replace the modal one (shown above) is the following, you can style it differently if you want;
<div style="float: right;"> <a rel="lightbox"> <xsl:attribute name="href"> <xsl:value-of select="entry/fields/field_entry_image/data/@original"/> </xsl:attribute> <xsl:copy-of select="entry/fields/field_entry_image/data/*" /> </a> </div>
The @original is what is used to create the link to the original file. this is what is shown when the user clicks on the thumbnail image. Ensure that in your SobiPro field for your image that you have set the thumbnail to be shown as default in the details view.
You will also need to obtain slimbox – get it from http://www.digitalia.be/software/slimbox but remember that slimbox2 uses jquery, so get slimbox 1.7x.
I then copied all of the slimbox css and placed it into the default.css file for my Sobipro template, and likewise copied the images into the css folder as well. I copied the slimbox.js file to the js directory of the template I am using, which you referenced already above. Save it all.
That should be it, test your SobiPro front end and details view to check that it is working for you.
Setting a Default Category for those sections with only one category
Thanks to KST for help in working out this solution
First identify the ID of the category you will use as your default.
Add this line just after the last div in the default template / entry / edit.xsl file, where XX is your default category.
<input type="hidden" name="entry.parent" value="62" id="entry.parent" />
Then delete lines 26 to 46
<div> <div> <label for="entry.parent"> <xsl:value-of select="php:function( 'SobiPro::Txt' , 'TP.CAT_BOX' )" /> </label> </div> <div> <xsl:copy-of select="entry/category_chooser/path/*"/> <div style="clear:both;"/> <div style="float:left; display:none;"> <xsl:copy-of select="entry/category_chooser/selected/*"/> </div> <div style="float:left;"> <button type="button" name="parent_path" id="entry_parent_path"> <xsl:value-of select="php:function( 'SobiPro::Txt' , 'EN.SELECT_CAT_PATH' )" /> </button> </div> <div style="clear:both;"/> </div> </div> <div style="clear:both;"/>
Save and test.
Adding alt and title text to an image
When developing your site you should always ensure that you use an ‘alt’ and ‘title’ tag for all of your images. SobiPro however does not provide this by default so you need to build that into your template;
Lets say for example you want to have a main image on your entries details page, first you need to create the image field, lets just call it ‘field_my_image’ for this example, here is how the code needs to look to enable it to use an alt and title tag
<img class="spFieldsData"> <xsl:attribute name="title"> <xsl:value-of select="entry/name" /> </xsl:attribute> <xsl:attribute name="alt"> <xsl:value-of select="entry/name" /> </xsl:attribute> <xsl:attribute name="src"> <xsl:value-of select="entry/fields/field_my_image/data/img/@src" /> </xsl:attribute> </img>
What we have done here is split up the img src code into segments so we can control what is used and how it is displayed. For the ‘alt’ and ‘title’ tags I have chosen to use the entry name field, you can of course use another specific field if you want. As can be seen I have set a value for the title, the alt and of course the image itself, The end result is your image is displayed and now includes alt and title in its source.
The same can also be done for the vcard view, you simply need to remove the entry/ part of the fields code, so that would look like this;
<img> <xsl:attribute name="title"> <xsl:value-of select="name" /> </xsl:attribute> <xsl:attribute name="alt"> <xsl:value-of select="name" /> </xsl:attribute> <xsl:attribute name="src"> <xsl:value-of select="fields/field_my_image/data/img/@src" /> </xsl:attribute> </img>
Nice and Easy
Showing a field only if it contains data.
This is a variation of the check for specific data as I have provided above, but since this was asked for specifically here is the way to do it.
Basically what you are about to do is simply check that the field contains data, if it does then show the field (and other data linked to it) otherwise do not show that field at all. This is a basic IF statement that checks for a null value. This example uses a filed named ‘field_name’ just substitute that for your field.
In the vcard view
<xsl:if test="fields/field_name/data != ''"> <div> <span><xsl:text>Field Name: </xsl:text></span> <span><xsl:value-of select="fields/field_name/data" /></span> </div> </xsl:if>
In the Details view
<xsl:if test="entry/fields/field_name/data != ''"> <div class="spField"> <span class="label"><xsl:text>Field Name: </xsl:text></span> <span><xsl:value-of select="entry/fields/field_name/data" /></span> </div> </xsl:if>
… more to come as I use SobiPro more and more
Oh if you want to post some code for me to see what issues you are having use the code button and then use ‘<‘ in place of ’<’ and ‘>‘ in place of ‘>’