source: enpraxis.educommons/trunk/enpraxis/educommons/docs/PORTLETS.html @ 566

Revision 566, 11.1 KB checked in by tom, 4 years ago (diff)

updating documentation and educommons.com links
Line 
1<?xml version="1.0" encoding="utf-8" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
7<title></title>
8<link rel="stylesheet" href="./default.css" type="text/css" />
9</head>
10<body>
11<div class="document">
12
13
14<div class="section" id="adding-portlets-to-educommons">
15<h1>Adding Portlets To eduCommons</h1>
16<p>A portlet is a user-interface component that can be &quot;plugged-in&quot; to the architecture of Plone, the framework upon which eduCommons is based. There are several portlets that are natively available when you install eduCommons: the Course Info portlet that appears in the right navigation is an example, the Course Builder portlet is another. This tutorial will explain how portlets can be added and removed and how you can create your own portlet from scratch.</p>
17<ul class="simple">
18<li><a class="reference internal" href="#adding-and-removing-existing-portlets">Adding and Removing Existing Portlets</a></li>
19<li><a class="reference internal" href="#creating-your-own-portlet">Creating Your Own Portlet</a>.</li>
20<li><a class="reference internal" href="#customizing-portlets">Customizing Portlets</a>.</li>
21<li><a class="reference internal" href="#oerrecommender-portlet">OerRecommender Portlet</a>.</li>
22<li><a class="reference internal" href="#coursebuilder-portlet">CourseBuilder Portlet</a>.</li>
23<li><a class="reference internal" href="#courseinfo-portlet">CourseInfo Portlet</a>.</li>
24<li><a class="reference internal" href="#additional-resources">Additional Resources</a>.</li>
25</ul>
26</div>
27<div class="section" id="id1">
28<span id="adding-and-removing-existing-portlets"></span><h1>Adding and Removing Existing Portlets</h1>
29<p>If a portlet already exists that you either want to remove or add, follow these steps.</p>
30<ul class="simple">
31<li>navigate to the site as an administrator.</li>
32<li>click on the <em>manage portlets</em> link.</li>
33</ul>
34<p>The <em>manage portlets</em> page allows you to add and remove portlets.</p>
35<ul class="simple">
36<li>To add a portlet click on the <em>Add portlet...</em> drop down menu and select the portlet to add.</li>
37<li>To delete a portlet click on the small red <em>x</em> next to the portlet to remove.</li>
38</ul>
39<p>You can also change the order that the portlets appear by using the small blue arrows next to the porlets.</p>
40</div>
41<div class="section" id="id2">
42<span id="creating-your-own-portlet"></span><h1>Creating Your Own Portlet</h1>
43<p>One of the simplest ways to create a portlet is to use the ZopeSkel tool to create a skeleton product that you can then modify for your own purposes. The Plone site has an <a class="reference external" href="http://plone.org/documentation/how-to/use-paster/">excellent article describing how to install and use the ZopeSkel tool</a>. Once you have ZopeSkel installed you can create a new portlet package using the plone3_portlet template.</p>
44<pre class="literal-block">
45paster create -t plone3_portlet
46</pre>
47<p>Enter the information, as prompted, for the portlet you are creating. To select the defaults, just press enter.</p>
48<pre class="literal-block">
49Enter project name: SamplePortletProject
50Variables:
51  egg:      SamplePortletProject
52  package:  sampleportletproject
53  project:  SamplePortletProject
54Enter namespace_package (Namespace package (like plone)) ['collective']: sample_portlet_project
55Enter namespace_package2 (Nested namespace package (like app)) ['portlet']:
56Enter package (The package contained namespace package (like example)) ['example']:
57Enter zope2product (Are you creating a Zope 2 Product?) [True]:
58Enter version (Version) ['0.1']:
59Enter description (One-line description of the package) ['']: This is a sample portlet product
60Enter long_description (Multi-line description (in reST)) ['']:
61Enter author (Author name) ['Plone Foundation']:
62Enter author_email (Author email) ['plone-developers&#64;lists.sourceforge.net']:
63Enter keywords (Space-separated keywords/tags) ['']:
64Enter url (URL of homepage) ['http://plone.org']:
65Enter license_name (License name) ['GPL']:
66Enter zip_safe (True/False: if the package can be distributed as a .zip file) [False]:
67Enter portlet_name (Portlet name (human readable)) ['Example portlet']: Sample Portlet
68Enter portlet_type_name (Portlet type name (should not contain spaces)) ['ExamplePortlet']: SamplePortlet
69</pre>
70<p>A portlet package will be created in the folder where you ran the script. Follow the directions in the Plone article to install the new portlet package using easy_install. Another option is to tell the paster script to create a Plone 2 product and then copy this product into the Products directory of your plone instance (the Plone 2 product is buried down a few levels in the package). In either case, after you restart your Plone instance and navigate to the <em>Add-on Products</em> page of your Plone site you will see the new product listed. After installing the product into your Plone site you will be able to manage it as you do the other portlets in your site.</p>
71</div>
72<div class="section" id="id3">
73<span id="customizing-portlets"></span><h1>Customizing Portlets</h1>
74<p>If you look at the code, generated in the last section, you will see that this new product is relatively simple. It contains a configure.zcml file, a template file, a python file, a profile folder, and a tests folder. Often the only places that will need to be changed to customize the portlet will be the template file and the renderer within the python file. Here are some examples of portlets that do just that:</p>
75<div class="section" id="id4">
76<span id="oerrecommender-portlet"></span><h2>OerRecommender Portlet</h2>
77<p>This is the <a class="reference external" href="http://cosl.usu.edu/svndev/eduCommons3/tags/3.1.0-final/portlet/oerrecommender.pt">oerrecommender.pt</a> template file for the oerrecommender. The file consists of a script tag that retrieves a series of recommendations from oerrecommender.org.</p>
78<pre class="literal-block">
79&lt;div id=&quot;recommendations&quot;&gt;
80  &lt;script language=&quot;JavaScript&quot;
81          tal:define=&quot;url here/absolute_url&quot;
82          tal:attributes=&quot;src string:http://www.oerrecommender.org/recommendations.pjs?educommons=true&amp;u=${url}&amp;title=true;&quot;
83          type=&quot;text/javascript&quot;&gt;
84  &lt;/script&gt;
85&lt;/div&gt;
86</pre>
87<p>Here is the renderer for the <a class="reference external" href="http://cosl.usu.edu/svndev/eduCommons3/tags/3.1.0-final/portlet/oerrecommenderportlet.py">oerrecommenderportlet.py</a> file.</p>
88<pre class="literal-block">
89class Renderer(base.Renderer):
90    &quot;&quot;&quot; Render the OER Portlet &quot;&quot;&quot;
91    render = ViewPageTemplateFile('oerrecommender.pt')
92
93    def __init__(self, context, request, view, manager, data):
94        super(Renderer, self).__init__(context, request, view, manager, data)
95        self.props = self.context.portal_properties.educommons_properties
96
97    &#64;property
98    def available(self):
99        return self.props.oerrecommender_enabled
100</pre>
101<p>You'll notice that the renderer is where we define which page template to use when rendering the template. This file also contains a property that allows the portlet to be conditionally displayed based on whether the oerrecommender is enabled.</p>
102</div>
103<div class="section" id="id5">
104<span id="coursebuilder-portlet"></span><h2>CourseBuilder Portlet</h2>
105<p>The Course Builder tool allows users to quickly create a course with its associated files and departments. In this <a class="reference external" href="http://cosl.usu.edu/svndev/eduCommons3/tags/3.1.0-final/portlet/coursebuilder.pt">coursebuilder.pt</a> template file you can see the portlet displaying a link to the Course Builder form (the '&#64;&#64;' symbol signifies that the resource is a view).</p>
106<pre class="literal-block">
107&lt;dl class=&quot;portlet portletCourseBuilder&quot;
108    i18n:domain=&quot;eduCommons&quot;&gt;
109
110  &lt;dt class=&quot;portletHeader&quot;
111      i18n:translate=&quot;box_course_builder&quot;&gt;
112    Course Builder
113  &lt;/dt&gt;
114
115  &lt;dd class=&quot;portletItem even&quot;&gt;
116    &lt;a href=&quot;&quot;
117         i18n:translate=&quot;text_build_course&quot;
118         tal:attributes=&quot;href string:${here/portal_url}/&#64;&#64;coursebuilderform&quot;&gt;Build a Course&lt;/a&gt;
119  &lt;/dd&gt;
120
121&lt;/dl&gt;
122</pre>
123</div>
124<div class="section" id="courseinfo-portlet">
125<span id="courseinfo-example"></span><h2>CourseInfo Portlet</h2>
126<p>The CourseInfo portlet displays course statistics for the objects within each course. Methods are defined with the python file that are then used with the template file. For example, the renderer for the portlet in the <a class="reference external" href="http://cosl.usu.edu/svndev/eduCommons3/tags/3.1.0-final/portlet/courseinfoportlet.py">courseinfoportlet.py</a> file contains several methods</p>
127<pre class="literal-block">
128...
129def statePercent(self, state=''):
130  &quot;&quot;&quot; return the percent value for a given state &quot;&quot;&quot;
131
132  if 0 == self.total:
133    return '0%'
134  else:
135    width = float(self.stateCounts[state])/float(self.total) * 100.0
136    return '%d%%' %int(width)
137...
138</pre>
139<p>that are then used in the <a class="reference external" href="http://cosl.usu.edu/svndev/eduCommons3/tags/3.1.0-final/portlet/courseinfo.pt">courseinfo.pt</a> template file.</p>
140<pre class="literal-block">
141...
142    &lt;img alt=&quot;barchart&quot; class=&quot;statecolumnimage&quot;
143                 tal:attributes=&quot;width python:view.statePercent(item);
144                 src string:bargraphic.gif&quot; /&gt;
145...
146</pre>
147</div>
148</div>
149<div class="section" id="id6">
150<span id="additional-resources"></span><h1>Additional Resources</h1>
151<p>There are some great resources to help you in customizing existing portlets and for adding functionality to portlets that you've created using the ZopeSkel product.</p>
152<p>If you would like to do some quick and dirty customization through-the-web you'll probably want to <a class="reference external" href="http://plone.org/documentation/tutorial/customization-for-developers/tutorial-all-pages">use the portal_view_customizations tool</a> in the ZMI. It's similar to portal_skins but for view, viewlets, and portlets.</p>
153<p>Martin Aspeli has a whole tutorial on customizing a plone site which includes a section on <a class="reference external" href="http://plone.org/documentation/tutorial/customization-for-developers/portlet-renderers">customizing portlet renderers</a>.</p>
154<p>The Plone site also has a tutorial that shows how to <a class="reference external" href="http://plone.org/documentation/how-to/override-the-portlets-in-plone-3.0/?searchterm=add%20new%20portlet">override existing portlets</a>.</p>
155</div>
156</div>
157<div class="footer">
158<hr class="footer" />
159<a class="reference external" href="PORTLETS.txt">View document source</a>.
160Generated on: 2009-08-09 07:41 UTC.
161Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
162
163</div>
164</body>
165</html>
Note: See TracBrowser for help on using the repository browser.