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