Sakai OAE Deployment and Management

Nội dung text: Sakai OAE Deployment and Management

1. www.it-ebooks.info
2. www.it-ebooks.info
3. Sakai OAE Deployment and Management Max Whitney Beijing • Cambridge • Farnham • Kửln • Sebastopol • Tokyo www.it-ebooks.info
4. Sakai OAE Deployment and Management by Max Whitney Copyright â 2012 Melissa Whitney. All rights reserved. Printed in the United States of America. Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles ( For more information, contact our corporate/institutional sales department: 800-998-9938 or corporate@oreilly.com. Editors: Shawn Wallace and Brian Jepson Cover Designer: Karen Montgomery Production Editor: Melanie Yarbrough Interior Designer: David Futato Illustrator: Robert Romano Revision History for the First Edition: 2012-06-01 First release 2012-06-14 Second release See for release details. Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of O’Reilly Media, Inc. Sakai OAE Deployment and Management, the cover image of a Lapland Longspur, and related trade dress are trademarks of O’Reilly Media, Inc. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O’Reilly Media, Inc., was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information con- tained herein. ISBN: 978-1-449-31876-5 [LSI] 1339693367 www.it-ebooks.info
5. Table of Contents Preface vii 1. Why Sakai? 1 Putting Course Materials Online 1 Collaboration 2 A Protected Space 3 The Open Source Orientation 3 2. Installing Sakai OAE 7 The Quickest Install: Web Start 7 Binary Install 8 Install Java 1.6 9 Start the Binary Up 11 Shut the Binary Down 14 Building from Source 15 3. A Whirlwind Tour 21 Choose Your Browser 21 Create Your First Account 21 Create Your Profile 23 Create a Course and a Research Project 25 Lecture Course Online Companion 25 Research project 31 Changing the Dashboard 35 The Public Face of Sakai 37 4. Making the Look and Feel Your Own 41 Configure OAE for CSS, Property, and JavaScript Changes 41 Modifying Labels in the User Interface 44 Internationalization and Localization 44 Changing the CSS: Paint It Pink 48 iii www.it-ebooks.info
6. Changing Drop Down Menus 53 Categories 56 Troubleshooting 59 Change the Landing Page 60 Changing the Sign Up and Error pages 62 Rebundle OAE 64 5. LDAP Integration 65 Set Up a Mini LDAP Instance 65 Build and Install the OAE LDAP Modules 70 LDAP Connection Service 70 LDAP Authentication Service 73 Troubleshooting LDAP Configuration Settings 78 Choose Your Configuration (and Configure It) 79 LDAP Host 80 SSLing the Connection 80 Bind User 81 Performance Considerations 81 Authorization 82 RESTful Account Creation 83 Advanced Topics: Cracking Open the LDAP Authentication Plug-in 84 Removing the Self-Service Functions 85 6. Building On 89 A Very Simple Dashboard Widget: JISC Content Browser 89 A Group Widget: Simplified Comments 91 A Complex Widget: Walking Time Map 91 7. Scaling Up 95 The Basics 95 Set Up Curl 95 Change the Admin Password 96 Outgoing Email 97 Logging 98 Create a Sakai User 98 Unix-Style Start and Stop Scripts 99 Integrating with a Database Backend 101 Choosing Your Database 101 Integrating with PostgreSQL 102 Integrating with Oracle 107 Set Up a Web Server 112 Retrieve Apache and Install Modules 113 Virtual Host Configuration 114 iv | Table of Contents www.it-ebooks.info
7. Server Protection Service Configuration 114 The Preview Processor 116 Separating Solr 117 Starting Clean 120 The Checklist 121 Table of Contents | v www.it-ebooks.info
8. www.it-ebooks.info
9. Preface A Note on Names The original Sakai software descended from work by Indiana University, Massachusetts Institute of Technology, Stanford University, University of Michigan, uPortal, and the Open Knowledge Initiative. Lots of the original code came from University of Michi- gan’s framework, known as CHEF, the CompreHensive collaborativE Framework. (Programmers do love to stretch their acronyms.) As the new shared infrastructure matured, a joke ran through the community that this was Iron Chef, a reference to the Japanese competitive cooking show. It seemed right on the surface: this collaboratively built framework was stronger, smarter, faster, and more international than any of the preceding single-institution systems. It also felt right as an observation of the commu- nity in development: programmers and academics coming together across varied in- stitutional cultures interacting in some highly formalized ways to duke it out over which implementation choice was best. Who would win the challenge? An established pro- grammer from a long-committed university or a smart upstart designer from a tiny consulting firm? The software was ultimately named for the “King of Iron Chefs,” Hir- oyuki Sakai, with hope that it would be the winningest of all education and collabora- tion frameworks. After a couple of years, an effort to rewrite the backend services was undertaken. This started out as the kernel rewrite effort, morphed into the kernel rearchitecture effort, then got clear enough that it became two separate but aligned efforts called kernel 1 and kernel 2. A major user interface redesign was undertaken at the same time, ad- dressing both the user interaction and user experience layers. Because the production version was numbered in the 2s, work on the next generation of the frontend of Sakai became variously known as Sakai 3 and 3akai (pronounced three-ak-EYE). It got mad- deningly confusing to talk about Sakai 2 on K1 as distinguished from 3akai-ux on K2. The kernel team resolved on nakamura as the name for the backend services. This name benefitted from referring both to an Iron Chef, Koumei Nakamura, and to the first Japanese national to scale K2, Shoji Nakamura. Let it never be said that Sakai pro- grammers don’t love the act of naming. vii www.it-ebooks.info
10. The name of the overarching product, of which nakamura forms one element in the framework, is the Sakai Open Academic Environment (OAE). This name primarily serves to distinguish it from the other Sakai product, the Collaboration and Learning Environment (CLE). While OAE started out conceptually as the next version of CLE it is now clear that both OAE and CLE will continue on as distinct products in develop- ment and maintenance for as long as schools and organizations find them valuable. The numeric distinction between them had become misleading. In practice, both systems get rebranded as soon as they’re deployed. Sakai instances around the world are known variously as Vula, Tusk, bSpace, and many other names, each of which is meaningful to the local community. Often it is only the technical staff that speak of CLE or OAE on a given campus. It is the branded, art-directed, living community of interaction that the students and teachers talk about. Conventions Used in This Book The following typographical conventions are used in this book: Italic Indicates new terms, URLs, email addresses, filenames, and file extensions. Constant width Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords. Constant width bold Shows commands or other text that should be typed literally by the user. Constant width italic Shows text that should be replaced with user-supplied values or by values deter- mined by context. This icon signifies a tip, suggestion, or general note. This icon indicates a warning or caution. Using Code Examples This book is here to help you get your job done. In general, you may use the code in this book in your programs and documentation. You do not need to contact us for viii | Preface www.it-ebooks.info
11. permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission. We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Sakai OAE Deployment and Manage- ment by Max Whitney (O’Reilly). Copyright 2012 Max Whitney, 978-1-4493-1876-5.” If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at permissions@oreilly.com. Safariđ Books Online Safari Books Online (www.safaribooksonline.com) is an on-demand digital library that delivers expert content in both book and video form from the world’s leading authors in technology and business. Technology professionals, software developers, web designers, and business and cre- ative professionals use Safari Books Online as their primary resource for research, problem solving, learning, and certification training. Safari Books Online offers a range of product mixes and pricing programs for organi- zations, government agencies, and individuals. Subscribers have access to thousands of books, training videos, and prepublication manuscripts in one fully searchable da- tabase from publishers like O’Reilly Media, Prentice Hall Professional, Addison-Wesley Professional, Microsoft Press, Sams, Que, Peachpit Press, Focal Press, Cisco Press, John Wiley & Sons, Syngress, Morgan Kaufmann, IBM Redbooks, Packt, Adobe Press, FT Press, Apress, Manning, New Riders, McGraw-Hill, Jones & Bartlett, Course Tech- nology, and dozens more. For more information about Safari Books Online, please visit us online. How to Contact Us Please address comments and questions concerning this book to the publisher: O’Reilly Media, Inc. 1005 Gravenstein Highway North Sebastopol, CA 95472 800-998-9938 (in the United States or Canada) 707-829-0515 (international or local) 707-829-0104 (fax) Preface | ix www.it-ebooks.info
12. We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at: To comment or ask technical questions about this book, send email to: bookquestions@oreilly.com For more information about our books, courses, conferences, and news, see our website at Find us on Facebook: Follow us on Twitter: Watch us on YouTube: Acknowledgements I received a tremendous amount of assistance in writing this book. It is a far better book because of it. Without the dedication of the entire Sakai OAE Managed Project staff, there would be no software about which I could write. I would particularly like to thank Ian Boston, Nicolaas Matthijs, Zach Thomas, and Carl Hall for taking the time over the last few years to work through the fundamentals of OAE with me, long before we even knew it was OAE; Daniel Parry for his freely available guides to the Cambridge deployments on the 1.0 and 1.1 series of OAE; Bert Pareyn for help with the CSS field guide; Scot Hacker for the WalkTime widget and pointers on widget development; Mark Walsh for pulling a functioning Oracle 11 pom.xml out of his hat. Valuable examples and advice were provided by Lucy Appert, Sam Peck, Chris Tweney, Chris Roby, D. Stuart Freeman, Oszkar Nagy, Christian Vuerings, Ray Davis, Jonathan Cook, Erik Froese, Lance Speelmon, Eli Chochran, The Githens, John King, and Michelle Hall from the Sakai communtiy and by Andy Sears, Mark Reilly, James Bullen, Jeff Pasch, Madan Dorairaj, Mark Triggs, Payten Giles, and Zach Elliott at my home department. I am grateful to Mark Dukes and Dan Burner of All Saints Company for permission to use the image of Paul Erdos from the Dancing Saints icon at Saint Gregory of Nyssa Epis- copal Church in San Francisco and to Ludovic Poitou at Forge Rock for encouragement in using the OpenDJ Directory for the authentication samples. I would like to thank David Ackerman for his foresight in championing this project from early days at NYU, and our CITO Marilyn McMillan for leading us succesfully through many a tumultuous year. My editors Brian Jepson and Shawn Wallace performed an amazing feat in turning this book out mere weeks after the OAE 1.2 release date. I am particularly grateful to Brian for seeing the value in Sakai OAE and taking on this project before we knew we’d have code. Much credit must go to Ian Dolphin, who was my original sounding board for x | Preface www.it-ebooks.info
13. the usefulness of this book. The manuscript was made more readable by the input of my reviewers: Zach Thomas, Noah Botimer, and Denise Hand. All errors are uniquely my own, as are all unintentional descents into my native tongue, unix. OAE is about enabling communities of learning. This book would not have come into existence without the constant conversation within my communities: I am grateful to Holly Hudson, Dustyn Roberts, Alexis Goldstein, Herb Hoover, Adam Mayer, Bill Ward, Raphael Abrams, Shelby Arnold, Matt Mets, Ranjit Bhatnagar, Guy Dickinson, and all the members and visitors to NYC Resistor who challenged my assumptions as I talked this book through on many a long day at our hackerspace; Stefan Lisowski, Hillary Mason, Rob Faludi, and Michael Dory provided valuable counterweights to my occasional single-mindedness; my teachers: Dennis Shasha, David Weber, Jim Val- houli, Lalith Munasinghe, Sunil Gulati, Jim Shapiro, Edmund Phelps, and particularly Mr. Charlie Deardorff and Mr. Rick Parris, who will always have the honorific with me. I am grateful to Jim Bruce, who was a key mover at MIT when I got my hands on my first mainframe account, and has honored me with his coaching these past few years. Tremendous thanks to my dearest friends Tom Igoe, Joseph Hobaica, Clive Thompson, Denise Hand, Morgan Noel, my mother Ginger Whitney, and my sisters Beth and Alicia Whitney. This work is dedicated to our Greg Sewell, the friends of whom continue to change the world. Preface | xi www.it-ebooks.info
14. www.it-ebooks.info
15. CHAPTER 1 Why Sakai? Sakai Open Academic Environment is an open source collaboration software system supporting teaching and learning at higher education institutions around the world. It is free for anyone to download, install, configure, and use. Sakai OAE brings together teachers, researchers, and students online to talk, write, and share, with the aim of enhancing the educational endeavor everywhere for everyone. Putting Course Materials Online The usefulness of an online analog to in-classroom instruction is now well established. The 1990 idea Tim Berners-Lee proposed for solving a problem of knowledge transfer among scientist cycling in and out of the European Organization for Nuclear Research has become so ubiquitous, it’s easy to forget it started somewhere. Almost as soon as Berners-Lee had a prototype of the World Wide Web working, the Fermilab Theoretical Physics Department was linking and sharing seminars on it. Individual instructors all over the world created their own web pages to support their research and teaching; pages of great effectiveness that were no more complicated than an HREF and a center tag could make them. Twenty years later, a healthy majority of instructors use some kind of learning man- agement system to support teaching and learning in the classroom, whether it is home- grown, open source, or proprietary. It can be as simple as posting the syllabus, and updating it as the term proceeds in order to reflect the pace of this particular semester’s group of students, or it can be as complicated as weekly automated quizzes, drawn from a pool of hundreds of potential questions, graded entirely by the machinery in order to monitor the level of mastery and shape the instructor’s ensuing lectures. The many tools and ancillary systems are well known now and used to great effect by in- structors, from in-class clickers to web-based grade books, SCORM modules with adaptive release features, blog post assignments with required peer response. What could be automated in the drudgery of the educational process, has been. The departmental photocopier lies largely quiet. Administrative assistants have been 1 www.it-ebooks.info
16. trimmed from the budget, and student workers are sent on ever more creative errands to earn their stipends. Much like word-processing software, the field of learning man- agement software has matured, the market has saturated. It is a “solved problem,” as computer scientists say. Relying on old tools, Sakai OAE does something new. It does not lead with tools to automate the administrative tasks around learning. There is no grade book yet written. Assignment creation and receipt functionality is in development but it doesn’t appear in the 1.2 version of OAE covered here. The heart of OAE is simple collaboration around the materials students study. Collaboration OAE is built for sharing. Every element of the system focuses back on the questions of engagement: who are students studying with? What’s the newest material a researcher has shared? Who is watching it? Who is commenting on it? From the student’s per- spective the questions are yet more personal: what do I have to get done tonight? Who’s figured out number five on this week’s problem set? Is anyone around to meet up for a study group? Where is that brilliant anthropology reading from last year, which is exactly the source I would need for this term’s business course, if I could only dig it out from all the things I read online last year? Students spend years interacting: across classes, across departments, across instructors. They go abroad and return home. They spend days in part-time jobs and unpaid in- ternships. OAE always ties them back to where they’ve been before. The university education builds one experience upon another, expanding students’ understanding of the world, then bringing them back to campus to reflect, to look inside and see how it has changed their understanding of themselves. Every experience builds on the last, inflecting, enlarging their comprehension of specific skills, of bodies of knowledge, of themselves. College, at its best, provides a framework for youngsters to become adults. A difficult task of identity formation takes place in the extraordinary years from age 17 to 22. Kids try on ideas and dispense with them just as fast. A hundred extracurricular clubs en- courage passing commitments en route to discovering deep interests and pursuing them. She tries out psychology and cognitive science before realizing she wants to be an actor after all. He delves into nineteenth century Victorian mores before resolving on the more intelligible area of combinatorics. In the fleeting window between youth and responsibility, students try on a million different selves. When they do this on the public Internet it becomes, all unwitting, a part of their permanent record. The impact is sufficiently real that Germany has legis- lated against considering information on social media sites like Facebook in employ- ment decisions, and the United States is now considering similar rules. Where it may not be possible to draw a straight line between a moment of misspent youth and a 2 | Chapter 1: Why Sakai? www.it-ebooks.info
17. lifetime of employment discrimination, there is a chilling effect of knowing everyone will know everything, in perpetuity. Do students get locked in to an identity they would otherwise shed because to be seen to flip-flop, to flim-flam, is too terrifying to their social selves? A Protected Space In this context, OAE is an ivory-towered social network. Here is a space where students can learn the risks and benefits of sharing themselves electronically, while not being permanently burdened by errors made in the process. Learning involves failure first. OAE can be a place to fail safely, a social network still inside the supportive structure of the university. Everyone, even grandparents, are online socially. Connecting to Facebook or to Twit- ter, taking just a quick peek at Orkut, is both extraordinarily gratifying and wildly distracting. Old friends, left behind, are still there, fresh and eager to hang out. There too are parents, former teachers, ex-boyfriends, grandpa, that kid from the show you did in tenth grade. Public social networks provide bright easy access to current peers and present teachers, but they also bring forward everyone a student has ever known. What was meant as a quick check-in with a classmate before recitation swiftly veers off into an instant message marathon with the girl back home. Much like the campus quad or the student center, OAE provides the immediacy of a social network, but partitions it to permit students to focus on their current studies. Home will always be a click away, but when they want to turn their attention to their present schooling, OAE provides a wall to protect them. Distractions can be quieted while they focus on their work. Faculty are accessible to their students in OAE without having to commingle their private and professional lives. Teaching is highly personal. To know where to prod a student is to know where they are, how they are, what motivates them, what is just on the edge of their current understanding. The intensity of that engagement can be ex- hausting to maintain at all times in all environments. Marking OAE as a designated place to be available to students, like posting office hours, presents an opportunity for the best engagement, balancing accessibility with boundaries. Public social networks can be where faculty visit with friends and far flung colleagues. OAE then is the online equivalent of campus—when you arrive there, you are present to teach and to learn. The Open Source Orientation OAE, the open academic environment, is an open source system issued under the Apache license, version 2.0. It has been built by a consortium of higher education institutions across the globe, under the auspices of the Sakai Foundation. None of the people working on building OAE know what it will be when it is done. Everyone reading this book will become a contributor. By asking questions, testing scenarios, by simply The Open Source Orientation | 3 www.it-ebooks.info
18. deploying the software, and seeing how your students use it, you will be changing the shape of the software to come. In a direct way, this book will show you how to customize OAE. You’ll get a tour of the skinning infrastructure, changing the look and feel of the system. You’ll install a few sample widgets, expanding the functionality of OAE to suit your local needs. Widgets can be written by anyone. They can stay highly customized and very local, or they can be abstracted and contributed back to the OAE community of schools via the Widget Library. A widget can be a small static tool, greeting each person by name when they log in. It can be an institutionally important workflow such as a widget being built at NYU to seamlessly take in video content in OAE, pass it off to a separate video repository where it is compressed and encoded, and return a permanent link in the OAE environment, without ever distracting the person who is preoccupied with up- loading film of their cat. Cats on the Internet are an area of valuable study, as evinced by Ethan Zuckerman’s 2008 Cute Cat Theory presented at the O’Reilly Emerging Technology Conference. The source code for OAE is public. If you find a bug, you can fix it. For people who have worked in open source before, this is not such exciting news, for those accustomed to proprietary vendor code it is a sea change. The code is managed on Github, with a team of core programmers committing changes on a daily basis. You can issue a pull request and know someone will look at it and give you feedback. Running an open source system does not mean being out on your own. The Sakai community has a large number of commercial affiliates, ranging from cloud source service providers to custom development teams. Longtime service providers like Long- sight, Unicon, rSmart, and Sungard Higher Education provide a deep technical bench for schools starting new with Sakai products. Aeroplane Software and Hallway Tech- nologies have established practices extending and customizing OAE for particular sit- uations. Wiley Higher Education, IBM, Oracle, and Blackboard all contribute to Sakai, demonstrating a belief in the value and viability of this open source academic environ- ment. The Sakai community of educators, programmers, and administrators provide a wealth of freely available insight. The mailing lists are active day and night. As an international community, it’s always daytime somewhere, and programmers never sleep. Sakai OAE is not a revolution in education technology. The groundbreaking innova- tions of the 1990s are now all familiar. Rather, OAE builds on two decades of web experience to reduce the complexity presented in an LMS. In repackaging familiar tools, it makes them into something else. The strict top-down hierarchy of the traditional LMS is shed. OAE is only just what it needs to be in order to serve its community of teachers, students, and scholars. It is a framework for sharing, collecting, and 4 | Chapter 1: Why Sakai? www.it-ebooks.info
19. remembering. It is a system in which many voices can work on an idea, until it becomes a single shared concept. It can be a series of private islands, or a pangaea connecting everything. As Antoine de St. Exupery observed about airplane engineering—great de- sign is “not when there is no longer anything to add, but when there is no longer anything to take away.” The Open Source Orientation | 5 www.it-ebooks.info
20. www.it-ebooks.info
21. CHAPTER 2 Installing Sakai OAE Sakai OAE provides installations ranging from a kick-the-tires demonstration system to a fully customizable and rebuildable set of source files. This chapter covers three installations models: Web Start The Java Web Start installation downloads Sakai OAE and everything needed to get it running in a demonstration format. Web Start is a good choice if this is your first encounter with Sakai OAE. Java Web Start is the absolute fastest way to get a look at OAE’s features. Binary Jar The compiled Sakai OAE jar can be downloaded and run using Java on a Linux, Mac, or Windows system. The binary is a fully functional instance of OAE. To run a small pilot with a handful of users, this is a fast and simple method of getting started. The binary install includes the default look and feel and employs the Apache Derby database. Customizable Build When you’re ready to start customizing and scaling OAE, build the frontend and backend code. The buildable code relies on maven, and on the 3akai-ux and naka mura repositories for customization work. The 3akai-ux repository contains fron- tend code for customizing the look and feel of OAE. The nakamura repository has the backend code for integrating LDAP as an authentication system, and for setting up on other databases such as PostgreSQL and Oracle. The Quickest Install: Web Start To get started fastest, use the Java Web Start version of the software. Java Web Start lets you get a quick look at the system before installing the full application. Use the browser of your choice to connect to 7 www.it-ebooks.info
22. In the “Downloads” section of the Sakai OAE page, there’s a section titled “OAE 1.2.0 Web Start (one-click download/run for Demos).” Click the link there to connect to Depending on the configuration of your computer, you may be prompted to let Java run. The Java Web Start system ensures that OAE runs in the correct Java version and that it is segregated from other parts of your computer. The initial download will be quite quick, as it is just grabbing an XML file. Give your computer a minute to download and start the application up. You’ll get a challenge once it’s finished initializing, since the Java Web Start version of Sakai OAE carries a self-signed certificate. As this is a demonstration system, it’s okay to click through the self-signed certificate warning. The Web Start launcher includes a disclaimer that this version of the install is not meant for production. You won’t be able to use the email functions or a handful of other functionality. Click the Launch button. Web Start notifies you that Nakamura has been started but it takes a little while to get running. You can close that message without impacting anything. Go ahead and twiddle your thumbs for a minute or two, or do a couple rows of knitting or sudoku. Once Nakamura has started, the Launch screen changes to indicate that Nakamura is running, and the Open Sakai OAE button becomes enabled. Go ahead and click it to start OAE now. Your web browser will open and connect to (See Figure 2-1.) You have achieved Sakai OAE. Congratulations! Head on over to Chapter 3. When you’re ready to shut the system down, come back to the Java Web Start window and click the Exit button. This will shut the system down. If you try refreshing the browser window, you’ll get an unable to connect error, since now there’s nothing to connect to. You can start the Java Web Start version again any time by executing the sakaioae.jnlp file. Binary Install Installing a regular small scale instance of Sakai OAE really isn’t much harder than using the Java Web Start version. Use the browser of your choice to connect to In the “Downloads” section of the Sakai OAE page, in the section titled “OAE 1.2.0 Binary,” click the link to open the folder at .2.0/binary/. Download the binary Java archive published there with the name org.sa- kaiproject.nakamura.app-1.2.0.jar. You can store the binary anywhere on disk and run it from that location. For convenience, drop it in a folder named binary in your own home directory (e.g. /users/username/binary). Later on, when you build the code from scratch, you’ll want to have a source directory to keep everything straight. 8 | Chapter 2: Installing Sakai OAE www.it-ebooks.info
23. Figure 2-1. The Web Start OAE If your preferred web browser is the command line, you can grab the OAE jar using curl. The curl browser is a great way to interface with the REST services OAE provides, making it the go-to tool for many OAE administrators. You can grab a copy of curl from if it’s not already on your system. (More information on curl is in Chapter 7.) To download the Sakai OAE jar using curl: curl -O \ org.sakaiproject.nakamura.app-1.2.0.jar You can check that the file downloaded cleanly by comparing the md5 and sha1 check- sums. For another layer of certainty, you can also check the GPG signature. Install Java 1.6 Sakai OAE is built on Java. Test scripts and some subsystems are made available in- dependently and rely on Python or Ruby, but for a basic binary installation, your only dependency is Java. Sakai OAE is certified on Java 6. You can see if Java is already installed and check the version at the command line: java -version Binary Install | 9 www.it-ebooks.info
24. If you receive something to the effect of the following output, then you are good to go: java version "1.6.0_29" Java(TM) SE Runtime Environment (build 1.6.0_29-b11-402-10M3527) Java HotSpot(TM) 64-Bit Server VM (build 20.4-b02-402, mixed mode) The first two digits of the version number are the relevant ones. “1.6” means you have version 6 installed and accessible. Java versions of 1.5 or (gasp) 1.4 need to be upgraded before you run the Sakai OAE binary. OAE hasn’t been tested with 1.7 yet, so you may get some hiccups with a later version of Java than 6. Each operating system will have its own foibles for getting to Java 6. Here’s a thumbnail for some major OSs. Ubuntu To install Java 6 on Ubuntu, use apt-get at the command line: sudo apt-get install openjdk-6-jdk Note that you need to have sudo rights, or to have another way to become the root user, in order to install Java system-wide. If you don’t have, or shouldn’t reasonably get, root privileges then ask your system administrator to set up Java 1.6 for you. Other flavors of *nix have their own package management strategies. Use the one you’re most familiar with; apt-get has no particular strength over yum, apt4rpm, or any other package management tool. Mac OS X On a Macintosh, versions 10.5 and 10.6 are likely to have Java preinstalled. To get the latest version of 1.6, either run Software Update, or connect to downloads and use the phrase “Java SE 6” with your operating system version number to find the correct update to download. If you’ve got more than one version installed, use the Java Preferences tool to make Java SE 6 the first version to try. If you prefer the command line, on 10.6 you can force the CurrentJDK to point to version 1.6: cd /System/Library/Frameworks/JavaVM.framework/Versions sudo ln -shfv 1.6 CurrentJDK then check it again: java -version In version 10.7 and later, Java has to be installed from the Apple support site at sup- port.apple.com. It no longer comes prebuilt with the operating system. Windows Oracle provides instructions for installing Java version 6 on Windows at .oracle.com/technetwork/java/javase/downloads. Download and run the executable for your operating system (e.g., jdk-6u32-windows-x64.exe for 64-bit Windows). By 10 | Chapter 2: Installing Sakai OAE www.it-ebooks.info
25. default, the downloaded Java will install in the location C:\Program Files\Java\jre6\. Check it at the command line with: cd C:\Program Files\Java\jre6 .\bin\java -version Be careful to distinguish this from the default version of Java for your system, which will remain the version returned by: java -version java version "1.7.0_01" Java(TM) SE Runtime Environment (build 1.7.0_01-b08) Java HotSpot(TM) 64-Bit Server VM (build 21.1-b02, mixed mode) If you’d like to make version 6 the default for a command session, set your PATH to look to the Java 6 bin directory before any other: set PATH=C:\Program Files\Java\jre6\bin;%PATH% java -version java version "1.6.0_32" Java(TM) SE Runtime Environment (build 1.6.0_32-b05) Java HotSpot(TM) 64-Bit Server VM (build 20.7-b02, mixed mode) The PATH setting is specific to the current command executable, so exiting and starting a fresh command will revert to the default Java version. Start the Binary Up No time like the present to set up a minimal start script. Create a new shell or batch script, depending on your operating system. Sakai OAE needs a bit more room than the reasonable defaults assumed by java. Specifically: -Xms512m Start java with an initial memory allocation pool of 512 MB -Xmx1024m Let the memory allocation pool grow up to 1024 MB if needed -XX:MaxPermSize=256m Assign 256 MB for the permanent generation pool, where classes and associated metadata are stored On Mac and Unix/Linux environments, create a file with the name startup.sh in the same directory as the .jar file: #! /bin/sh java -Xms512m -Xmx1024m -XX:MaxPermSize=256m -jar org.sakaiproject.nakamura.app-1.2.0.jar 1> run.log 2>&1 & SAKAI_PID=$! if [ -f OAE.pid ] Binary Install | 11 www.it-ebooks.info
26. then rm OAE.pid fi echo $SAKAI_PID > OAE.pid The *nix style script captures the process ID and writes it to a file named OAE.pid, which the shutdown script will use later to identify which process to stop. Make the start script executable: chmod +x startup.sh On Windows, create a file with the name startup.bat in the same directory as the .jar file: @echo off set PATH="C:\Program Files\Java\jre6\bin";%PATH% java -Xms512m -Xmx1024m -XX:MaxPermSize=256m -jar org.sakaiproject.nakamura.app-1.2.0.jar 1> run.log 2>&1 & Windows doesn’t use the process ID model of Unix. Instead, this startup script can be called by double-clicking on it. The OAE system can be stopped either by closing the command window, or by using Task Manager. Start OAE with your spanking new start script by calling ./startup.sh at the command line or by double-clicking startup.bat. The console output will go to a file named run.log in the binary directory. On Mac and Unix/Linux platforms tail the run.log to watch the system start up. When you lose interest, you can cease to tail the log by clicking Control-C. That’ll cancel your tail process and return you to the command line: tail -f run.log If you are running the system on an underpowered shared server or if your own little machine is really little, it may take a bit longer to start up. When you see the log entry *INFO* [main] Startup completed understand that is a programmer’s truth, which is equivalent to a layman’s barefaced lie. The statement that startup has completed means the startup script has finished what it considers to be its work: kicking off the start of the system. All those wiggly details about cacheing CSS and loading up the database for the first time have yet to finish. So, consider going to have a nice cup of tea and coming back in five minutes. Or turn to Chapter 1 and read it now. We know you skipped straight to the install chapter; it’s okay! That was the right choice, because now you have something to go back and read while OAE initializes for the very first time: *INFO* [main] Installing new launcher: jar:file:/Users/username/binary/ org.sakaiproject.nakamura.app-1.2.0.jar!/resources/ org.apache.sling.launchpad.base.jar, 2.3.0 (org.apache.sling.launchpad.base.jar. 1337036455648) *INFO* [main] Loading launcher class org.apache.sling.launchpad.base.app.MainDelegate from org.apache.sling.launchpad.base.jar.1337036455648 *INFO* [main] Starting launcher *INFO* [main] HTTP server port: 8080 *INFO* [main] Startup completed 12 | Chapter 2: Installing Sakai OAE www.it-ebooks.info
27. To find out when OAE is really done loading, watch the sling error log. Because one of the things Sakai OAE initializes on its first run is the sling directory structure, this may take a minute to come into existence. If you get the message No such file or direc tory give it a little breathing time and then try again. For Unix style systems, you can tail the log as it runs: tail -f sling/logs/error.log When the sling error log stops throwing lines the system really is up and running. The ultimate line of the startup process is Felix’s startlevel changed message: *INFO* [FelixDispatchQueue] org.apache.felix.framework FrameworkEvent STARTLEVEL CHANGED Now connect your browser to It will look the same as the Java Web Start version of the software, but it’s a fully functional system now. A Quick Domain Name Fix At this juncture, attempting to connect to your machine under a proper domain name will be a bit underwhelming. Connecting to a fully qualified domain name will display the top bar of OAE and then stop rendering. The Server Protection Service, discussed more thoroughly in Chapter 7, limits OAE’s exposure to cross-site scripting attacks. Out of the box, it’s configured explicitly for localhost. If you cannot, for whatever reason, access your OAE instance under the loopback network interface at localhost:8080, you’ll have to take a quick dive into the innards of the OAE OSGi framework. To hack up this quick fix, replace yourdomain.edu with the actual domain name for your system in the following steps: 1. In a web browser, open When prompted, login with the username admin and the password admin. 2. Scroll down and click the component named Sakai Nakamura :: Server Protec tion Service to open its configuration panel. 3. For Trusted Hosts, replace: localhost:8080 = with: yourdomain.edu:8080 = Click Save. 4. Quit and restart your browser application. Now accessing will properly display the landing page for OAE. You must quit and restart your browser because the admin credentials are cached in your browser. Once you log in as admin, you can’t just log out. Binary Install | 13 www.it-ebooks.info
28. It works! Of course, it looks just the same as the Web Start version, so this may not feel quite as exciting as you’d like. Rest assured that this is meaningfully different. Shut the Binary Down On *nix systems, for completeness, create another shell script—this one with the name shutdown.sh in the same directory where you created the startup.sh script. This script reads the process id from the file created by the startup.sh script and kills that process with extreme prejudice: #! /bin/sh if [ -f OAE.pid ] then SAKAI_PID=`cat OAE.pid` kill -9 $SAKAI_PID rm OAE.pid else echo \ "No pid file found. Run 'ps -ef | grep nakamura' to identify the process to kill." fi Make the shutdown script executable: chmod +x shutdown.sh and shut OAE down: ./shutdown.sh It doesn’t hurt to do a quick process check after shutting down to make sure you have killed OAE: ps -ef | grep nakamura If all you get in response is the grep nakamura process itself, then you know OAE is shut down. On Windows, use the Task Manager to shut down OAE. Right-click on the cmd.exe process associated with the startup.bat script and click End Task. If you end up with multiple OAE instances running at some point, you’ll get some confusing logging in the sling/log/error.log file. The first instance launched will have a hold on port 8080, so anything you do in a web browser will happen in the environment of that instance. If you unintentionally start up a second (or third, or fourth) instance of OAE, things will look normal on startup in the log associated with that instance, but when you click something in the web browser, you won’t see any associated trail in the error.log file. If you’re not getting the expected log entries, make a process check of your first triage step. Now you’re ready to take a whirlwind tour in Chapter 3. 14 | Chapter 2: Installing Sakai OAE www.it-ebooks.info
29. Building from Source You may already be familiar with Sakai OAE, or have finished the whirlwind tour and are ready to customize OAE to suit your school or organization. You’ll need the source code, the Maven build manager, and an installation of Java 1.6. Be warned heading in to this section, that while it’s one of the shortest sections, it may take the longest to complete. Depending on the speed of your network connection, and whether you already have a pile of useful stuff in your Maven repository, this build may take anywhere from 20 minutes to 5 hours. An hour is about standard for a stateside university on-campus connection. If you’re working in an environment that meters your data usage, go someplace else for your first build. If you’re planning to run this install over free city wireless in a beautiful pocket park, don’t. Go get up close to an Ethernet cable. If your roommate is playing World of Warcraft, suggest she go check out the big room with the blue ceiling for a couple of hours. The bulk of time and bandwidth in the initial build is used in retrieving artifacts for the Maven repository. Once you have them, builds will be relatively quick and extremely rare. Most of the work of customization is done live in the source files, or through configuration in the Sling OSGi web console. After the initial build, you’ll do a major build again only when you’re ready to redeploy a production jar tweaked to suit your school. On in the section OAE 1.2.0 Source, there are four links to the four parts of the OAE system: Frontend The 3akai-ux frontend code, including JavaScript, HTML, and CSS files. This is usually referred to as the sakai-ux code, and you’ll rename it to that in the example code, but you may occasionally hear people say three-akai when talking about the frontend code (see the Preface). Backend (Nakamura) The backend code. Much of the backend gets pulled down from other open source projects during the build process. Nakamura is Java code, built on the OSGi framework. sparsemapcontent An open source sparse hash column oriented data storage layer. If you configure your system to use an Oracle database for storage, you’ll need to bundle the Oracle drivers with sparsemapcontent. solr Customized solr configuration for searching. Solr is bundled and configured with nakamura. The separate repository provides tools for setting up a stand alone solr server in a multinode architecture. Building from Source | 15 www.it-ebooks.info
30. These subsystems were all tagged and tested together for the 1.2.0 release. The core elements, nakamura and 3akai-ux, show the 1.2 tag. The supporting elements, spar- semapcontent and solr, are on a slightly different schedule, so they’re tagged at 1.3.4 and 1.4.2 respectively. The source code for Sakai OAE is managed by git, shared on github.com. Later on, if you want to start contributing to the project, you can get set up with your own forks of the shared repositories. For now, download ZIP files of the code, so you can get started on basic customizations. For most of the customization covered in this book, you’ll only need the sakai-ux and nakamura sources. 1. Create a directory, parallel to your binary directory, where the code will go. Call it source. 2. Connect to the link for the frontend code: ux/tree/3akai-ux-1.2.0. This is the user interface code, and includes the files you’ll need for skinning Sakai OAE to look like it belongs at your school. Click the ZIP button to get a copy of all the frontend code for this tag. Save it in your source directory. 3. Connect to the link for the backend nakamura code: project/nakamura/tree/nakamura-1.2.0. This is the backend code, and includes the files you’ll need for integrating and scaling Sakai OAE. Click the ZIP button to get a copy of all the backend code for this tag. Save it in your source directory. The source code downloaded from Github is just one part of the whole which is OAE. The frontend source is 17 MB, and the backend just 7.5 MB. The bulk of backend source comes from other open source projects. Once built, the frontend code grows to 168 MB and the backend code consumes 280 MB. You’ll need one more piece, the maven build system. Sakai OAE 1.2 needs a minimum Maven version of 2.2.1. Check if you have it installed already and what version you’re on: mvn -version Apache Maven 2.2.1 (r801777; 2009-08-06 15:16:01-0400) If you don’t have at least version 2.2.1, download it from download.html. If you’re on Ubuntu, you can do a quick: apt-get install maven2 On Windows, be sure to set the environment and user variables as described on the Apache Maven download page. You’ll also need Java version 1.6: java -version java version "1.6.0_31" If you didn’t get Java 1.6 set earlier in this chapter, pop back to “Install Java 1.6” on page 9. 16 | Chapter 2: Installing Sakai OAE www.it-ebooks.info
31. 1. Unzip the frontend and backend elements of the Sakai OAE source code. 2. On Mac and *nix use the unzip command: unzip sakaiproject-3akai-ux-3akai-ux-1.2.0-0-ga27a5b1.zip unzip sakaiproject-nakamura-nakamura-1.2.0-0-g33d7e98.zip On Windows, double-click the ZIP files to unzip them. 3. Move both directories over to more humane names. On Mac and *nix, use the mv command: mv sakaiproject-3akai-ux-e993f00 sakai-ux mv sakaiproject-nakamura-6407909 nakamura On Windows, do the same with the rename command: rename sakaiproject-3akai-ux-e993f00 sakai-ux rename sakaiproject-nakamura-6407909 nakamura Change into the sakai-ux directory. In this location there is a pom.xml file which con- trols the Naven build for the frontend code. Maven looks to the pom in the working directory for its marching orders, so by calling Maven here you build the UX: cd source/sakai-ux mvn clean install The UX code is largely self-contained. It relies on a handful of external systems, but all in all it’s pretty concise. Building the UX takes under ten minutes on a nice high band- width pipe. The primary output artifact of the UX build is a jar called org.sakaipro- ject.nakamura.uxloader-1.2.0.jar. Once it’s built this .jar gets dropped into your Maven repository, from whence the backend build collects it: [INFO] Installing org/sakaiproject/nakamura/org.sakaiproject.nakamura.uxloader/ 1.2.0/org.sakaiproject.nakamura.uxloader-1.2.0.jar [INFO] Writing OBR metadata [INFO] [INFO] Reactor Summary: [INFO] [INFO] Sakai 3 UX Loader Wrapper SUCCESS [1.051s] [INFO] Sakai 3 UX File Hasher SUCCESS [4.780s] [INFO] Sakai 3 UX Loader SUCCESS [38.168s] [INFO] [INFO] BUILD SUCCESS [INFO] [INFO] Total time: 45.027s [INFO] Finished at: Wed May 23 22:06:23 EDT 2012 [INFO] Final Memory: 10M/161M [INFO] To build the backend code, change into the nakamura directory and issue a build com- mand from there. The backend is substantially larger, relying on signficant external frameworks to achieve its goals. Because of this, the memory allocated to Maven to do Building from Source | 17 www.it-ebooks.info
32. its work may need to be expanded before you build nakamura. This is done by setting the MAVEN_OPTS environment variable: cd source/nakamura export MAVEN_OPTS="-Xmx256m -XX:PermSize=256m" mvn clean install This’ll take a while. Go get a coffee or a sparkling water. Or read some xkcd (say for example number 303). You’re looking for a response like: INFO] Sakai Nakamura :: Launchpad Standalone Java Application SUCCESS [35.068s] [INFO] [INFO] BUILD SUCCESS [INFO] [INFO] Total time: 30:52.469s [INFO] Finished at: Wed May 23 22:23:29 EDT 2012 [INFO] Final Memory: 55M/178M [INFO] To Run as Root or Not? Really, you don’t want to run Sakai OAE as root. Why would you? Root can do any- thing. Even acknowledging that on a zone or a virtual machine the root user can be oddly restricted such that the impossible occurs and there’s something root can’t do, that’s not an excuse to get sloppy. The easiest thing in the world to do is to let Sakai OAE run as root. You’ll never run into permission problems, and you’ll have access to all the things. However, OAE will run with all the rights and privileges available on the whole box, and that may end up squeezing out other services. Like for example, login or ls. The safest choice is to set up a sakai user just for running this software. Alternatively while you’re sorting things out, run the system under your own userid. Then, when OAE bumps up against a permission or resource limitation, you’ll know about it and can make an informed choice about how to increase resources or rights. Running as root means the first time you might hear of a problem is when the Sakai OAE installation takes your server down. If up until now you’ve blithely been working through things while root, this is the moment to go straighten that all out. Make a sakai user, or commit to having your personal user id be sakai for a little while. Change the ownership of the source directory and its contents to the more limited user. 18 | Chapter 2: Installing Sakai OAE www.it-ebooks.info
33. The source build comes with its own start script for Mac and *nix environments, so this time you don’t have to create one. Call it from the nakamura directory with: ./tools/run_production.sh & Take a look in the sling log to make sure it finishes starting up before you try to connect with a browser: tail -f sling/logs/error.log On Windows, there’s a script as well this time, the run_debug.bat script in the tools directory. Somewhat unusually for Window, run this from the command line in the nakamura directory: .\tools\run_debug.bat OAE logs directly to the command session from the run_debug job. Once you see: org.apache.felix.framework FrameworkEvent STARTLEVEL CHANGED open OAE up in your browser to make sure everything looks right before you start making changes: If the page looks like our beautiful and now familiar brand-spanking-new OAE, then you’re good to go. See: short section—large chunk of your day. Building from Source | 19 www.it-ebooks.info
34. www.it-ebooks.info
35. CHAPTER 3 A Whirlwind Tour OAE doesn’t come with a user manual any more than Facebook, Google+, Orkut, or RenRen do. The user interface for the students, faculty, and researchers is designed to be straightforward after a bit of poking around. Local communities are left to develop their own customs without direction from the software creators. This whirlwind tour exposes you to the key areas around profiles, courses, permissions, and content before sending you to the backend to customize them. If you’d prefer to click around and discover the system for yourself, by all means do so, then head to “Building from Source” on page 15 to start changing things up. Choose Your Browser OAE is designed to be browser agnostic, supporting as many browsers as possible, degrading gracefully when it runs in an unfamiliar browser. Testing targets the two most recent versions of Mozilla Firefox, Microsoft Internet Explorer, Google Chrome and Apple Safari at the time of a release. For OAE 1.2, released on April 25, 2012, this means: • Mozilla Firefox 11 and 12 • Microsoft Internet Explorer 9 and 10 • Google Chrome 17 and 18 • Apple Safari 4 and 5 Create Your First Account Whether you’re working with the Web Start version, downloaded the binary, or deci- ded to get down with Maven builds before looking around, let’s get you in the system now. You’ll see a link at the top of your browser to Sign Up. This takes you to 8080/register where you can set up your account (see Figure 3-1). The demonstration 21 www.it-ebooks.info
36. text is a tribute to Hiroyuki Sakai, the greatest of the great Iron Chefs. We’ll assume you know how to enter (or make up) your name, email address, preferred username, and password. If you enter a username that’s already taken, you’ll see a little red x appear in the text entry field. As user number one, the only names you can conflict with are the demonstration username hiroyuki or the administrative account admin. Figure 3-1. The sign up screen Account creation integrates the reCAPTCHA system from Carnegie Mellon, now run by Google, to reduce the likelihood that spambots will invade your system. A captcha is a Completely Automated Public Turing Test To Tell Computers and Humans Apart. Technically it’s a reverse Turing test, as the test asks you to convince a computer that you are a human, whereas the original Turing test asked a computer to convince a human that it also was human. Humans are, as of this writing, far more adept at de- tecting words in images than computers are, so many captchas rely on this difference in ability to sort people from bots. A core technical principle of OAE is that wherever possible OAE will adopt well written open systems instead of rolling its own. Inclusion of reCAPTCHA embodies that prin- ciple while simultaneously helping to transcribe old books and newspapers. If it turns out that you are no better than a computer at discerning the words displayed, use the reload button (the two arrows in a circle) to ask for another. 22 | Chapter 3: A Whirlwind Tour www.it-ebooks.info
37. Once you’ve created your account, OAE will automatically log you in and take you to your default dashboard. The reCAPTCHA system relies on a web service running at Google. If you’re setting up Sakai OAE off network, or have a highly restricted firewall sysystem, the interactive version of user creation will fail as it tries to connect to recaptcha.net. If you are fully offline, the registration page at will halt without an indication in the error log of what has failed, though you may see your browser at- tempting to contact recaptcha.net or google.com. If your network con- nection passes through a highly restricted firewall, the registration page will load in your browser but there will be no reCAPTCHA challenge at the bottom of the screen. In this case, clicking the Create account button will reload the page without actually creating the account. Create Your Profile Let’s start with you who are. Your personal profile is accessed by clicking on My profile in the lefthand navigation panel on the dashboard screen, or by selecting My profile from the drop-down menu accessible from the word You on the top navigation. By default, there are three sections to every person’s profile: Basic information, About me, and Publications. The Basic information section shows the information you added when creating your account: First name, Last name, and Email. People can also provide a Preferred name in addition to their formal first name. For roster and grading purposes, a school may need to populate and maintain the official name values for each profile. The preferred name allows each person to indicate what they will answer to, and allow that to be easily tracked against the official names by their instructors. The Role/position list defaults to an interesting amalgamation of university roles in English speaking coun- tries, including the States, the UK, Australia, and South Africa. The role Faculty got dropped from the default list; it was confusing permission conversations due to the differing meaning of the word in two of the contributing countries: in the U.S. a faculty member is a teacher and researcher; in South Africa the faculty is an area of study or a college. No worries though, you’ll be able to change the default listing when you’re ready to customize. See “Changing Drop Down Me- nus” on page 53. Tags and categories in the Profile can be edited in two ways: from the List cate gories pop up selection screen, or by typing directly in the text entry area. The cate- gories listed by default are drawn from departments and areas of study common in the Create Your Profile | 23 www.it-ebooks.info
38. Sakai community institutions. It is by no means exhaustive, and like the Role/posi tion values can be updated to reflect your institution’s departments. Direct text entry in the tags section gets at the more interesting case, what Thomas Vander Wal captured as “folksonomies” back in 2004. No system configurator or committee of configurators will think of the magic word that best describes you to your new community. If they could, next term the first year students will certainly reject it as overused and insufficiently unique. Free text entry allows people to tag their profiles with the specific ideas and descriptors they want people to know them by. If a tag closely resembles one of the prepopulated categories, that category will be suggested as you type. Let’s go with something certainly not in the default category list: the world de- stroying villain of Dr. Who: “daleck.” Figure 3-2. My Profile Basic information, tagged with “daleck” The About me section is the essay section of the personal profile. The material you enter here is intended to be digested by readers rather than indexed by OAE. There’s no formal limit on how much text you can enter. The text entry boxes are kept small to encourage conciseness. To make yourself easily findable based on one of your interests or hobbies, it’s best to enter it on that first Basic information screen as a tag rather than, or in addition to, the About me essays. 24 | Chapter 3: A Whirlwind Tour www.it-ebooks.info
39. The final profile section Publications is the most formal, and the one most indicative of OAE’s core academic mission. Basic bibliographic fields are assumed in the out-of- the-box install of Sakai OAE, but these can be updated to reflect your institution’s established standards. Last, add a photo to your profile. Chances are your first year students will do this before they do anything else. To upload an initial photo, click on the silhouette image over your name in the upper-left of the dashboard view, then select Change picture. You’ll need to use an image that is stored locally on your computer, in JPG or PNG format. OAE is not yet configured to pull images from web sources or avatar hosting services. The image you start with need not be square nor any particular size. The crop and preview tool allows you to trim it before displaying it in your profile. To change the size of the trimmed image, click and drag a corner or edge of the highlighted area. To start over with a fresh selection box, click on the image anywhere outside the selection. The image will return to its normal coloration. When you’re happy (or at least have reached a minimum of disatisfaction) with your profile image, click the Save new selec tion button. The picture over your name will update to display your new profile image (see Figure 3-2). Now that you’ve shared some information about yourself, create your first site. Create a Course and a Research Project People learn in different ways. Some are autodidacts, absorbing material they encounter with minimal exchange with other learners or with instructors. Some are social learners, engaging the material by engaging with others. Any given person might be both an autodidact and a social learner depending on the topic, or on their level of mastery. Hans needs lots of conversation with experienced programmers to grasp the trade-offs among sort algorithms. Gretel needs a quiet room and a pile of problem sets to get a handle on partial derivatives. Sakai allows you to tailor your project to accommodate different approaches to learn- ing. Here we’ll take a quick look at creating sites to support models at each end of that spectrum. Lecture Course Online Companion From the Create & Collect drop down menu at the top of the browser window, choose Create a course. Choose the Mathematics course template by clicking the associated Use this template button. This template is provided with Sakai OAE as an example of one way to structure a traditional lecture course. Enter a title for the course, say, Partial Derivatives for Dunces. The suggested URL is set to the course title once spaces and special characters are swapped out with something more URL-friendly. If you enter a course title that matches a URL already in the system, OAE will let you know and you can enter an alternative. Create a Course and a Research Project | 25 www.it-ebooks.info
40. The URL stays the same through the life of the course in Sakai OAE. You can pop it in an email, on Twitter, or jot it on a napkin and know that students will be able to find the site consistently. The description you enter here displays whenever someone browses a listing of courses in OAE. You can assign a tag or a category (or many of both) to the course, just the way you did to your profile. The same tags and categories are used in both places, so if you tagged yourself a daleck on the profile page, you can tag your course the same here. The partial derivatives course is a prerequisite for the pre-med program, so assign it the category Medicine and Dentistry→Pre-clinical Medicine. There are three levels of publicity you can give to your new course site. You can make the course’s existence completely public; this is, unsurprisingly, the public setting. Anyone who can get to your installation of Sakai can find out the course exists. They won’t necessarily be able to see what is in the course; that is controlled by the mem- bership settings. Another option is to make the course visible only to people who have accounts and have authenticated to Sakai, the Logged in users setting. This is akin to putting up a poster in your college’s student center or inside the library building. Only members of your community can see information about it. The third option is to make the course invisible to anyone who isn’t a member of the course. This one—the par ticipants only setting—is the sharing equivalent of “ain’t nobody’s business but my own.” You might want to keep your course invisible if it’s a proposed course that may not make it past the curriculum board this semester or if you have an over-eager student body who will deluge you with requests for access as soon as they know you’re teaching remedial calculus. Which brings us to the last setting: membership. Sakai OAE supports three models of enrollment management by default: totally casual, totally controlled, and upon approval. The setting People can join automatically lets anyone with an account join the course at will. If they’re interested, they can just join, and if they get bored they can just as easily remove themselves. The middle ground is the People request to join setting. Potential students can click a button to pass you a request for membership in the course. You then approve it before they gain access to the material in the course. This can give you a handshake moment, when you can ask potential pupils about their interests and background in advance of them turning up for the first lecture. For now, set the course to be discoverable by the public, and let people join automatically. (See Figure 3-3.) 26 | Chapter 3: A Whirlwind Tour www.it-ebooks.info
41. Figure 3-3. Creating a new course It’s entirely possible to create some unusual permission combinations. For example, say you make your course discoverable only by partici- pants, then decide that people can join your course automatically. Try not to be hurt if no one signs up; they can’t see it to join it. If you make your course public and set the membership to be controlled only by the course managers, and you happen to be a Booker Prize winner teaching a small writing seminar, expect students to deluge you with emails or even phone your office telephone line trying to get in to the course. If you go the totally public and tightly controlled route, put a note in your course description about how learners can express their interest so you don’t end up with a crowd camping outside your office. Click the Create mathematics course button on the lower right. It takes a few seconds for the system to copy over all the elements of the mathematics template. When it’s done, your browser refreshes with the landing page of the course site. Take a look at the URL in the browser window. It consists of just three parts: the domain name for your OAE system, a tilde (~), and the URL-safe version of the name of your course site. If you later change the name of your site, the URL will remain the same as it is now. To see this, update the course site settings. Create a Course and a Research Project | 27 www.it-ebooks.info
42. Figure 3-4. Accessing the course settings menu To the right of the Message button is the group configuration drop-down menu, indi- cated by a gear icon (see Figure 3-4). Select Settings from the gear menu and change the title to Partial Derivatives for Dreamers. Click Apply settings and you’ll see the title of the course change to this much more attractive version. The secret frustrations of the topic will persist in the address bar of your browser (see Figure 3-5). The only way to change that URL is to create a new course. Figure 3-5. The URL remains the same even if a course title changes Let’s create a student now, so you can see the site from the learner’s perspective. Before you go away and diminish your privileges, take a click around the lefthand navigation. There’s the material you would expect to see: Syllabus, Lectures, Problem Sets, and Participants. There’s also some you might not expect in an old fashioned learning management system: Course website, Organization Notes, Lecture Template, and Library. Open the management menu for Organization Notes by clicking the downward point- ing arrow that appears when your mouse is on that item and selecting Permissions (see Figure 3-6). Notice that the Organization Notes page, which is about the internal pol- icies for this class, is viewable only by the lecturer and the teaching assistants (see Figure 3-7). Students don’t see it at all. The teaching assistants can’t edit it. T.A.s are consumers, not producers of guidelines in this particular class. (You’re an autocrat of a lecturer, aren’t you?) Log out and make yourself another account, the same way you made your first one. Once you’re logged in as your new self, enter derivatives in the search box at the top 28 | Chapter 3: A Whirlwind Tour www.it-ebooks.info
43. Figure 3-6. Accessing the management menu for Organization Notes Figure 3-7. Permissions dialog box for the Organization Notes section of your browser window. Sakai OAE will suggest the Partial Derivatives course as soon as it recognizes what you want, or you can click on the magnifying glass icon to kick off the search. If you had set the Partial Derivatives course to discoverable only by participants, you wouldn’t be able to find it via search now. Once you’ve found it, access the course site by clicking on the course name. As a visitor there’s less visible than when you were logged in as the instructor; just the Syllabus and Course website sections appear (see Figure 3-8). Create a Course and a Research Project | 29 www.it-ebooks.info
44. Figure 3-8. How the Partial Derivatives course looks to a window shopper Along the top bar with the title of the course you’ll see a button to send a message to the group, and a button for joining up. Click the Join group button and then refresh your browser. Now you have access to all the student materials for the course: the lectures, problem sets, library, and list of participants. You still can’t see the material intended just for the lecturer and teaching assistants, nor can you access the drop down menus which control the left hand navigation elements or the group configuration gear menu. Easy communication is one of the guiding principles of OAE development. Whether or not you’re a member of the course you can send a message to everyone in the class. Click the message button. The to field is filled in with the name of the course site. Write a note and send it off. Everyone who is a participant in the course at the time you send your message will get a copy, including yourself. The envelope icon at the top of your browser updates to show you have 1 unread message in your inbox. Click on the envelope to see a preview of the new message. Click the Read full message button to go to your inbox. Notice that the to line shows the name of the course. From the inbox view, you can mark messages read or just delete them (see Figure 3-9). 30 | Chapter 3: A Whirlwind Tour www.it-ebooks.info
45. Figure 3-9. Exchanging messages within Sakai OAE Course site templates focus on the interactions of students with their instructors, teaching assistants and with each other. Research project templates take a more con- structivist approach, focusing on the individual learner. Research project To create a research project, select Create a research project from the Create + Col lect menu. Select Use this template for the simple Research project. Let’s say this is a research project to go along with the Partial Derivatives course. Name it Calculus on the Web and set it to the most restrictive sharing settings: discoverable only by participants, with membership set to Managers add people. Don’t add any partici- pants, as this is a private research project (see Figure 3-10). Click the Create research project button. Like the course site, you’ll be delivered to the landing page for your new research project once it’s created. Next, on the Introduction page, click the Edit page button. To exercise the revisions feature, replace the template text with some thoughtful summary information about this research into Calculus on the Web. Click Save, then make a few more changes and click the Save button again. Now take a look at the history of edits by clicking the Page revisions button (see Figure 3-11). Every save of your document appears as an entry Create a Course and a Research Project | 31 www.it-ebooks.info
46. Figure 3-10. Creating a new research project on the revision timeline, stamped with the time and author. You can view an earlier revision by clicking on the time and date of the entry. If you decide you want to throw some work away or, more likely, restore an earlier draft after accidentally deleting ma- terial, click the Restore button for that draft. That version becomes a new entry in the timeline, with the current time and date. Be a little careful where you click in the Revisions timeline; it can be dangerously easy to restore an earlier draft. While you can always restore over a restoration, it does eventually feel a bit like untangling twine the kitten’s been at. Before leaving this research project, take a quick look at adding content. Click Library on the lefthand navigation of the Calculus on the Web project. The Library displays a message that you don’t have any content in the project’s library yet, as well as a suggestion to Add content. Click that link to start creating and linking in materials. First, add a link to a website, say the Khan Academy calculus resources: click Add link on the lefthand navigation. For the link, enter culus and pop something in the Title field such as “Khan Academy’s awesome calculus section”. Click the Add button in the middle of the window. The Khan Academy link appears in the Collected Items section. There’s a drop-down menu listing the libraries you can save this item to; it includes your private library, the Partial Derivatives course, and this Calculus on the Web research project. The selection defaults to the group from 32 | Chapter 3: A Whirlwind Tour www.it-ebooks.info
47. Figure 3-11. A pair of page revisions which you started: Calculus on the Web. For the purposes of this example, change it to My library. Take a look at the permissions here, which differ significantly from the permissions available to be set on groups and on pages within a group. Under Khan Academy’s awe some calculus section, click Add permissions. There are three options for who can see this content: Public, Logged in users, and Only me. When you are adding an item to a collection there is no option to limit the visibility to a set of participants. Visibility is set when you include the item to a course or a research project. Let’s make this link visible to the public. The Copyright section is vitally important in the academic environment. Much of the material used in teaching is the result of the hard work of professionals. Copyright protects the intellectual property rights of these workers. Addressing copyright status in OAE opens with conversation with students about how to use others’ work respon- sibly. The OAE system identifies every element added to a collection with the copyright state of the item. The Khan Academy educational content is provided under the Creative Commons Attribution Noncommercial ShareAlike license, so select the Creative Com mons option from the Copyright menu. Click Save then click the Done, add collected button. Create a Course and a Research Project | 33 www.it-ebooks.info
48. Because the link was added to your library, not to the research project’s library, you’ll be returned to Calculus on the Web’s library with the note that your library is indeed still empty. Click Add content again, and we’ll look at adding existing content to the project. Select All content from under Use existing content. You’ll see absolutely everything you have access to in the system, including the student accessible materials from the Partial Derivatives course site. There’s not a whole lot there yet. Check the checkbox next to Khan Academy’s awesome calculus section and click the Add button at the bottom of the list of materials. This time the link appears in the Collected items section, but doesn’t have the options to edit the item or to add permissions. The descriptive data for an item is only set one time, when you upload it. The item inherits those details every where it goes. Double-check that you are saving this collection to the Calculus on the Web library then click Done, add collected. At long last, you’ve got something in your research project library. Click the title Khan Academy’s awesome calculus section and you’ll be brought to the item’s profile page (content gets a profile just like people do) (see Figure 3-12). Along the top there’s information about the visibility of the link as well as where it’s being used and by whom. Below the preview of the link’s content, there’s descriptive infor- mation about the link, including when it was added to OAE and what copyright is associated with it. Figure 3-12. Content gets a profile, just like people do 34 | Chapter 3: A Whirlwind Tour www.it-ebooks.info
49. Most folks in OAE will spend all of their time in course sites and working on projects, either alone, in clubs, or with their cohort. For us, this is just a whirlwind look at sites before digging into the backend of the system. A Quick Trick for Checking Permissions Sakai OAE keeps track of you while you’re logged in using a cookie named sakai- trusted-authn. Regardless of how many tabs you open in a browser, you’ll be logged in to OAE. This is terrific if you want to compare your work in a current class with the version you taught last semester. Just bring the two sites up in separate windows on your cinema display. It’s lousy for testing out permissions, however. When you want to check on how a course site appears to a test user or to an anonymous member of the Internet public, the constantly logging out and logging back in is a giant distraction. To reduce the virtual doorway effect, use a second browser like Firefox. If you’re a devotee of Firefox, then use your operating system’s default browser, whether Internet Explorer or Safari. It won’t hurt this once to use it for testing. Cookies aren’t shared between browser products, so you can maintain two live connections to OAE at the same time. To reduce confusion when checking permission settings, do something to differentiate the look of your two browsers: for example hide all the top bars on the browser of your less powerful user or use Firefox’s full screen view for your more powerful user. Changing the Dashboard When you first log in to Sakai OAE you start out on your dashboard screen. Much as the name implies, this is the overview of what’s going on in OAE right now (see Fig- ure 3-13). On the lefthand navigation, you can rearrange the items according to your own priorities, with some exceptions: the My dashboard and My messages sections can be swapped, but will always remain the top two items in the left navigation. If you put My dashboard at the top, when you log in to OAE, you’ll automatically get the dashboard view. If you put My messages at the top, you’ll land in your inbox when you first log in. The items for my contacts, library, profile, and membership can be arranged in any order, providing they remain below dashboard and messages. To rearrange the left navigation items, click on the item title and drag it to its new position. You can rearrange subsections as well. Different people will have different preferences. The best set up may change through the course of the semester, and depending whether you’re focusing on coursework or research. The You drop-down menu on the top navigation will remain in the default order no matter how you arrange your left navigation. This achieves a balance between custom- ization and support. The lefthand navigation is owned by the user, while the drop- down menu is guaranteed to stay exactly the same, so support staff can predictably offer instructions. Changing the Dashboard | 35 www.it-ebooks.info
50. The top part of the main section cycles through content, groups, and contacts that you might find interesting. The algorithm for what gets displayed to each person is pseudo- random. Nonetheless, it implements the idea of serendipity. By way of example, my writer friend Clive follows almost 500 people on Twitter, some of them quite loqua- cious. He’s experimented with prioritization algorithms, but ultimately it turns out any selection of those, given true attention, is better than trying to skim all of them. He’s set up a client that draws his attention, almost randomly, to just a handful everyday. Since he’s already done a lot of vetting for quality in who he follows, the results tend to be really interesting. The paradox of choice is defanged. Random’s not such a bad prioritization scheme after all. Figure 3-13. The default dashboard If you find the carousel effect distracting, click on any of the three dots under the suggestions. The display slides to a single set of suggestions then stays there. Below the suggestions, three sections highlight your recent activity: content you’ve added, groups you’ve joined and contacts you’ve established. This section is subject to the most customization. The areas here are called widgets and they’re programmable chunks of Sakai OAE you’ll hear more about in Chapter 6. Click the Add widget button at the top right of the window to see a list of the available widgets installed out-of-the- box (see Figure 3-14). As you click the Add and Remove buttons, the dashboard will update in the background, giving you a preview of your new dashboard. Click the 36 | Chapter 3: A Whirlwind Tour www.it-ebooks.info
51. Add button next to the Most popular tags widget, then click the little x to close the widget screen. This widget displays the most used tags through the system. Clicking on a tag opens the search view, with all the results for that tag. At this moment the results aren’t all that interesting, but as material is added to OAE interesting patterns emerge. Figure 3-14. Adding a new widget to the dashboard Finally, you can move your widgets around on the lower part of the main section. Click on the widget’s title and drag it to its new position. Like My dashboard and My mes sages, the Suggested area always stays at the top of this section. To reduce the number of widget columns from the default of three, click the Edit Layout button. The Public Face of Sakai The university is not just about what happens inside the ivory tower. How education engages the experience outside its walls is more important every day. Many universities have a highly curated public web presence. These are quite good at serving the interests of potential students, of faculty and staff in their capacity as em- ployees, and of students needing to navigate internal policies. Getting work in progress through an onerous approval process though can keep it locked up on an individual’s web page. If a web page hasn’t been redesigned since it was created in 1992—let alone been tuned for modern SEO—then it might as well be posted on the hallway bulletin board. The Public Face of Sakai | 37 www.it-ebooks.info
52. To get a sense of the public experience of the OAE, log out of the system. You’re returned to the same page you saw when you first installed OAE, but now it will look a little different. On the right side, there’s new information in the recent activity section. Because the link to the Khan Academy was marked public when it was added, it will pop up in this area. The research project Calculus on the Web won’t show up, as it was set to the most restrictive privacy level. Scroll down to see the Featured Content section. Along with the Khan Academy link, the public course website of the Partial Derivatives course you created appears here. Any course section or content item that’s marked public is a candidate for display on the home page of OAE. OAE can also be browsed by category. Click the Choose a category link to expand the category scroller (see Figure 3-15). These categories are the same ones you used in creating your profile, creating a course or project, and adding content. By adding a category to your materials in OAE, you, in effect, publish it (but only if you also mark it public). By contrast, tags don’t bubble up to the public view of OAE. As folksonomy, they stay local to the community. Figure 3-15. Another public view of OAE The Explore menu on the top left will take you to all publicly available information of a specific type: Content, People, Groups, Courses, and Research Projects. Select Peo 38 | Chapter 3: A Whirlwind Tour www.it-ebooks.info
53. ple and you’ll be taken to search results for all the accounts in the system (see Fig- ure 3-16). There will be two, unless you got all god-like and started creating people like mad. If the accounts have tags or categories associated, these will automatically be suggested as refinements to reduce the list of results. Figure 3-16. Searching for people shows everyone who has a public profile Individuals can opt not to be publically listed in the search by changing the Privacy settings of their account. The privacy settings apply to profile information and to lists of content, membership, and contacts. There’s no Only me setting for accounts, but visibility can be limited to just Logged in users. The Public Face of Sakai | 39 www.it-ebooks.info
54. www.it-ebooks.info
55. CHAPTER 4 Making the Look and Feel Your Own The OAE project has been design-led from the outset. Getting the aesthetic right makes the user experience flow more easily. This chapter introduces you to CSS, label display, language localization, modifying the category metadata, and modifying the landing page widget. The technical work is the easy part in many ways. Designing and deciding all the visual and navigational elements of your instance of OAE requires time and expertise. Be sure to bring in a talented designer, and once you do, remember to listen to her. Configure OAE for CSS, Property, and JavaScript Changes To make look-and-feel changes, configure the running server to look at the UI code you unzipped in “Building from Source” on page 15. Changes to CSS, labels, and lan- guage localizations are all done in the unzipped UI code. When you’re happy with your changes, then you can rebundle the system to make the UI permanent. Ready for some acronyms? Okay. Sakai OAE is built on the Apache Felix implemen- tation of the OSGi framework. It further relies on the Apache Sling OSGi bundles for RESTful implementation of HTTP request handling. To some extent these framework selections derive from an earlier architecture that anticipated full reliance on JSR-170, the Java content repository, to serve all the content needs of Sakai OAE. In pilot de- ployments, it became apparent that the needs for concurrent reads and writes on a shallow, broad tree structure in Sakai OAE were in contention with how JCR optimized. This brought about the development of the sparsemapcontent storage API layer and solr indexing to improve performance under heavy load. (See Figure 4-1.) The view layer is implemented in CSS and JavaScript, with heavy reliance on the jQuery library. Customization handling differs slightly if it’s at the CSS and properties layer from if it’s at the JavaScript layer. In order to customize anything, Nakamura needs to know where to look for your cus- tomizations. Open a browser to The default user- name and password are admin/admin. You are now looking at the dashboard to the guts 41 www.it-ebooks.info
56. Figure 4-1. Some key OAE technologies in the stack of the Sakai OAE system. Click the Configuration button to get over to the Sling con- figuration manager. Modules are listed alphabetically. Scroll down until you find the Apache Sling Filesystem Resource Provider. Click the plus (+) button to create an entry that overrides the packaged frontend code location. For Provider root, enter: /dev For Filesystem root, enter: /Users/username/source/sakai-ux/dev Leave the other values at their defaults and click Save. (See Figure 4-2.)When you add a new Resource Provider, the Felix interface doesn’t necessarily update immediately to show you the new entry. If you want to confirm that your new entry took, refresh your browser and scroll back down to the Apache Sling Filesystem Resource Provider. Under the Filesystem Resource Provider heading you’ll see an entry for org.apache.sling.fsprovider.internal.FsResourceProvider with a unique suffix string. Before getting down to real work, do something quick and destructive to show that you have control of the user interface code now. 1. Change to your dev directory: cd /Users/username/source/sakai-ux/dev 42 | Chapter 4: Making the Look and Feel Your Own www.it-ebooks.info
57. 2. Move your index.html file to a safe backup copy: mv index.html index.html.bak 3. Create a new index.html with an unmistakable message: echo I 0wn the UI > index.html 4. Connect to to see the fruits of your labor (see Figure 4-3). Figure 4-2. Configure a filesystem resource to pick up local UI modifications Figure 4-3. The user interface is so p0wned Changes made in HTML files take effect as soon as you connect to OAE. Configure OAE for CSS, Property, and JavaScript Changes | 43 www.it-ebooks.info
58. Now put it all back: mv index.html.bak index.html and reload your browser. Phew. No harm done. If you have done harm, just unzip the frontend code again and rename the directory to match what you put in the Sling con- sole for the Filesystem Resource (e.g., /Users/username/source/sakai-ux). When you connect to Sakai OAE now notice that you are the admin user. When you log in as admin to the console, you end up with all possible rights and privileges in the OAE system. To log out, you have to close and restart your browser. Use this knowledge carefully. With great power comes great responsibility. Close and restart your browser, then create yourself a new user to test with. Modifying Labels in the User Interface Most elements displayed in the user interface of Sakai OAE are just labels for variables. Modifying the text displayed is as straightforward as changing the label in the default properties file. The file default.properties in sakai-ux/dev/bundle contains all the cus- tomizable display text in OAE. It’s an alphabetically ordered monster of a properties file. For the most part, the variable names match the initial English label values dis- played out of the box. As you make changes to default.properties keep a copy of the original version around as a reference. To see it in action, change the heading for Basic Information in the user profile section. Login to the web interface at and expand the My profile section. Notice that the lefthand navigation shows the section heading for the first section as Basic information. Open up the default.properties file and modify the display value for PROFILE_BASIC_LABEL. Change: PROFILE_BASIC_LABEL = Basic information to: PROFILE_BASIC_LABEL = Name, email, stuff and save the file. Refresh your browser. The first section under My profile now displays as Name, email, stuff. Changes you make in default.properties are automatically adopted the next time anyone loads a page. Internationalization and Localization The display labels in Sakai OAE can not only be customized, they can also be translated and internationalized. Localization property files are stored in sakai-ux/dev/bundle alongside the default.properties file. Sakai OAE ships with limited translations for Spanish, American and British English, Dutch, Magyar, and Chinese. 44 | Chapter 4: Making the Look and Feel Your Own www.it-ebooks.info
59. A localization file can contain just a subset of labels; it need not exhaustively translate the labels in default.properties. As an example, crack open the en_GB.properties files in sakai-ux/dev/bundle. The only two labels customized out of the box are those containing the word acknowledgements. In the States, this word is acceptably spelled acknowledg- ments, whereas in Great Britain only acknowledgements is correct. Start by setting your account language preference to English (United Kingdom). 1. Login at and select My account from the top-right drop-down list associated with your name. 2. On the Preferences tab, select English (United Kingdom) for Language and click Save changes. Figure 4-4. My account language settings The web browser will automatically refresh with the United Kingdom localization. You won’t notice many changes. The Language listed at the bottom right of your browser screen will update to show you are now set to English (United Kingdom). Modify the properties file to localize a third display label. For our British version of OAE, replace the You menu with the more generic label One. In the file en_GB.properties add the line: YOU = One and save the file. Order is not meaningful in the properties files, so technically you can place the new label value anywhere. As these grow though, it’s good to have the values alphabetized by variable, so drop the new line in at the end of the en_GB.properties file. Refresh your browser and the new menu name One displays in place of You in the upper-left of the browser screen. (See Figure 4-5.) Introducing a new localization requires creating a fresh properties file for the region, and also making a modification to add a new option to the My account drop-down list of Languages. The config.js file in sakai-ux/dev/configuration maintains the Languages drop-down list. This will be your first look at the JavaScript layer of customization in OAE. Internationalization and Localization | 45 www.it-ebooks.info
60. Figure 4-5. UK English menu using the third person plural instead of the second person pronoun 1. Create a new file in sakai-ux/dev/bundle with the name zu_ZA.properties. zu-ZA is the i18n code for the Xhosa language in the South African geographic region. 2. Modify the display label for the You menu to the Xhosa word for hello, by adding the following line to your new zu_ZA.properties file: YOU = Molo 3. Change to the sakai-ux/dev/configuration directory and take a quick backup of the config.js file. It’s easy to mess up the JavaScript syntax, and you can accidentally white-bomb your OAE install with a stray semicolon: cp -p config.js config.js.bak 4. Locate the Languages section in the config.js file, about line 1511. Add a block for the new localization option: { "country": "ZA", "language": "zu", "displayName": "Xhosa (South Africa)" }, The Xhosa option will turn up in the position in which you place it relative to the other language options in the menu. Be careful with your brackets and commas as you place it in the list. 5. JavaScript content is eagerly cached in the browser in order to improve the per- formance of OAE. To see the new localization option, refresh the cache in your browser. In Firefox: Preferences→Advanced→Network, then in Cached Web Content click Clear Now. In Safari: Safari menu→Empty Cache→Empty. 6. Select My account from the top-right drop-down list associated with your name, then on the Preferences tab, select Xhosa (South Africa) for Languages and click Save changes. (See Figure 4-6.) 46 | Chapter 4: Making the Look and Feel Your Own www.it-ebooks.info
61. The top-left menu changes from You (or One) to Molo. (See Figure 4-7.) Figure 4-6. Xhosa Language menu item is added by editing config.js If the Xhosa option doesn’t turn up, make sure you’ve saved the zu_ZA.properties file and the revised config.js file and try refreshing your cache again. Figure 4-7. Xhosa South Africa menu using a greeting in lieu of a pronoun If you are ever scratching your head for what the underlying label name is for a bit of display text, you can use the special language setting i18n debug to see the labels in place in the UI. In theMy account menu, click the Preferences button, then select the last of the language settings, i18n debug. When the window refreshes, all the display text is replaced with the corresponding label names. Before you roll OAE into produc- tion, remove the i18n debug option for the Language list. See “Reducing the JavaScript Debug Logging” on page 98 for details on getting production ready. Internationalization and Localization | 47 www.it-ebooks.info
62. Changing the CSS: Paint It Pink Sakai OAE is entirely styled with Cascading Style Sheets. You can customize the look of the system for your local environment by providing your own stylesheets, overriding the selectors with custom properties and values. The default CSS files for OAE are stored in sakai-ux/dev/css. The bulk of the CSS files of interest are in the sakai directory under css. The two other directories in this location are FSS and lib. The FSS stylesheets come to OAE from the Fluid project, which enables a high level of customization to individuals for accessibility purposes. Inclusion of the Fluid skinning system in Sakai OAE allows people with visual or other impairments to alter the display of OAE, making content accessible to them that might otherwise be unavailable. In the lib directory is a single stylesheet for tweaking the jQuery-based AutoSuggest display. The styles you’ll want to get familar with are all in .css files located in dev/css/sakai: sakai.corev1.css The primary stylesheet, providing the main layout for all pages defining columns, content areas, and header areas. sakai.base.css The primary element styling file, all 2,700 lines of it. This is the most important stylesheet in the system. All the s3d consolidated styles are defined here. The sec- tions are commented to guide you to what is being styled by the selectors that follow (e.g., global rules, drop-down menus, links, buttons, search boxes). The Mozilla firebug plug-in is invaluable in picking out the selector names for rules you’d like to change. main.css The aggregating master file. The main.css imports the Fluid skinning system base classes, the jQuery AutoSuggest tweak from the local CSS library and a jQuery gritter stylesheet for popping up alert messages. It imports the two key OAE specific stylesheets: sakai.base.css and sakai.components.jq_pager.css. sakai.explore.css Styles the Search results page, whether reached via the Explore menu or by entering something in the search box. This stylesheet also covers the category and subca- tegory displays, and the index page (conceptualized as exploring categories from the root). The sakai.explore.css file overrides some of the styles defined in sa- kai.base.css and sakai.corev1.css. sakai.create_new_account.css Styles the Sign Up page at overriding the base styles as needed. 48 | Chapter 4: Making the Look and Feel Your Own www.it-ebooks.info