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