1 |
dpavlin |
4 |
|
2 |
|
|
|
3 |
|
|
File: libdata_customization.txt |
4 |
|
|
Title: LibData Customization |
5 |
|
|
Author: Paul F. Bramscher brams006@umn.edu |
6 |
|
|
Date: November 19, 2003 |
7 |
|
|
|
8 |
|
|
|
9 |
|
|
============================================================================== |
10 |
|
|
TABLE OF CONTENTS |
11 |
|
|
============================================================================== |
12 |
|
|
|
13 |
|
|
1.0 Introduction |
14 |
|
|
2.0 File Structure, Headers, and Footers |
15 |
|
|
3.0 LibData PageScribe Styles |
16 |
|
|
4.0 Conclusion |
17 |
|
|
|
18 |
|
|
============================================================================== |
19 |
|
|
1.0 INTRODUCTION |
20 |
|
|
============================================================================== |
21 |
|
|
|
22 |
|
|
The striving of many web designers has been to separate content from |
23 |
|
|
presentation to the greatest extent possible. Only limited effort toward this |
24 |
|
|
end has been achieved on the LibData administration side. It should best be viewed |
25 |
|
|
as a program delivered over the web, rather than as a dynamic web page. As such, |
26 |
|
|
expectations of wide-ranging and easy modification should be more in step with |
27 |
|
|
desktop applications than with flat web pages or documents. Many of the forms |
28 |
|
|
are tightly coupled with underlying logic affecting their functionality. |
29 |
|
|
|
30 |
|
|
With web scripting environments in general there are often the tendencies to |
31 |
|
|
bounce in and out of contexts (HTML, logic, or SQL) to the point that logic |
32 |
|
|
structures -- particularly nested structures more than two layers deep -- become |
33 |
|
|
increasingly unreadable. So on the administrative side, particularly, |
34 |
|
|
presentation customization will require some knowledge of PHP coding practices. |
35 |
|
|
The approach taken here is that when the logic required to render a page is more |
36 |
|
|
substantial than the HTML tagging, then it becomes fair game to "submerge" or |
37 |
|
|
imbed the HTML within logic code for the sake of logic readability (rather than |
38 |
|
|
ease of formatting customization). |
39 |
|
|
|
40 |
|
|
That said, there are a still number of public (and private) pages which are easily |
41 |
|
|
customizable. Additionally, there are a few areas which require presentation |
42 |
|
|
customization and these will be detailed further in this document. |
43 |
|
|
|
44 |
|
|
============================================================================== |
45 |
|
|
2.0 NOTES ON FILE STRUCTURE |
46 |
|
|
============================================================================== |
47 |
|
|
|
48 |
|
|
LibData is generally to be installed into two separate web servable directories. |
49 |
|
|
One location hosts the public side environment (public LibData), the other is |
50 |
|
|
(hopefully) served over an SSL port (administration LibData). These directories |
51 |
|
|
are determined at install time. Within each are a number of files which are |
52 |
|
|
quickly customizable, and contain virtually no programming code: |
53 |
|
|
|
54 |
|
|
---------------------------------------------------- |
55 |
|
|
Administrative Customization under /libdata/include/ |
56 |
|
|
---------------------------------------------------- |
57 |
|
|
libdata_header.phtml |
58 |
|
|
The header file for the administrative LibData pages. |
59 |
|
|
|
60 |
|
|
libdata_footer.phtml |
61 |
|
|
The corresponding footer file for administrative LibData pages. |
62 |
|
|
|
63 |
|
|
scribe_header.phtml |
64 |
|
|
The header file for PageScribe/CourseLib pages. It can be |
65 |
|
|
similar to libdata administrative above, or customized independently. |
66 |
|
|
|
67 |
|
|
scribe_footer.phtml |
68 |
|
|
The corresponding footer file for PageScribe/CourseLib. |
69 |
|
|
|
70 |
|
|
libdata.css |
71 |
|
|
The standard CSS definitions for use with the administrative portion |
72 |
|
|
of libdata. Note especially that the file contains classes S1, S2, |
73 |
|
|
S3, S4, and S5. These special style classes correspond to 5 possible |
74 |
|
|
styles during CourseLib/PageScribe page authoring. Individual pages |
75 |
|
|
may have customized headers, footers, and CSSs (treated in the |
76 |
|
|
LibData Usage Manual), but these five are used as defaults if nothing |
77 |
|
|
else is available. This will be explained in section 3.0 LibData |
78 |
|
|
PageScribe Styles. |
79 |
|
|
|
80 |
|
|
-------------------------------------------------- |
81 |
|
|
Public Customization under /libdata/ (public side) |
82 |
|
|
-------------------------------------------------- |
83 |
|
|
|
84 |
|
|
header.phtml |
85 |
|
|
The header file for the public LibData pages. |
86 |
|
|
|
87 |
|
|
footer.phtml |
88 |
|
|
The corresponding footer file for public LibData pages. |
89 |
|
|
|
90 |
|
|
libdata.css |
91 |
|
|
The standard CSS definitions for use with the public portion |
92 |
|
|
of libdata. Note especially that the file contains classes S1, S2, |
93 |
|
|
S3, S4, and S5. These special style classes correspond to 5 possible |
94 |
|
|
styles during CourseLib/PageScribe page authoring. Individual pages |
95 |
|
|
may have customized headers, footers, and CSSs (treated in the |
96 |
|
|
LibData Usage Manual), but these five are used as defaults if nothing |
97 |
|
|
else is available. This will be explained in section 3.0 LibData |
98 |
|
|
PageScribe Styles. |
99 |
|
|
|
100 |
|
|
|
101 |
|
|
Both page.phtml and page_print.phtml first attempt to load a customized header |
102 |
|
|
and footer. This customized header is explained in section 3.0 LibData Styles. |
103 |
|
|
If it is not defined LibData will load a default header and footer (known as |
104 |
|
|
header.phtml and footer.phtml respectively). These are unique to your |
105 |
|
|
institution, and may be placed either in the LibData public directory or in your |
106 |
|
|
default Apache/PHP server side include location. They are completely |
107 |
|
|
customizable and may be straight HTML if desired, contain javascript, etc. |
108 |
|
|
|
109 |
|
|
The other files ending with a .phtml extension may be modified at will, though |
110 |
|
|
certainly there is PHP code in them. Standard best practice includes the |
111 |
|
|
historical backup of files frequently or establishing a CVS code repository |
112 |
|
|
system. |
113 |
|
|
|
114 |
|
|
subject.phtml, for example, renders a Research QuickStart subject page. |
115 |
|
|
Youll note that there is scant little basic HTML in it -- most of the file |
116 |
|
|
is logic necessary to draw the page and dynamically generate the underlying |
117 |
|
|
HTML. |
118 |
|
|
|
119 |
|
|
============================================================================== |
120 |
|
|
3.0 LIBDATA PAGESCRIBE STYLES |
121 |
|
|
============================================================================== |
122 |
|
|
|
123 |
|
|
LibData, in both the public and administrative portions, has a basic libdata.css |
124 |
|
|
file (the purpose of which is detailed above). However, this application was |
125 |
|
|
designed for a Big-10 university library environment with many libraries and |
126 |
|
|
special departments within libraries with their own look-and-feel. |
127 |
|
|
|
128 |
|
|
LibData pages created through the CourseLib/PageScribe authoring environment |
129 |
|
|
may reference PageScribe Styles -- these are defined on the LibData Manager |
130 |
|
|
Functions console menu under "PageScribe Style." Styles have the following |
131 |
|
|
attributes: |
132 |
|
|
|
133 |
|
|
(A) A style title |
134 |
|
|
(B) header file |
135 |
|
|
(C) footer file |
136 |
|
|
(D) css file |
137 |
|
|
|
138 |
|
|
The header/footer/css fields contain relative (for example, |
139 |
|
|
styles/smithlibrary/header.phtml) pathing or a full http reference |
140 |
|
|
(for example, http://anothersite.library.edu/header.phtml). However, |
141 |
|
|
with the CSS file we've had the best luck if the relative path |
142 |
|
|
mechanism is used. |
143 |
|
|
|
144 |
|
|
Steps to create a new LibData PageScribe (CourseLib as well) Style: |
145 |
|
|
|
146 |
|
|
---------------------------------------------------------------- |
147 |
|
|
(1) Create the directory for the three files (header/footer/css) |
148 |
|
|
---------------------------------------------------------------- |
149 |
|
|
|
150 |
|
|
The preferred (internal) directory location for PageScribe styles is: |
151 |
|
|
/{libdata public side}/styles/{stylename} |
152 |
|
|
|
153 |
|
|
Although these styles may be anywhere on the libdata server, it's |
154 |
|
|
recommended that they are encapsulated into a unique subdirectory |
155 |
|
|
since they'll include three files and any associated graphical |
156 |
|
|
elements. If, however, your styles share more common attributes than |
157 |
|
|
not you may want a different structure altogether. |
158 |
|
|
|
159 |
|
|
------------------------------------------------- |
160 |
|
|
(2) Create the header/footer/css files themselves |
161 |
|
|
------------------------------------------------- |
162 |
|
|
|
163 |
|
|
There are no special instructions for the header or footer file |
164 |
|
|
content -- they are totally customizable. |
165 |
|
|
|
166 |
|
|
The CSS file may also contain anything desired. However, it should |
167 |
|
|
contain (additionally) five special CSS classes: |
168 |
|
|
|
169 |
|
|
S1 |
170 |
|
|
S2 |
171 |
|
|
S3 |
172 |
|
|
S4 |
173 |
|
|
S5 |
174 |
|
|
|
175 |
|
|
These classes are used within a SPAN tag to render PageScribe/CourseLib |
176 |
|
|
pages. In the authoring environment, page authors may individually |
177 |
|
|
tweak each page element with a number [X][1][2][3][4][5] (X corresponds to |
178 |
|
|
no class, using the default body text instead). |
179 |
|
|
|
180 |
|
|
It was discussed by the LibData design committee that we wanted to |
181 |
|
|
strike a balance between a webmaster's desire for some sort of page |
182 |
|
|
consistency versus author creative freedom. So setting up the |
183 |
|
|
PageScribe/CourseLib styles is a Manager function, requires unix ftp or |
184 |
|
|
sftp access to physically place the files, and create the corresponding |
185 |
|
|
five SPAN styles. We've felt that after roughly five style changes a page |
186 |
|
|
begins to become "messy" anyway. |
187 |
|
|
|
188 |
|
|
One approach is to make the styles get increasingly smaller in size |
189 |
|
|
(roughly analogous to the HTML H tags). Note that the span styles |
190 |
|
|
encapsulate several attributes. For example: |
191 |
|
|
|
192 |
|
|
.S1 { |
193 |
|
|
font-family: Arial, Helvetica, sans-serif; |
194 |
|
|
font-size: 18pt; |
195 |
|
|
color: #2F4F4F; |
196 |
|
|
} |
197 |
|
|
|
198 |
|
|
.S2 { |
199 |
|
|
font-family: Arial, Helvetica, sans-serif; |
200 |
|
|
font-size: 14pt; |
201 |
|
|
color: #2F4F4F; |
202 |
|
|
} |
203 |
|
|
|
204 |
|
|
So, unlike a full-fledged word processing environment in which a section |
205 |
|
|
of text may independently contain bold, italics, underline, size, etc. |
206 |
|
|
attributes, LibData limits an authored page to only five overall theme |
207 |
|
|
variations. This may be extended in future versions, or with some |
208 |
|
|
relatively minor programming the current version may be extended. We're |
209 |
|
|
still investigating the balance between full-blown creative license versus |
210 |
|
|
some page consistency in look-and-feel across a large site. |
211 |
|
|
|
212 |
|
|
----------------------------------------------------- |
213 |
|
|
(3) Enter the directory path information into LibData |
214 |
|
|
----------------------------------------------------- |
215 |
|
|
|
216 |
|
|
From the Manager Functions menu click to create a New PageScribe Style. |
217 |
|
|
|
218 |
|
|
Pick a (unique) style name, and fill in the corresponding information |
219 |
|
|
for the header/footer/css file locations. Note that they are relative |
220 |
|
|
to the /{libdata public side} path. |
221 |
|
|
|
222 |
|
|
If there is a discrepancy between the actual file name and its |
223 |
|
|
entry in the LibData system (see the next step), or there is a |
224 |
|
|
permissions issue, the entire LibData page may fail to load. |
225 |
|
|
LibData currently does no error checking at this step. Additionally, |
226 |
|
|
for security purposes most includes (except CSS files) are of the |
227 |
|
|
"required" sort in PHP. This means that the script will abort if |
228 |
|
|
an included file is missing. |
229 |
|
|
|
230 |
|
|
------------------------------------------------------ |
231 |
|
|
(4) Create a New CourseLib or PageScribe Page and Test |
232 |
|
|
------------------------------------------------------ |
233 |
|
|
|
234 |
|
|
From either scribe_start.phtml or the main authoring console menu, |
235 |
|
|
create a new CourseLib or PageScribe Page and populate it with |
236 |
|
|
some page elements (for further directions here, check the |
237 |
|
|
LibData Introduction file). |
238 |
|
|
|
239 |
|
|
In the top command box of the scribe authoring environment is an |
240 |
|
|
option to change the style. Flip it over to your newly created |
241 |
|
|
style and click "Apply Style." You should now see the changes |
242 |
|
|
go into effect -- the page is now using the newly created |
243 |
|
|
PageScribe Style. For the full effect, click the Preview link in the |
244 |
|
|
command box at the top of the PageScribe authoring screen. |
245 |
|
|
|
246 |
|
|
============================================================================== |
247 |
|
|
4.0 CONCLUSION |
248 |
|
|
============================================================================== |
249 |
|
|
|
250 |
|
|
LibData is not fully a content management system, and therefore lacks many of |
251 |
|
|
the features available elsewhere. However, we feel that its strengths are in |
252 |
|
|
library-centric page building, and in its open source nature. |
253 |
|
|
|
254 |
|
|
Probably the most productive customization possibilities with LibData will |
255 |
|
|
result from a collaborative effort between web designers and programmers at |
256 |
|
|
this stage. |
257 |
|
|
|
258 |
|
|
|
259 |
|
|
November 19, 2003 |
260 |
|
|
Paul F. Bramscher |
261 |
|
|
brams006@umn.edu |
262 |
|
|
University of Minnesota Libraries |