-
Notifications
You must be signed in to change notification settings - Fork 1
/
HACKING
124 lines (64 loc) · 6.37 KB
/
HACKING
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
Hacking Sprinkles
=================
Welcome to Sprinkles customization! This document explains how you can alter various bits of the package to customize the look and feel, and add any features that you might dream up.
Sprinkles is designed to be customized at many levels, so that look & feel customizations are fairly easy, but more complex changes, such as added features, can also be accomplished with a bit of programming skill.
The sections below are sequenced according to the amount of skill required to perform the relevant changes.
Look and Feel (CSS/HTML)
------------------------
The look and feel of the site can be changed by modifying the CSS stylesheet, which can be found at `themes/default/sprinkles.css`. A wide variety of site designs can be obtained through modifying the stylesheet. For further flexibility, try modifying the HTML templates found in `themes/default/templates`, which use the Smarty templating syntax (see [Smarty For Template Designers](http://www.smarty.net/manual/en/smarty.for.designers.php)).
TBD: give an overview of the available template variables.
### Template variables available for topics and replies
For each template that displays a list of topics or replies, there is a template variable holding an array of these items, and each item has the following fields:
* `id`
The unique ID of the item (as a URI).
* `sfn_id`
The item's sfn:id, a number that uniquely distinguishes it from other items of the same kind (that is, from other topics, if this item is a topic, or other replies, if this one is a reply).
* `title`
In the case of topics, the topic title. In the case of replies, a descriptive string such as "John Q. replied to 'There's a green blob in my OJ.'"
* `content`
The content of the item, in HTML.
* `author`
A person record (see `get_person`, above) describing the author of the item.
* `updated`, `updated_relative`, `updated_formatted`
The timestamp when the item was last updated. The `updated` field is in seconds-since-the-epoch format; `updated_relative` is a human-readble string describing the approximate elapsed time since the update (such as, "2 weeks ago"); `updated_formatted` is a human-readable string giving the date of the update (such as, "December 8, 07").
For a topic, the update time will reflect the latest replies under that topic.
* `published`, `published_relative`, `published_formatted`
The timestamp when the item was first published. The `published` field is in seconds-since-the-epoch format; `published_relative` is a human-readble string describing the approximate elapsed time since the publication (such as, "2 weeks ago"); `published_formatted` is a human-readable string giving the date of the publication (such as, "December 8, 07").
The publication date of a topic is not affected by its replies.
* `company_url`
The company to which the topic pertains, represented as a URL. Not present for replies.
* `at_sfn`
A URL where the item can be found on the Get Satisfaction main site. This is a URL for a user interface to the item, as opposed to a machine-readable API resource.
* `replies_url`
The URL of the API resource where replies to the item should be posted. Not present for reply items.
* `in_reply_to`
For reply items, the ID (as a URI) of the item to which this one is a reply. For example, for top-level replies this would be a topic ID; for second-level replies this would be a reply ID. Not present for topic items.
* `topic_style`
For topic items, the style of the topic, one of the tokens `question`, `idea`, `problem`, or `talk`.
* `reply_count`
For topic items, the number of replies, whether direct or indirect. Not present for replies.
* `follower_count`
The number of people following this topic.
* `star_count`
The number of people who have starred this item.
* `flag_count`
The number of people who have flagged this item (as inappropriate).
* `tags`
A comma-separated list of tags on the item. Note that each comma may be immediately followed by whitespace which is not part of the tag, but whitespace following the next printing character is part of the tag.
* `emotitag_face`
A token identifying the face associated with the item, one of `happy`, `sad`, `silly` or `indifferent`.
* `emotitag_severity`
A number indicating the intensity of the associated emotion.
* `emotitag_emotion`
A string, the emotion entered by the author when posting the item. It is implicitly prefixed by the word "I'm": for example, if this field were "perplexed," it would normally be displayed as "I'm perplexed."
* `star_promoted`
For replies, a boolean indicating whether the reply has been promoted by the people, that is, through receiving a threshold number of stars from users.
* `company_promoted`
For replies, a boolean indicating whether the reply has been promoted by the owning company, which is performed through a separate administrative interface.
Behavior (PHP)
--------------
Each page of the site has a corresponding PHP file which is responsible for serving up that page--for example, the topic page is served by `topic.php`, the FAQ page by `faq.php`; these are the "views."
Each form is submitted to a controller, a PHP file whose name begins with `handle-`. This controller takes action as requested and then redirects the user to one of the views.
The PHP code in the views and controllers is responsible only for doing things specific to that particular page or action. Most of the functionality, then, is in the Sprinkles class (`Sprinkles.php`) or the Get Satisfaction API library (`Satisfaction.php`).
The Sprinkles class provides capabilities specific to the Sprinkles application, such as session handling, some in-memory caching facilities, utilities for keeping a database connection in context, and application-wide template variables, amongst other things. It also provides an interface to all of the routines in the API library, which allows fronting them with the in-memory cache. See comments in the file for detailed descriptions of the class methods.
The API library (`Satisfaction.php`) provides direct access to most of the Get Satisfaction web API. The library also makes use of a database-backed cache and makes intelligent HTTP requests in order to make good use of the cache. See the file `Satisfaction-lib-docs.html` for detailed documentation of the library.