/[libdata]/trunk/admin/install/libdata_customize.txt
This is repository of my old source code which isn't updated any more. Go to git.rot13.org for current projects!
ViewVC logotype

Contents of /trunk/admin/install/libdata_customize.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 4 - (show annotations)
Fri Dec 5 18:54:49 2003 UTC (17 years, 10 months ago) by dpavlin
File MIME type: text/plain
File size: 11482 byte(s)
Initial revision

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 CSS’s (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 CSS’s (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 You’ll 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

  ViewVC Help
Powered by ViewVC 1.1.26