admin/install/libdata_customize.txt

File:   libdata_customization.txt
Title:  LibData Customization
Author: Paul F. Bramscher brams006@umn.edu
Date:   March 16, 2004


==============================================================================
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.
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.


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