Jump to: navigation, search

Difference between revisions of "Using Phoenix"

Line 324: Line 324:
 
   $Nav->addMetaNav("project.name");
 
   $Nav->addMetaNav("project.name");
  
Just insert this before you call App-GeneratePage, and it will load the left nav from the Meta data.  The entries on the left nav have the same restrictions as those for the wiki.
+
Just insert this before you call $App->GeneratePage(). and it will load the left nav from the Meta data.  The entries on the left nav have the same restrictions as those for the wiki.  You can even combine this with the $Nav->addCustomNav() function to add extra items to a default left nav defined in the Meta data.
  
 
==Adding a security question to a form==
 
==Adding a security question to a form==
  
 
See [[Phoenix_formsecurity]].
 
See [[Phoenix_formsecurity]].

Revision as of 11:21, 4 June 2008

Use this page for help on authoring websites under Phoenix guidelines.

Back to Phoenix Documentation.

General steps to get going

  • Familiarize yourself with Phoenix page layouts. Understand the 10 components of a page, and which ones you can modify.
  • Set up your Eclipse environment. This includes CVS, PHP and XAMPP plugins.
  • Update your local files from the repository before making changes. This will help prevent commit conflicts later.
  • Understand template.php file and the _projectCommon.php. These were put in your project's directory by the webmaster.
  • Commit new and changed pages to the phoenix.eclipse.org sandbox first (Foundation staff only). View them at http://phoenix.eclipse.org/ .
  • Commit new and changed pages to the dev.eclipse.org repository. View them at http://www.eclipse.org/ .


CVS repository setup

There are two repositories: The website repository and the sandbox repository. The sandbox repository is only used by Foundation staff.

   Website repository
   Host name 	dev.eclipse.org
   CVS root 	/cvsroot/org.eclipse
   Project 	www
   Connection method 	extssh
   Sandbox repository
   Host name 	phoenix.eclipse.org
   CVS root 	/cvsroot/org.eclipse
   Project 	www
   Connection method 	extssh

Phoenix page layout

Phoenix Page Layout

1. Top banner. This is an eclipse.org common element that can only be modified by the Eclipse Foundation.

2. Menu bar. This is an eclipse.org common element that can only be modified by the Eclipse Foundation.

3. Nav bar - common navs. These common navs are defined by the Eclipse Foundation.

4. Page title. Marked up with the h1 tag:

<h1>Eclipse</h1>

5. Section title. Marked up with the h2 tag:

<h2>Open Source Community</h2>

6. Section text. Marked up with the p tag:

<p>Eclipse is an open source community...</p>

7. Featured element. Created using a DIV tag

    <div class="homeitem">
       <h3>Community News</h3>
          <ul>
             <li><a href="http://somesite">Some news! Teaser text  <span class="dates">2005-10-06</span></li>
             <li><a href="http://somesite">Some other news! Teaser text  <span class="dates">2005-10-06</span></li>
          </ul>
    </div>

8. Side element. Created using a DIV tag

    <div class="sideitem">
       <h6>New to Eclipse?</h6>
          <ul>
          <li><a href="#">Community Resources</a></li>
          <li><a href="#">News Corner</a></li>
       </ul>
    </div>

9. Nav bar - project common navs. These navs are defined in your _projectCommon.php file and are displayed for all pages in your project. They are not visually different from other navs.


10. Nav bar - page navs. These navs are specific to one page, and are defined with the PHP file itself. They are not visually different from other navs.


Wide Layout

Pages can also be built to use a wider right hand column (Forced Width of 200px) by using the midcolumnwide and rightcolumnwide CSS tags.

<div id="widecontainer">
        <div id="midcolumnwide">
        </div>
        <div id="rightcolumnwide">
        </div>
</div>

Creating new pages

  • Step zero is to read the PHP Security Guide. Your web pages are now active PHP programs and thus security is everyone's business.
  • Before starting, ensure WebMaster has put these files in your project home directory: template.php and _projectCommon.php
  • Configure _projectCommon.php to specify the theme you want, and to add any project-wide navigation links you need. Uncomment (remove the leading "#") from the lines as required.
  • Copy template.php to a new name. For instance, index.php or downloads.php
  • Edit your new PHP page, and modify the page-specific settings, such as title, keywords, author, and page-specific Nav bars. Use a descriptive title and keywords to help search engines find your site easily.
  • . Commit your PHP page to the repository. It will be accessible from the web shortly.
  • If the page is replacing an old .html page, modify your html page to redirect to the new page (see Preserving Links).


Preserving links (using redirects)

Your old file.html has been replaced with file.php, so you want file.html to transparently redirect to file.php

  • Edit file.html and put only the following lines in it:
