-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathKISS-HOWTO.txt
168 lines (135 loc) · 8.84 KB
/
KISS-HOWTO.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
=================================================================================================================
KISS Template Format 1.0
=================================================================================================================
== OVERVIEW
kiss is html with embedded processing instructions inside appropriate <tags>.
Examples of processing instructions could be:
1. load display data about a product, customer, etc.
2. hide/remove part of the html document if data in a product, customer, etc. isn't set.
As the name implies it is very easy to learn KISS, especially if you already know HTML.
KISS includes a variety of simple "dwiw" (Do What I Want) functions to properly handle data, encoding, etc.
When KISS is done properly it's also easy to view/visualize approximately what the output will look while
editing the template.
KISS is suitable for eBay listings, Newsletter/Email content, and other places where it is useful to let
end users create HTML formatting that will later be populated with data from a product/customer ("rendering").
Unlike all other template languages KISS is pure valid previewable HTML5 with a few hidden instructions/hints
sprinkled in using data- attributes (which are valid in HTML5).
== GETTING STARTED
kiss templates are USUALLY stored in a container with the filename index.html
It's easy to know you're looking at a KISS template because the index.html will have the following <meta> tag:
<meta name="version" content="kiss/1.0">
Kiss is embedded inside HTML by hiding custom data- attributes such as:
<tag data-object="PRODUCT" data-attrib="zoovy:prod_name" data-if="BLANK" data-then="REMOVE">sample data</tag>
== UNDERSTANDING THE LOGIC
* the data-object MUST be supported by the container type
- container type 'EBAY PROFILE' will use data-object="PRODUCT"
- container type 'CAMPAIGN' will use data-object="CUSTOMER"
- container type 'ORDER' will use data-object="ORDER"
* the data-attrib MUST match with the data-object type
- data-object="PRODUCT" : any valid product attribute (ex: zoovy:prod_name)
- data-object="CUSTOMER": any valid customer attribute (ex: email)
- data-object="ORDER" : any valid order attirbute (ex: our/orderid)
Each type of HTML <tag> processing attempts to do a slight variation based on the tag type. For example
a <div> or <span> tag will replace it's inner contents (ex: <div>inner</div>) with the data retrieved
from the data-object/data-attribute. We'll discuss more on this later.
**********************************************************************************************
IMPORTANT CONCEPT: USING LOREM IPSUM
since data-object/data-attribute will *REPLACE* the inner contents it is recommended authors
embed lorem ipsum (http://www.lipsum.com/) text to assist users with visualize the template
while in preview mode before the data-object/data-attrib data is rendered:
Example Template Preview:
<div data-object="PRODUCT" data-attribute="zoovy:prod_desc">
Lorem Ipsum for Sample Product Description
</div>
Example Rendered View:
<div>
Actual Product Description
</div>
***********************************************************************************************
== KISS HTML <tag> Processing:
<div>|<span>|<p>|<q>|<h1>|<h2>|<h3>|<h4>|<h5>|<h6>|<figcaption>|<section>|<article>|<aside>|<li>
* replaces the inner contents of the tag with the data-object/data-attrib.
* supports conditional statements with or without data-object/data-attrib.
<img>
* modifies the src="" property.
* the data-object/data-attrib value WILL be formatted as an image link and set to the "src" attribute.
* data-object/data-attrib MUST refer to valid image fields (failure to do so could generate an error)
If the field is not set, a blank 1x1 pixel will be inserted.
* the image will (if possible) be auto-sized to the height= and width= specified in the image tag
* optional: <img data-img-height=""> override the <img height="">
- set this to zero to disable vertical scaling.
* optional: <img data-img-width=""> override the <img width="">
- set this to zero to disable horizontal scaling.
* set both <img data-img-width="0" data-img-height="0"> to reference the original (not resized) image.
* optional: <img data-img-bgcolor="RGBRGB"> applies a #RGBRGB background color to the image (when resized)
* optional: <img data-img-minimal="1"> turns on minimal image resizing to maintain aspect ratio
- minimal resizing never adds a background to an image even when height= and width= are both specified.
<a>
* the data-object/data-attrib value will be set in the "href" attribute
* optional: <a data-format="img"> follows the same rules as the <img src=""> handling
- to create a link to a fullsized image use: <a data-format="img" data-img-height="" data-img-width="">
<ul>
* will default to a list processor
**********************************************************************************************
IMPORTANT CONCEPT: PLACEHOLDER LINKS/GRAPHICS
since <img src=""> tags will be *REPLACED* during render, it is recommend that KISS template authors
include sample images as placeholders for template previews.
***********************************************************************************************
== HTML Conditional Processing:
* data-if="BLANK|NULL|NOTBLANK|NOTNULL|TRUE|FALSE|GT(#)|LT(#)|EQ(#)|NE(#)|REGEX//|NOTREGEX//"
- BLANK matches NULL, but also matches an empty string (a value of "" is set)
- NOTBLANK is the opposite of BLANK, any non-zero length string will match
* If you are confused by the subtle difference between BLANK and NULL then *ALWAYS* use BLANK (it'll dwyw)
- NULL is an undefined (not set) value -- NOT the same as BLANK (which is set to an empty string)
- NOTNULL is the opposite of NULL
-
- TRUE matches any positive number, "T", "TRUE", "YES", "Y" or "ON"
- FALSE matches zero, "F", "FALSE", "NO", "N", or "OFF"
-
- GT(#) matches any number greater than # (precise up to 3 decimal points)
- LT(#) matches any number greater than # (precise up to 3 decimal points)
- EQ(#) matches any number equal to # (precise up to 3 decimal points)
- NE(#) matches any number not equal to # (precise up to 3 decimal points)
-
- REGEX matches the pattern inside // (see perl regular expressions)
- NOTREGEX is the opposite of REGEX
* data-then="REMOVE|IGNORE"
* data-else="REMOVE|IGNORE"
HTML Conditional Example:
<li data-if="BLANK" data-then="REMOVE" data-object="PRODUCT" data-attrib="zoovy:prod_desc">
pretext
<span data-object="PRODUCT" data-attrib="zoovy:prod_desc">this will be replaced, or removed.</span>
posttext
</span>
**********************************************************************************************
IMPORTANT CONCEPT: Pretext and Posttext
Since conditionals remove themselves any HTML contained within a conditional will be removed/displayed
based on the conditional result. This makes it possible to have headers, footers, titles, etc. which are
all conditionally displayed based on the presence,absense, or content of a data-object/data-attribute
**********************************************************************************************
== HTML Formatting:
* data-format="img" will attempt to convert data into an image link
* data-format="wiki" will attempt to wiki-format the content and insert as html
* data-format="html" will not escape html in the content and insert it raw into the document
* data-format="dwiw" will attempt to auto detect wiki/html (based on <tag> presence) and do-what-i-want
* data-format="date" will format a timestamp or date into MM/DD/YYYY
* data-format="date(strftime)" will format a timestamp or date into a POSIX strftime date format string ex: %Y%m%d %H:%M:%S
== Trick #1: Make a click to zoom image reference
Used to override the base tag formatting, for example an "a" will normally set the "href"
to the data-attrib value.
In order to link to an image (possibly at a different height/width for zoom) it is necessary
to set data-format to "img"
At that point the data-img-height and data-img-width will be read, along with
data-img-bgcolor data-img-minimal and the data-attrib value will be converted to a link
which will then be set to the href.
== Trick #2: Using Wizards & Magic
Wizards work within the default KISS editor and provie an easy to add/remove blocks of html within a
template using jQuery (before runtime). If you are building a template that many users will work with
then we recommend reading WIZARD-HOWTO.txt
== KISS Q&A
- Why not simply use javascript.
KISS is not intended to replace javascript, or css for that matter. KISS is for situations where Javascript
isn't available or the content maintainer may not be a javascript developer.
CSS regrettably lacks the simplicity of conditional logic, and the W3C recommended way to format HTML with
conditional logic is XSL, which is frankly mind-numbingly difficult.
In many cases KISS will actually be rendered by Javascript.