admin/install/libdata_customize.txt



File:   libdata_customization.txt
Title:  LibData Customization
Author: Paul F. Bramscher brams006@umn.edu
Date:   November 19, 2003


==============================================================================
TABLE OF CONTENTS
==============================================================================

1.0  Introduction
2.0  File Structure, Headers, and Footers
3.0  LibData PageScribe Styles
4.0  Conclusion

==============================================================================
1.0     INTRODUCTION
==============================================================================

The striving of many web designers has been to separate content from
presentation to the greatest extent possible.  Only limited effort toward this
end has been achieved on the LibData administration side.  It should best be viewed
as a program delivered over the web, rather than as a dynamic web page.  As such,
expectations of wide-ranging and easy modification should be more in step with
desktop applications than with flat web pages or documents.  Many of the forms
are tightly coupled with underlying logic affecting their functionality.

With web scripting environments in general there are often the tendencies to
bounce in and out of contexts (HTML, logic, or SQL) to the point that logic
structures -- particularly nested structures more than two layers deep -- become
increasingly unreadable.  So on the administrative side, particularly,
presentation customization will require some knowledge of PHP coding practices.
The approach taken here is that when the logic required to render a page is more
substantial than the HTML tagging, then it becomes fair game to "submerge" or
imbed the HTML within logic code for the sake of logic readability (rather than
ease of formatting customization).

That said, there are a still number of public (and private) pages which are easily
customizable.  Additionally, there are a few areas which require presentation
customization and these will be detailed further in this document.

==============================================================================
2.0     NOTES ON FILE STRUCTURE
==============================================================================

LibData is generally to be installed into two separate web servable directories.
One location hosts the public side environment (public LibData), the other is
(hopefully) served over an SSL port (administration LibData).  These directories
are determined at install time.  Within each are a number of files which are
quickly customizable, and contain virtually no programming code:

----------------------------------------------------
Administrative Customization under /libdata/include/
----------------------------------------------------
libdata_header.phtml
        The header file for the administrative LibData pages.

libdata_footer.phtml
        The corresponding footer file for administrative LibData pages.

scribe_header.phtml
        The header file for PageScribe/CourseLib pages.  It can be
        similar to libdata administrative above, or customized independently.

scribe_footer.phtml
        The corresponding footer file for PageScribe/CourseLib.

libdata.css
        The standard CSS definitions for use with the administrative portion
        of libdata.   Note especially that the file contains classes S1, S2,
        S3, S4, and S5.  These special style classes correspond to 5 possible
        styles during CourseLib/PageScribe page authoring.  Individual pages
        may have customized headers, footers, and CSSs (treated in the
        LibData Usage Manual), but these five are used as defaults if nothing
        else is available.  This will be explained in section 3.0 LibData
        PageScribe Styles.
        
--------------------------------------------------
Public Customization under /libdata/ (public side)
--------------------------------------------------

header.phtml
        The header file for the public LibData pages.

footer.phtml
        The corresponding footer file for public LibData pages.

libdata.css
        The standard CSS definitions for use with the public portion
        of libdata.   Note especially that the file contains classes S1, S2,
        S3, S4, and S5.  These special style classes correspond to 5 possible
        styles during CourseLib/PageScribe page authoring.  Individual pages
        may have customized headers, footers, and CSSs (treated in the
        LibData Usage Manual), but these five are used as defaults if nothing
        else is available.  This will be explained in section 3.0 LibData
        PageScribe Styles.


Both page.phtml and page_print.phtml first attempt to load a customized header
and footer.  This customized header is explained in section 3.0 LibData Styles.
If it is not defined LibData will load a default header and footer (known as
header.phtml and footer.phtml respectively).  These are unique to your
institution, and may be placed either in the LibData public directory or in your
default Apache/PHP server side include location.  They are completely
customizable and may be straight HTML if desired, contain javascript, etc.

The other files ending with a .phtml extension may be modified at will, though
certainly there is PHP code in them.  Standard best practice includes the
historical backup of files frequently or establishing a CVS code repository
system.

subject.phtml, for example, renders a Research QuickStart subject page.
Youll note that there is scant little basic HTML in it -- most of the file
is logic necessary to draw the page and dynamically generate the underlying
HTML.

==============================================================================
3.0     LIBDATA PAGESCRIBE STYLES
==============================================================================

