1 |
|
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 |