You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@vcl.apache.org by bu...@apache.org on 2012/07/31 15:59:09 UTC
svn commit: r827506 - in /websites/staging/vcl/trunk/content: ./
docs/themes.html
Author: buildbot
Date: Tue Jul 31 13:59:09 2012
New Revision: 827506
Log:
Staging update by buildbot for vcl
Added:
websites/staging/vcl/trunk/content/docs/themes.html
Modified:
websites/staging/vcl/trunk/content/ (props changed)
Propchange: websites/staging/vcl/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Jul 31 13:59:09 2012
@@ -1 +1 @@
-1367173
+1367555
Added: websites/staging/vcl/trunk/content/docs/themes.html
==============================================================================
--- websites/staging/vcl/trunk/content/docs/themes.html (added)
+++ websites/staging/vcl/trunk/content/docs/themes.html Tue Jul 31 13:59:09 2012
@@ -0,0 +1,287 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+ <link href="/css/vcl.css" rel="stylesheet" type="text/css">
+ <title>Apache VCL - Themes</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+</head>
+
+<body>
+ <div id="sitetitle">
+ <table width="100%" border="0" cellspacing="0" cellpadding="5">
+ <tr>
+ <td><a href="/index.html">Apache VCL</a></td>
+ <td><img src="/img/vcllogo.png" width="63" height="52" align="right"></td>
+ </tr>
+ </table>
+ </div>
+
+ <div id="navigation">
+ <ul>
+<li>Information<ul>
+<li><a href="/info/about.html">What is VCL?</a></li>
+<li><a href="/info/features.html">Features</a></li>
+<li><a href="/info/architecture.html">Architecture</a></li>
+<li><a href="/info/use-cases.html">Use Cases</a></li>
+<li><a href="/download.cgi">Download</a></li>
+<li><a href="/info/license.html">License</a></li>
+<li><a href="/info/faq.html">FAQ</a></li>
+</ul>
+</li>
+<li><a href="/docs/index.html">Documentation</a><ul>
+<li><a href="/docs/using-vcl.html">Using VCL</a></li>
+<li><a href="/docs/image-creation.html">Image Creation</a></li>
+<li><a href="/docs/administration.html">Administration</a></li>
+<li><a href="/docs/installation.html">Installation</a></li>
+<li><a href="/docs/deployment-planning.html">Deployment Planning</a></li>
+</ul>
+</li>
+<li><a href="/comm/index.html">Community</a><ul>
+<li><a href="/comm/index.html#getInvolved">Getting Involved</a></li>
+<li><a href="/comm/index.html#mail-list">Mailing Lists</a></li>
+<li><a href="/comm/index.html#how-do-i-join-the-project">How can I Join</a></li>
+<li><a href="/comm/wiki.html">Wiki</a></li>
+<li><a href="/dev/index.html">Development</a><ul>
+<li><a href="/dev/jira.html">Issue Tracking</a></li>
+<li><a href="/dev/code-documentation.html">Code Documentation</a></li>
+<li><a href="/dev/roadmap.html">Roadmap</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="http://www.apache.org">Apache Software Foundation</a><ul>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+</ul>
+</li>
+</ul>
+ </div>
+
+ <div id="content">
+ <h1 class="title">Themes</h1>
+ <div class="toc">
+<ul>
+<li><a href="#overview">Overview</a></li>
+<li><a href="#file-system-structure">File system structure</a></li>
+<li><a href="#vcl-html-generation">VCL HTML generation</a></li>
+<li><a href="#understanding-pagephp">Understanding page.php</a></li>
+<li><a href="#path-references">Path references</a></li>
+<li><a href="#example-bare-minimal-theme">Example: bare minimal theme</a></li>
+<li><a href="#using-a-new-theme">Using a new theme</a></li>
+<li><a href="#tips-and-tricks">Tips and Tricks</a></li>
+</ul>
+</div>
+<h2 id="overview">Overview</h2>
+<p>Custom themes can be created in VCL for each affiliation. This allows a multi-site
+installation of VCL to have themes that match each affiliation's primary web site
+theme. When a user logs in, the site will be displayed using the theme specified
+for that user's affiliation. Additionally, when using <a href="/docs/ldapauth.html">LDAP
+authentication</a>, the login page for the affiliation will be
+displayed with the theme matching that affiliation.</p>
+<h2 id="file-system-structure">File system structure</h2>
+<p>The themes are in a <strong>themes</strong> directory in the web code. If you installed your web
+frontend under a directory named <strong>vcl</strong>, you would look in vcl/themes. Each VCL
+release comes with a <strong>default</strong> theme, which you should see at vcl/themes/default.
+Typically, you would set up the following directory structure for a new theme:</p>
+<ul>
+<li>vcl/themes/mynewtheme</li>
+<li>vcl/themes/mynewtheme/page.php</li>
+<li>vcl/themes/mynewtheme/images</li>
+<li>vcl/themes/mynewtheme/js</li>
+<li>vcl/themes/mynewtheme/css</li>
+</ul>
+<p>The page.php file and css directory are the only ones that are required. After creating
+the directory structure, you will need to go to the themes directory and run the
+copydojocss.sh script, passing it the name of the directory containing your new theme as
+an argument:</p>
+<div class="codehilite"><pre><span class="n">cd</span> <span class="n">vcl</span><span class="o">/</span><span class="n">themes</span>
+<span class="o">./</span><span class="n">copydojocss</span><span class="o">.</span><span class="n">sh</span> <span class="n">mynewtheme</span>
+</pre></div>
+
+
+<h2 id="vcl-html-generation">VCL HTML generation</h2>
+<p>There are a few parts to how VCL generates the HTML for any given page. There are some
+important functions of which to be aware. The first two must be in the page.php file:</p>
+<ul>
+<li>getHeader - generates all content up to and including the opening of a div element
+that will contain the main page content (typically what is to the right of the
+navigation menu); this div element must have an <strong>id</strong> of <strong>content</strong>; must have
+$refresh passed to it as an argument, which is then passed to getDojoHTML</li>
+<li>getFooter - closes the div element containing the main page content and generates any
+remaining content to close out the HTML for the page</li>
+</ul>
+<p>These are functions that exist in utils.php that are available to be called from
+getHeader and getFooter:</p>
+<ul>
+<li>getDojoHTML - returns a string of Dojo related style and javascript; needs to be
+called in the <head> part of the page; needs to be passed $refresh as an argument</li>
+<li>getExtraCSS - returns an array of css files expected to exist in the vcl/css directory
+that need to be included for the current value of $mode; a link tag needs to be created
+for each of these files</li>
+<li>getSelectLanguagePulldown - returns the html for a form that has a select element for
+changing the locale of the site</li>
+<li>getNavMenu - returns a string of list items that make up the navigation part of the
+site; needs to be wrapped in <ul> tags; accepts 3 arguments:</li>
+<li>$inclogout - 0/1 - should a <strong>Logout</strong> item be at the bottom of the navigation list</li>
+<li>$inchome - 0/1 - should a <strong>HOME</strong> item be at the top of the navigation list</li>
+<li>$homeurl - (optional) - if $inchome is 1, use this as the href of the HOME link;
+if $inchome is 1 and $homeurl is not specified, HOME from conf.php is used</li>
+</ul>
+<h2 id="understanding-pagephp">Understanding page.php</h2>
+<p>As noted above, this file must contain getHeader and getFooter. <strong>getHeader</strong> must
+contain these elements, all of which can be seen in the default theme's page.php file:</p>
+<ul>
+<li>opening html and head tags</li>
+<li>stylesheet link to "css/vcl.css"</li>
+<li>script tag with src="js/code.js"</li>
+<li>script block setting the javascript variable <em>cookiedomain</em> to the php define
+<em>COOKIEDOMAIN</em> and setting usenls = 0</li>
+<li>a call to getDojoHTML($refresh) in the head section of the HTML</li>
+<li>a call to getExtraCSS() with a foreach to add a stylesheet link for each file in the
+array returned by getExtraCSS()</li>
+<li>closing head tag</li>
+<li>body tag with its class set to the name of the theme</li>
+<li>an unordered list wrapping the string returned by a call to getNavMenu() - this should
+be inside an if conditional checking for $authed to be true</li>
+<li>must end with an opening div tag with an id of <em>content</em></li>
+</ul>
+<p><strong>getFooter</strong> must contain these elements:</p>
+<ul>
+<li>closing div tag for the content div element</li>
+<li>closing body and html tags</li>
+</ul>
+<h2 id="path-references">Path references</h2>
+<p>There are a few things to keep in mind with respect to path references. From a web
+browser's perspective, all HTML generated by getHeader and getFooter will be part of the
+vcl/index.php file. So, any paths referenced in getHeader and getFooter need to be
+relative to that - example: <img src="themes/mynewtheme/images/someimage.png">. Any
+files referenced in css files in the theme's css directory will be relative to that css
+file. So, if you were to include a reference to an image in the theme's image directory
+in a css file in the css directory, you would reference it relative to the css directory
+- example: url(../images/someimage.png)</p>
+<h2 id="example-bare-minimal-theme">Example: bare minimal theme</h2>
+<p>This example shows the bare minimum that must be included. For a more detailed example,
+look at the default theme include in each release. We'll call the theme "minimal". First,
+we create a directory under the themes directory for it:</p>
+<div class="codehilite"><pre><span class="nb">mkdir</span> <span class="n">vcl</span><span class="sr">/themes/mi</span><span class="n">nimal</span>
+</pre></div>
+
+
+<p>Next, we create a css directory and run the copydojocss.sh script:</p>
+<div class="codehilite"><pre><span class="nb">mkdir</span> <span class="n">vcl</span><span class="sr">/themes/mi</span><span class="n">nimal</span><span class="o">/</span><span class="n">css</span>
+<span class="n">cd</span> <span class="n">vcl</span><span class="o">/</span><span class="n">themes</span>
+<span class="o">./</span><span class="n">copydojocss</span><span class="o">.</span><span class="n">sh</span> <span class="n">minimal</span>
+</pre></div>
+
+
+<p>Now, we create vcl/themes/minimal/page.php with this content:</p>
+<div class="codehilite"><pre>function getHeader(<span class="p">$</span><span class="nv">refresh</span>) <span class="err">{</span>
+ global <span class="p">$</span><span class="nv">user</span>, <span class="p">$</span><span class="nv">mode</span>, <span class="p">$</span><span class="nv">authed</span>, <span class="p">$</span><span class="nv">locale</span>, <span class="p">$</span><span class="nv">VCLversion</span>;
+ <span class="p">$</span><span class="nv">rt</span> = "<span class="cp"><!DOCTYPE html></span>\n";
+ <span class="p">$</span><span class="nv">rt</span> .= "<span class="nt"><html></span>\n";
+ <span class="p">$</span><span class="nv">rt</span> .= "<span class="nt"><head></span>\n";
+ <span class="p">$</span><span class="nv">rt</span> .= "<span class="nt"><title></span>VCL<span class="nt"></title></span>\n";
+ <span class="p">$</span><span class="nv">rt</span> .= "<span class="nt"><link</span> <span class="na">rel=</span><span class="s">stylesheet</span> <span class="na">type=</span><span class="s">\"text/css\"</span> <span class="na">href=</span><span class="s">\"css/vcl.css\"</span><span class="nt">></span>\n";
+ <span class="p">$</span><span class="nv">rt</span> .= "<span class="nt"><link</span> <span class="na">rel=</span><span class="s">stylesheet</span> <span class="na">type=</span><span class="s">\"text/css\"</span> <span class="na">href=</span><span class="s">\"themes/minimal/css/minimal.css\"</span><span class="nt">></span>\n";
+ <span class="p">$</span><span class="nv">rt</span> .= "<span class="nt"><script</span> <span class="na">src=</span><span class="s">\"js/code.js\"</span> <span class="na">type=</span><span class="s">\"text/javascript\"</span><span class="nt">></script></span>\n";
+ <span class="p">$</span><span class="nv">rt</span> .= "<span class="nt"><script</span> <span class="na">type=</span><span class="s">\"text/javascript\"</span><span class="nt">></span>\n";
+ <span class="p">$</span><span class="nv">rt</span> .= "var cookiedomain = '" . COOKIEDOMAIN . "';\n";
+ <span class="p">$</span><span class="nv">rt</span> .= "<span class="nt"></script></span>\n";
+ <span class="p">$</span><span class="nv">rt</span> .= getDojoHTML(<span class="p">$</span><span class="nv">refresh</span>);
+ <span class="p">$</span><span class="nv">extracss</span> = getExtraCSS();
+ foreach(<span class="p">$</span><span class="nv">extracss</span> as <span class="p">$</span><span class="nv">file</span>)
+ <span class="p">$</span><span class="nv">rt</span> .= "<span class="nt"><link</span> <span class="na">rel=</span><span class="s">stylesheet</span> <span class="na">type=</span><span class="s">\"text/css\"</span> <span class="na">href=</span><span class="s">\"css/</span><span class="p">$</span><span class="nv">file</span><span class="s">\"</span><span class="nt">></span>\n";
+ <span class="p">$</span><span class="nv">rt</span> .= "<span class="nt"></head></span>\n\n";
+ <span class="p">$</span><span class="nv">rt</span> .= "<span class="nt"><body</span> <span class="na">class=</span><span class="s">minimal</span><span class="nt">></span>\n\n";
+ <span class="p">$</span><span class="nv">rt</span> .= "<span class="nt"><div</span> <span class="na">id=</span><span class="s">menulist</span><span class="nt">></span>\n";
+ if(<span class="p">$</span><span class="nv">authed</span>) <span class="err">{</span>
+ <span class="p">$</span><span class="nv">rt</span> .= "<span class="nt"><ul></span>\n";
+ <span class="p">$</span><span class="nv">rt</span> .= getNavMenu(1, 1);
+ <span class="p">$</span><span class="nv">rt</span> .= "<span class="nt"></ul></span>\n";
+ }
+ <span class="p">$</span><span class="nv">rt</span> .= "<span class="nt"></div></span>\n";
+ <span class="p">$</span><span class="nv">rt</span> .= "<span class="nt"><div</span> <span class="na">id=</span><span class="s">content</span><span class="nt">></span>\n";
+ return <span class="p">$</span><span class="nv">rt</span>;
+}
+
+function getFooter() <span class="err">{</span>
+ <span class="p">$</span><span class="nv">year</span> = date("Y");
+ <span class="p">$</span><span class="nv">rt</span> = "<span class="nt"></div></span>\n";
+ <span class="p">$</span><span class="nv">rt</span> .= "<span class="nt"></body></span>\n";
+ <span class="p">$</span><span class="nv">rt</span> .= "<span class="nt"></html></span>\n";
+ return <span class="p">$</span><span class="nv">rt</span>;
+}
+</pre></div>
+
+
+<p>Finally, we create a basic css file at vcl/themes/minimal/css/minimal.css:</p>
+<div class="codehilite"><pre><span class="c1">#menulist {</span>
+ <span class="n">float:</span> <span class="n">left</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="c1">#content {</span>
+ <span class="n">margin</span><span class="o">-</span><span class="n">left:</span> <span class="mi">15</span><span class="n">em</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h2 id="using-a-new-theme">Using a new theme</h2>
+<p>Themes are assigned on a per-affiliation basis in the affiliation table. This must
+be done directly in the database by setting the <strong>affiliation.theme</strong> field for an
+affiliation to the name of a theme in the themes directory. For example, to use our new
+<em>minimal</em> theme, you would set <strong>affiliation.theme</strong> to <strong>minimal</strong> for the desired
+affiliation.</p>
+<h2 id="tips-and-tricks">Tips and Tricks</h2>
+<p>The VCL web site has some administrative pages that can generate very large tables. If
+you want them to be completely wrapped in your theme, you will probably need to use
+tables as part of you main layout instead of just using div elements and css. (Hopefully,
+all of those large tables will be converted to dojo grids like the Manage Groups page by
+the 2.4 release.)</p>
+<p>Mobile themes - If you would like to use a modified theme for mobile devices, you can add
+a section of code to the top of getHeader and getFooter that detects mobile devices
+based on $_SERVER['HTTP_USER_AGENT']. If a mobile browser is detected, you can then
+call a different function that generates mobile specific HTML and returns it to the
+calling function. Here is an example that could be used in getHeader:</p>
+<div class="codehilite"><pre><span class="k">if</span><span class="p">(</span><span class="n">array_key_exists</span><span class="p">(</span><span class="s">'HTTP_USER_AGENT'</span><span class="p">,</span> <span class="nv">$_SERVER</span><span class="p">)</span> <span class="o">&&</span>
+ <span class="p">(</span><span class="n">eregi</span><span class="p">(</span><span class="s">'iphone'</span><span class="p">,</span> <span class="nv">$_SERVER</span><span class="p">[</span><span class="s">'HTTP_USER_AGENT'</span><span class="p">])</span> <span class="o">||</span>
+ <span class="n">eregi</span><span class="p">(</span><span class="s">'android'</span><span class="p">,</span> <span class="nv">$_SERVER</span><span class="p">[</span><span class="s">'HTTP_USER_AGENT'</span><span class="p">])))</span>
+ <span class="k">return</span> <span class="n">mobileHeader</span><span class="p">(</span><span class="nv">$refresh</span><span class="p">);</span>
+</pre></div>
+
+
+<p>mobileHeader would still need to meet all of the requirements of getHeader, but it
+would just generate mobile specific HTML. A similar block of code would then be
+added to getFooter, calling a function named something like mobileFooter.</p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2012 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache and the Apache feather logo are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>