LibData, in both the public and administrative portions, has a basic libdata.css
file (the purpose of which is detailed above).  However, this application was
designed for a Big-10 university library environment with many libraries and
special departments within libraries with their own look-and-feel.

LibData pages created through the CourseLib/PageScribe authoring environment
may reference PageScribe Styles -- these are defined on the LibData Manager
Functions console menu under "PageScribe Style."  Styles have the following
attributes:

(A)     A style title
(B)     header file
(C)     footer file
(D)     css file

The header/footer/css fields contain relative (for example,
styles/smithlibrary/header.phtml) pathing or a full http reference
(for example, http://anothersite.library.edu/header.phtml).  However,
with the CSS file we've had the best luck if the relative path
mechanism is used.

Steps to create a new LibData PageScribe (CourseLib as well) Style:

----------------------------------------------------------------
(1) Create the directory for the three files (header/footer/css)
----------------------------------------------------------------

The preferred (internal) directory location for PageScribe styles is:
/{libdata public side}/styles/{stylename}

Although these styles may be anywhere on the libdata server, it's
recommended that they are encapsulated into a unique subdirectory
since they'll include three files and any associated graphical
elements.  If, however, your styles share more common attributes than
not you may want a different structure altogether.

-------------------------------------------------
(2) Create the header/footer/css files themselves
-------------------------------------------------

There are no special instructions for the header or footer file
content -- they are totally customizable.

The CSS file may also contain anything desired.  However, it should
contain (additionally) five special CSS classes:

S1
S2
S3
S4
S5

These classes are used within a SPAN tag to render PageScribe/CourseLib
pages.  In the authoring environment, page authors may individually
tweak each page element with a number [X][1][2][3][4][5] (X corresponds to
no class, using the default body text instead).

It was discussed by the LibData design committee that we wanted to
strike a balance between a webmaster's desire for some sort of page
consistency versus author creative freedom.  So setting up the
PageScribe/CourseLib styles is a Manager function, requires unix ftp or
sftp access to physically place the files, and create the corresponding
five SPAN styles.  We've felt that after roughly five style changes a page
begins to become "messy" anyway.

One approach is to make the styles get increasingly smaller in size 
(roughly analogous to the HTML H tags).  Note that the span styles
encapsulate several attributes. For example:

.S1 {
        font-family: Arial, Helvetica, sans-serif;
        font-size: 18pt;
        color: #2F4F4F;
}

.S2 {
        font-family: Arial, Helvetica, sans-serif;
        font-size: 14pt;
        color: #2F4F4F;
}

So, unlike a full-fledged word processing environment in which a section
of text may independently contain bold, italics, underline, size, etc.
attributes, LibData limits an authored page to only five overall theme
variations.  This may be extended in future versions, or with some
relatively minor programming the current version may be extended.  We're
still investigating the balance between full-blown creative license versus
some page consistency in look-and-feel across a large site.

-----------------------------------------------------
(3) Enter the directory path information into LibData
-----------------------------------------------------

From the Manager Functions menu click to create a New PageScribe Style.

Pick a (unique) style name, and fill in the corresponding information
for the header/footer/css file locations.  Note that they are relative
to the /{libdata public side} path.

If there is a discrepancy between the actual file name and its
entry in the LibData system (see the next step), or there is a
permissions issue, the entire LibData page may fail to load.
LibData currently does no error checking at this step.  Additionally,
for security purposes most includes (except CSS files) are of the
"required" sort in PHP.  This means that the script will abort if
an included file is missing.

------------------------------------------------------
(4) Create a New CourseLib or PageScribe Page and Test
------------------------------------------------------

From either scribe_start.phtml or the main authoring console menu,
create a new CourseLib or PageScribe Page and populate it with
some page elements (for further directions here, check the
LibData Introduction file).

In the top command box of the scribe authoring environment is an
option to change the style.  Flip it over to your newly created
style and click "Apply Style."  You should now see the changes
go into effect -- the page is now using the newly created
PageScribe Style.  For the full effect, click the Preview link in the
command box at the top of the PageScribe authoring screen.

==============================================================================
4.0     CONCLUSION
==============================================================================

LibData is not fully a content management system, and therefore lacks many of
the features available elsewhere.  However, we feel that its strengths are in
library-centric page building, and in its open source nature.

Probably the most productive customization possibilities with LibData will
result from a collaborative effort between web designers and programmers at
this stage.


November 19, 2003
Paul F. Bramscher
brams006@umn.edu
University of Minnesota Libraries
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