<html>
   <head>
      <meta http-equiv="refresh" content="0; url=file.php" />
   </head>
   <body>
      <a href="file.php">This document has moved</a>
   </body>
</html>
  • Commit your file.html
  • Test the redirect. It should work, you shouldn't see the body text, and your browser's back button should still work

Available Themes

  • Phoenix - the standard Eclipse.org theme
  • Lazarus - a variation on the Phoenix theme
  • Miasma - a light, easy to read theme


Available styles

Local Stylesheets - Overriding default styles in _projectCommon.php

The deafult styles can be overridden and expanded by calling a local stylesheet in _projectCommon.php. Here is some sample code:

   _projectCommon.php:
   <?php
       # Set the theme for your project's web pages.
       # See the Committer Tools "How Do I" for list of themes
       # https://dev.eclipse.org/committers/ 
       $theme = "Phoenix";
       
       # Define your project-wide Nav bars here.
       # Format is Link text, link URL (can be http://www.someothersite.com/), target (_self, _blank), level (1, 2 or 3)
       $Nav->addNavSeparator("Community","/community/");
       $Nav->addCustomNav("Events", "/community/events/", "_self", 1);	
   ?>
   <link rel=stylesheet type="text/css" href="/path/to/my/stylesheet.css">

/path/to/my/stylesheet.css would contain CSS elements that would override (or extend) the ones found in visual.css and layout.css.

If you need to override a specific property in the standard style sheet you can use the !important tag.

   standard layout.css 
   body {
        font-size:12px;
        font-weight:bold;
        background-color:#000;
   }
   local layout.css
   body {
        font-weight: normal !important;
   }

In the example above if you did not have the !important tag the font would remain bolded on your pages.

Project Status Infrastructure

  • Eclipse projects belong to a larger community - Eclipse - which is comprised of a not only the committers and developers on the project, but also the developers on other projects, plug- in developers outside the Eclipse projects, and the entire ecosystem surrounding Eclipse. In order to keep all these people up-to-date on the direction and status of the Eclipse projects, each project needs to provide timely and accurate descriptive and status information.
  • The project status information (files) drive a number of the eclipse.org web pages including the dashboard, the timeline, lists of projects, lists of mailing lists and newsgroups, status pages, and more.
  • The project status information files integrate with the Phoenix web structure and it's all explained in step-by-step detail (but on another set of pages).


Using polls

