Templates
Users of previous versions of the shop,
please be aware that we changed the form of the tags!
The template is a plain html file, which contains the generic
html for a certain view. We have a main page template, a cart template,
a checkout template, and so on. We also offer support for static
content, which can contain the same tags as a template.
All the shop-specific fields are in the form:
<cityshop:keyword:value:.../>
We define a few reserved keywords:
views
This tag is dedicated to defining what view packages are included
in the page, and the order the views are being built. Place it usually
right after the <html> tag, to speed up the script. If this
tag is not present, the views will be taken from the page contents,
but no guarantee can be given that the order of execution will be
respected. One example of usage:
<html>
<cityshop:views:TextTopBar:MenuTop:MenuJumpbox:Auth/>
<head>
<title>My Account</title>...
This defines that there are 4 views in this template (the highlighted
names), and they will be built in the order listed. If this tag
is present, only the views listed in the tag are going to be processed.
view
Every view needs a place to be inserted in the template. The standard
format for a view tag is:
<cityshop:view:ViewName1/>
There are no other parameters needed, since this is only a target
placeholder. The script will display the view associated with the
"ViewName1". The hash key in the ShopSetup.pm that
creates this relationship is named: "-SHOP_VIEWS".
display
This is currently the only active tag in the shop. The basic format
is:
<cityshop:display:template:value:value:.../>
The library ShopBuildTagData.pm processes these tags in
two phases. For the first pass, the template is being read
and a list of the items to be read from the database is being built.
Then, a database query is made, and the output assigned to
a hash that has the templates as keys. The second pass through
the template replaces the placeholders with the calculated values.
A list of supported tags is defined as a global variable in the
ShopBuildTagData.pm library, under the name @ValidTags.
For the sake of simplicity, we begin all the product data display
tags with "Product", for categories we use "Category",
and so on.
We give here some examples of how you can build output using these
tags:
<cityshop:display:ProductPriceHTML:100005/>
Will display the price in the format assigned to this tag. There
is a shorter form for this tag, which looks like:
<cityshop:display:ProductPriceHTML/>
This form will ONLY work if the page is called with the parameter
&P=ProductID in the call string, which means,
we refer to this page as being the product static page. For ProductID
we pass the actual number that is the ProductID.
The complete format for a product related tag, is actually
as follows:
<cityshop:display:ProductTagName:
ProductID:IndexOnPage:FieldType:Values:Titles:Extra Data/>
Note that the tag has to be on one line,
otherwise the parser will ignore it!
- ProductID = The product ID
- IndexOnPage = Index on page for the presented item.
You can have more than one product on one page, and the might
have their own form input fields or hidden fields that are generated
by this keyword. To be able to add the right one to the shopping
cart, we need to identify them by providing an index to the field.
- FieldType = Type of the field.
Currently suppoted field types are: select, mselect,
checkbox, radio, hidden, and text.
Just to avoid confusion, the "mselect" means
"multiple select" and allows the select of multiple
items in a select box.
- Values = Values, semicolon separated (;).
These are relevant only for the multiple value fields, like select,
mselect, checkbox, and radio.
- Titles = Titles, semicolon separated (;)
These are relevant only for the multiple value fields, like select,
mselect, checkbox, and radio.
- Extra Data = Extra information for this tag.
An example of usage is the description of the field, or the empty
value for a select box.
Here is a full tag, built with the structure described above:
<cityshop:display:ProductOrderQuantityField:100005:1:
select:1;2;5:one;two;five:Select Amount/>
Note that the tag has to be on one line,
otherwise the parser will ignore it!
In the demo shop, the product "Programming
Perl (3rd Edition)" is using a static page build on
this concept.
Common Tags
The shop.cgi builds a hash %D which is used to hold the
main links, form tags and hidden fields. You can display the values
of that hash, by passing the hash keys as arguments to the tag,
as follows:
<cityshop:FormTag/>
<cityshop:HiddenFields/>
The complete list of values is:
- JavaScriptHeader
- HTMLStyle
- ScriptLink
- SecureScriptLink
- FormTag
- FormTagOneClick
- ManagerFormTag
- HiddenFields
The "JavaScriptHeader" is the placeholder for
the page-specific script header, if we decide to use one. In its
initial implementation, the Store does not use any common javascript
in header, but you can customize that on your own, in the Views
module, adding a concatenation routine in the store.cgi, right before
replacing the placeholders. With the first practical implementation
that comes my way, I will introduce an example in the code.
The "HTMLStyle" contains the CSS associated with
this view. For the time being, the shop uses a central CSS cartridge,
that can be found in the ShopSetup.pm, under the variable named
"$BaseHTMLStyle", that is assigned to the shop
generic hash under: "-LAYOUT_BASE_HTML_STYLE".
Of course, you can put directly the CSS content in the template,
omitting the tag, or you can customize its display at the Views
level, as you need.
An example why you would like to do so, is to have a different color
set for different categories, or sections of the shop.
The "FormTag", "ManagerFormTag"
and the "HiddenFields" are inserted in the code
as needed, since some of the Views do not insert their own form
tags. These are the menu Views, like: TextTopBar, Menu,
MenuJumpBox, MenuCat.
You can change that as you see fit, but I found it comfortable that
way, since most of the menues are usually http links, and not form
buttons. The reason we prefer to use the http link, is that it can
be easily bookmarked, since it uses the HTTP GET method, that passes
all the form data in the link.
You are welcome to add support for other exception tags, as your
implementation requires it.
StaticTags
For building links in the shop static pages, which are supposed
to bring up a product page, checkout link, or something similar,
we had to change the format of the tag a bit, so that it can be
used in the link:
<a href="[cityshop:SecureScriptLink:&P=100005/]">Secure Product Page</a>
Note that the tag has to be on one line,
otherwise the parser will ignore it!
As you can see, the tag is much simpler than the previous. The
keyword "cityshop" is always present. The next
keyword is the name of the link, from the choices below:
- ScriptLink
- SecureScriptLink
More keywords will be added as needed. Of course you can use anything
that is mapped in the %D hash, but all the rest of the values
are not usable in a link. For example, you can mix some common tags
with the static tags as follows:
<cityshop:FormTag/>
[cityshop:HiddenFields/]
Of course, if viewed directly in a browser, the second tag will
show up in the HTML display, while the first one will stay hidden.
The most important usage of the static tag is to build custom search
links. The third parameter in the tag is therefore a URL-encoded
string which you can plain cut and paste from your browser, leaving
out the site URL, the script path, cart, session, and eventually
language field:
<a href="[cityshop:ScriptLink:&SearchButton=1&SLP=10&SHP=40
&SKey=Perl%20book&MatchAll=1&SLogic=1&Sort=name/]"
>Perl books between $10 and $40</a>
Note that the tag has to be on one line,
otherwise the parser will ignore it!
Custom Tags
The shop also supports a different tag format, which will NOT be
processed in the ShopBuildTagData.pm library. If you parse
the template file in a different routine, that routine will have
to build the output for the template. An example is the following
tag, from the OrderMailUser.txt template:
Order Number: <?-ORDER_NUMBER>
Basically, this tag has the format:
<?Keyword>
Where "Keyword" is usually a hash key in a custom hash
that is used to build the tag output. An example of how that is
being implemented, is in the _LogOrderAndSendEmails() routine,
in the ShopOrderLib.pm
|