You can use an unlimited number of polls in any phoenix-based web page. Although polls may be used indefinitely, the results are deleted every three months.

  • To define a new poll, add this code to your PHP page:
   # Enable polls on this page
   # Polls are good for 3 months!
   $App->usePolls();
   # Poll 1
   $Poll = new Poll(1, "What's your favourite Phoenix skin?");
   $Poll->addOption(1, "Phoenix");
   $Poll->addOption(2, "Miasma");
   $Poll->addOption(3, "Blue");
   $Poll->addOption(4, "Industrial");
   $Poll->addOption(5, "I prefer frames");
   # $Poll->noGraph();  # uncomment to disable bar graph
   $pollHTML = $Poll->getHTML();


  • The $pollHTML variable now contains minimalistic HTML code to display the poll form or results.
  • Add the $pollHTML to your web page (here it's in a sideitem, but it can also be displayed in a homeitem):
Eclipse Insta-poll

<?= $pollHTML ?>


  • Define additional polls by copying the "Poll 1" block above, incrementing the value 1 to 2, and storing the HTML in a different variable:
   # Poll 2 - without a bar graph
   $Poll = new Poll(2, "Do you think this is another poll?");
   $Poll->addOption(1, "Yes");
   $Poll->addOption(2, "No");
   $Poll->noGraph();  # uncomment to disable bar graph
   $poll2HTML = $Poll->getHTML();
  • Polls are bound to the page where they are defined. To use the same poll across multiple pages:
    • instanciate Poll in each page where the poll should appear, or instanciate it once in _projectCommon.php
    • use the optional string-based ID representing the root URL of your project
   # Poll for multiple pages in the Phoenix website
   $Poll = new Poll(1, "Do you think this is another poll?", "http://www.eclipse.org/phoenix/");
   $Poll->addOption(1, "Yes");
   $Poll->addOption(2, "No");
   $Poll->noGraph();  # uncomment to disable bar graph
   $pollHTML = $Poll->getHTML();


Dates

Functions to provide a standardized date format have been added. Use the functions as follows:

$App->getFormattedDate("February 20, 2005", 'long'); $App->getFormattedDateRange("February 20, 2005", "February 25, 2005", 'long');

In both cases the final parameter is optional. If specified, it can be either 'short' or 'long' (default). Dates can be specified either as strings (that are parseable by strtotime()) or as UNIX timestamps.

Examples:

   $App->getFormattedDate("February 20, 2005", 'long');
   # returns the string "February 20, 2005"
   $App->getFormattedDate(1108875600, 'long');
   # returns the string "February 20, 2005"
   $App->getFormattedDate("February 20, 2005");
   # returns the string "February 20, 2005"
   $App->getFormattedDate("February 20, 2005", 'short');
   # returns the string "20 Feb 05"
   $App->getFormattedDateRange("February 20, 2005", "February 25, 2005", 'long');
   # returns the string "February 20-25, 2005"
   $App->getFormattedDateRange("February 20, 2005", "March 10, 2005", 'long');
   # returns the string "February 20-March 10, 2005"
   $App->getFormattedDateRange("February 20, 2004", "March 10, 2005", 'long');
   # returns the string "February 20, 2004-March 10, 2005"
   $App->getFormattedDateRange("February 20, 2005", "February 25, 2005", 'short');
   #  returns the string "20-25 Feb 05"
   $App->getFormattedDateRange("February 20, 2005", "March 10, 2005", 'short');
   # returns the string "20 Feb-10 Mar 05"
   $App->getFormattedDateRange("February 20, 2004", "March 10, 2005", 'short');
   # returns the string "20 Feb 04-10 Mar 05"


Using HTTP Parameters

Functions to provide a safe way to use HTTP parameters, either from the GET or the POST.

$App->getHTTPParameter("paramName" [, "method"]);

Where paramName is the name of the parameter, and method is optionally either GET or POST. When no method is specified, the POST is always returned, unless only a GET value exists.

Examples:

   # www.eclipse.org/somepage.php?page=abcdefg
   $page = $App->getHTTPParameter("page"); 
   # value of $page is "abcdefg"
   
   # <form method="post" />
   # <input type="hidden" name="page" value="mm1234" />
   $page = $App->getHTTPParameter("page"); 
   # value of $page is "mm1234"
   # <form method="post" />
   # <input type="hidden" name="page" value="mm1234" />
   $page = $App->getHTTPParameter("page", "GET"); 
   # value of $page is ""
   # <form method="get" />
   # <input type="hidden" name="page" value="mm1234" />
   $page = $App->getHTTPParameter("page", "POST"); 
   # value of $page is ""


RSS Feeds

Pages that provide an RSS feed can override the default site-wide RSS feed icon that is located in the Phoenix page header. Overriding the site RSS feed will also add a <link rel="alternate"> tag to the page header, making your page easy to subscribe to from browsers that support it.

To override the site RSS feed, simply define $App->PageRSS and $App->PageRSSTitle in your page-specific settings, as in the example code below. These settings may also be defined in _projectCommon.php so that your RSS feed is available throughout all the pages in your web space

   #
   # Begin: page-specific settings.  Change these. 
   $pageTitle = "My Web Page";
   $pageKeywords = "eclipse";
   $pageAuthor = "Someone";
   
   # Define my own RSS feed!
   $App->PageRSS = "/projects/downloads/rss.php";
   $App->PageRSSTitle = "Eclipse Project Feed";

Authenticated Users

Phoenix supports authenticated users using their Bugzilla credentials. The Login page is at http://dev.eclipse.org/site_login


   # Initiate session
   $Session = $App->useSession("optional");  # replace with "required" if a valid logged-in user is req'd
                                             # $App will redirect to the login page (and back) for login
   $Friend	 = $Session->getFriend();
   echo $Friend->getFriendID();
   echo $Friend->getFirstName();
   echo $Friend->getLastName();

Wiki Pages as Project Pages

The Eclipse skin now supports making pages on wiki.eclipse.org look like pages on www.eclipse.org. See here .

To use this feature all you need to do is add the following line to the top of a wiki article

{{#eclipseproject:toplevel.project}}

Note that url entries for the left nav in the Projectinfo DB have to be fully qualified(http://) and must belong to an Eclipse.org website, or else they will not be displayed.

The Metadata supports 2 style features for the custom left nav. First the 'separator' option will cause the entry to appear in a light-purple box with a 'down' arrow on the right side. Secondly the 'indent' option will change the distance of your text/url from the left side of the page. The default indent value(and lower limit) is 0, and the upper limit is 5

Custom Left Nav

It's possible to use the leftnav defined in your project meta data for the Wiki on your eclipse.org project pages as well. Use the following code slice:

 $Nav->addMetaNav("project.name");

Just insert this before you call $App->GeneratePage(). and it will load the left nav from the Meta data. The entries on the left nav have the same restrictions as those for the wiki. You can even combine this with the $Nav->addCustomNav() function to add extra items to a default left nav defined in the Meta data.

Adding a security question to a form

See Phoenix_formsecurity.