Projects/kde.org/Capacity HOWTO: Difference between revisions

    From KDE TechBase
    m (Text replace - "</code>" to "</syntaxhighlight>")
    m (Text replace - "<code php>" to "<syntaxhighlight lang="php">")
    Line 15: Line 15:
    Any normal page just contains:
    Any normal page just contains:


    <code php>
    <syntaxhighlight lang="php">
    <?php
    <?php
       $page_title = "Page Title";
       $page_title = "Page Title";
    Line 36: Line 36:
    An example {{path|site.inc}} would be:
    An example {{path|site.inc}} would be:


    <code php>
    <syntaxhighlight lang="php">
    <?php
    <?php
       // promote which subdomain we are
       // promote which subdomain we are
    Line 60: Line 60:
    The {{path|header.inc}} does some setup of global vars, even before it includes the {{path|site.inc}}, these are:
    The {{path|header.inc}} does some setup of global vars, even before it includes the {{path|site.inc}}, these are:


    <code php>
    <syntaxhighlight lang="php">
    $site_root
    $site_root
    $document_root
    $document_root
    Line 68: Line 68:


    * <tt>$site_root</tt> contains the relative path to the toplevel of the current site, like:
    * <tt>$site_root</tt> contains the relative path to the toplevel of the current site, like:
    <code php>
    <syntaxhighlight lang="php">
    $site_root = "../.."
    $site_root = "../.."
    </syntaxhighlight>
    </syntaxhighlight>


    * <tt>$document_root</tt> contains the absolute pathname which is the documentroot of this site, even correct if the site isn't in it's own vhost. Example:
    * <tt>$document_root</tt> contains the absolute pathname which is the documentroot of this site, even correct if the site isn't in it's own vhost. Example:
    <code php>
    <syntaxhighlight lang="php">
    $document_root = "/home/www/sites/www"
    $document_root = "/home/www/sites/www"
    </syntaxhighlight>
    </syntaxhighlight>


    * <tt>$url_root</tt> contains the absolute base url to the toplevel of your site, if your site would, for example, have a it's toplevel in http://127.0.0.1:8080/sites/www, like it is for staging, this would contain:
    * <tt>$url_root</tt> contains the absolute base url to the toplevel of your site, if your site would, for example, have a it's toplevel in http://127.0.0.1:8080/sites/www, like it is for staging, this would contain:
    <code php>
    <syntaxhighlight lang="php">
    $url_root = /sites/www
    $url_root = /sites/www
    </syntaxhighlight>
    </syntaxhighlight>


    * <tt>$current_relativeurl</tt> contains the relative part of the current url to the url_root, would you access http://127.0.0.1:8080/sites/www/whatiskde/manifest.php and /sites/www is the <tt>$url_root</tt>, it would contain
    * <tt>$current_relativeurl</tt> contains the relative part of the current url to the url_root, would you access http://127.0.0.1:8080/sites/www/whatiskde/manifest.php and /sites/www is the <tt>$url_root</tt>, it would contain
    <code php>
    <syntaxhighlight lang="php">
    $current_relativeurl = whatiskde/manifest.php
    $current_relativeurl = whatiskde/manifest.php
    </syntaxhighlight>
    </syntaxhighlight>
    Line 90: Line 90:


    The framework is clever, it will never add trailing slashs to the <tt>$site_root</tt>, <tt>$document_root</tt> and <tt>$url_root</tt>, therefor they can and must always be used like:
    The framework is clever, it will never add trailing slashs to the <tt>$site_root</tt>, <tt>$document_root</tt> and <tt>$url_root</tt>, therefor they can and must always be used like:
    <code php>
    <syntaxhighlight lang="php">
    $some_url = "$site_root/mycoolpage.php"
    $some_url = "$site_root/mycoolpage.php"
    </syntaxhighlight>
    </syntaxhighlight>
    Line 101: Line 101:


    * The Name for your whole subdomain/site, best set once in {{path|site.inc}}
    * The Name for your whole subdomain/site, best set once in {{path|site.inc}}
    <code php>
    <syntaxhighlight lang="php">
    $site_title = "KDE Foo Site Title";
    $site_title = "KDE Foo Site Title";
    </syntaxhighlight>
    </syntaxhighlight>


    * The title of the individual page.
    * The title of the individual page.
    <code php>
    <syntaxhighlight lang="php">
    $page_title = "Page Title";
    $page_title = "Page Title";
    </syntaxhighlight>
    </syntaxhighlight>
    Line 112: Line 112:
    * Don't show edit function on the page. The default is <tt>$showedit = true;</tt>. This setting should normally not be used. {{path|site.inc}} is the preferred place.
    * Don't show edit function on the page. The default is <tt>$showedit = true;</tt>. This setting should normally not be used. {{path|site.inc}} is the preferred place.


    <code php>
    <syntaxhighlight lang="php">
    $showedit = false;
    $showedit = false;
    </syntaxhighlight>
    </syntaxhighlight>
    Line 130: Line 130:


    It should look like this:
    It should look like this:
    <code php>
    <syntaxhighlight lang="php">
    <?php
    <?php
       $this->setName ("KDE Foo Site Title");
       $this->setName ("KDE Foo Site Title");
    Line 145: Line 145:
    Also you could show a little 16*16 Icon for each menu item.You should give the Icon url as the last argument to the appendDir or appendLink:
    Also you could show a little 16*16 Icon for each menu item.You should give the Icon url as the last argument to the appendDir or appendLink:


    <code php>
    <syntaxhighlight lang="php">
    <?php
    <?php
       $section->appendDir("A Subdirectory","subdirectory", true, false, "icon.png");
       $section->appendDir("A Subdirectory","subdirectory", true, false, "icon.png");
    Line 152: Line 152:


    To show an Icon with appendDir, just add icon url as the third argument, like this:
    To show an Icon with appendDir, just add icon url as the third argument, like this:
    <code php>
    <syntaxhighlight lang="php">
       $section->appendDir("A Subdirectory","subdirectory", "icon.png");
       $section->appendDir("A Subdirectory","subdirectory", "icon.png");
    </syntaxhighlight>
    </syntaxhighlight>
    Line 158: Line 158:


    The format is similar:
    The format is similar:
    <code php>
    <syntaxhighlight lang="php">
    <?php
    <?php
       $this->appendDir("A Subsubdirectory","subsubdirectory");
       $this->appendDir("A Subsubdirectory","subsubdirectory");
    Line 212: Line 212:
    The <tt>kde_general_news()</tt> can be used to easily show a new story on a page.
    The <tt>kde_general_news()</tt> can be used to easily show a new story on a page.


    <code php>
    <syntaxhighlight lang="php">
    <?php
    <?php
       kde_general_news($file, $items, $summaryonly)
       kde_general_news($file, $items, $summaryonly)
    Line 227: Line 227:
    A PHP class has been written to make it easy to write FAQs. It will always give a consistent formatting style. Using the class is simple:  
    A PHP class has been written to make it easy to write FAQs. It will always give a consistent formatting style. Using the class is simple:  


    <code php>
    <syntaxhighlight lang="php">
    <?php
    <?php
       $faq = new FAQ();
       $faq = new FAQ();
    Line 245: Line 245:
    {{Tip| If you want to have a fancy Image Gallery with Lightbox, pass <tt>True</tt> as the second argument to the <tt>imageGallery</tt> class.}}
    {{Tip| If you want to have a fancy Image Gallery with Lightbox, pass <tt>True</tt> as the second argument to the <tt>imageGallery</tt> class.}}


    <code php>
    <syntaxhighlight lang="php">
    <?php
    <?php
       $gallery = new ImageGallery("Add a summary for screen readers here");
       $gallery = new ImageGallery("Add a summary for screen readers here");
    Line 260: Line 260:


    The parameters of <tt>addImage()</tt> are as follows
    The parameters of <tt>addImage()</tt> are as follows
    <code php>
    <syntaxhighlight lang="php">
    addImage($src_url, $dest_url, $width_pixels, $height_pixels,
    addImage($src_url, $dest_url, $width_pixels, $height_pixels,
             $alt_text, $caption_text, $description_text)
             $alt_text, $caption_text, $description_text)
    Line 279: Line 279:
    For web sites like koffice.org and edu.kde.org it makes sense to have a sub-directory for each program that is part of the project and in that sub-directory have a page which shows information about the program. The AppInfo class has been designed to make it easy to create such a page. It can be used as follows:
    For web sites like koffice.org and edu.kde.org it makes sense to have a sub-directory for each program that is part of the project and in that sub-directory have a page which shows information about the program. The AppInfo class has been designed to make it easy to create such a page. It can be used as follows:


    <code php>
    <syntaxhighlight lang="php">
    <?php
    <?php
       $appinfo = new AppInfo("KWord");
       $appinfo = new AppInfo("KWord");
    Line 322: Line 322:
    For pages which have changed location, a custom mapping can be added in {{path|www/media/404.php}} so that the user can be directed to just about anywhere.
    For pages which have changed location, a custom mapping can be added in {{path|www/media/404.php}} so that the user can be directed to just about anywhere.


    <code php>
    <syntaxhighlight lang="php">
    <?php
    <?php
       include("handler.inc");
       include("handler.inc");
    Line 339: Line 339:


    Create a file named "locale.inc" in root folder and use the following content:
    Create a file named "locale.inc" in root folder and use the following content:
    <code php>
    <syntaxhighlight lang="php">
    <?php
    <?php
       $site_locale = "de";
       $site_locale = "de";
    Line 351: Line 351:
    If you want to translate random text of your web page you have to use one of the three i18n functions available, that is i18n(), i18n_var() and i18n_noop().
    If you want to translate random text of your web page you have to use one of the three i18n functions available, that is i18n(), i18n_var() and i18n_noop().
    * i18n is the function you want to use if you simply want to show a text that would be translatable, e.g.
    * i18n is the function you want to use if you simply want to show a text that would be translatable, e.g.
    <code php>
    <syntaxhighlight lang="php">
    <p><?php i18n("Some images of Okular in action...")?></p>
    <p><?php i18n("Some images of Okular in action...")?></p>
    </syntaxhighlight>
    </syntaxhighlight>
    * i18n_var is the function you want to use if you want to get a translated text in a way you can assign it to a variable, e.g.
    * i18n_var is the function you want to use if you want to get a translated text in a way you can assign it to a variable, e.g.
    <code php>
    <syntaxhighlight lang="php">
    <?php $site_title = i18n_var("Okular - more than a reader"); ?></p>
    <?php $site_title = i18n_var("Okular - more than a reader"); ?></p>
    </syntaxhighlight>
    </syntaxhighlight>
    * i18n_noop is the function you want to use if you simply want to mark your text as translatable because you know the translation will happen at a later stage.
    * i18n_noop is the function you want to use if you simply want to mark your text as translatable because you know the translation will happen at a later stage.
    <code php>
    <syntaxhighlight lang="php">
    <?php $page_title = i18n_noop('Frequently Asked Questions'); ?></p>
    <?php $page_title = i18n_noop('Frequently Asked Questions'); ?></p>
    </syntaxhighlight>
    </syntaxhighlight>


    If you want to show a language selector in your webpage you have to define the site_languages variable to hold the supported languages.
    If you want to show a language selector in your webpage you have to define the site_languages variable to hold the supported languages.
    <code php>
    <syntaxhighlight lang="php">
    <?php $site_languages = array('en', 'es', 'pt_BR', 'uk'); ?></p>
    <?php $site_languages = array('en', 'es', 'pt_BR', 'uk'); ?></p>
    </syntaxhighlight>
    </syntaxhighlight>

    Revision as of 20:59, 29 June 2011

    Note
    This projects page has been moved to [[1]]. Please don't edit on techbase anymore.


    Introduction

    Capacity is a versatile framework which helps you to construct your page by focusing on the content. Your pages will be simple PHP-files which include predefined header and footer. This header/footer layout the page, you only provide the real content and menu structure.


    Example PHP-file

    Any normal page just contains:

    <?php
      $page_title = "Page Title";
      include "header.inc";
    ?>;
    
      Content of the web page
    
    <?php include "footer.inc"; ?>
    

    The magic site.inc

    For each subsite, a site.inc in the toplevel directory of this page, which would be equal to the later documentroot on the server in many cases, may be created. This include is used by the header.inc, it should contain some information about your site, like its name and the email address of the webmaster, this will be used by header/footer to setup the page correct.

    An example site.inc would be:

    <?php
      // promote which subdomain we are
      // we are www.kde.org in this case!
      $site = "www";
    
      // use new style ;) yeah
      $templatepath = "newlayout/";
    
      // promote title to use
      $site_title = i18n_var("K Desktop Environment");
    
      // links in the top bar, right
      $menuright = array ('family/'=>'Sitemap',
        'contact/'=>'Contact Us');
    ?>
    

    Even in the site.inc you can already use the i18n-functions, which is important to have the names right on translated pages!

    Global Variables setup by header.inc

    The header.inc does some setup of global vars, even before it includes the site.inc, these are:

    $site_root
    $document_root
    $url_root
    $current_relativeurl
    
    • $site_root contains the relative path to the toplevel of the current site, like:
    $site_root = "../.."
    
    • $document_root contains the absolute pathname which is the documentroot of this site, even correct if the site isn't in it's own vhost. Example:
    $document_root = "/home/www/sites/www"
    
    • $url_root contains the absolute base url to the toplevel of your site, if your site would, for example, have a it's toplevel in http://127.0.0.1:8080/sites/www, like it is for staging, this would contain:
    $url_root = /sites/www
    
    $current_relativeurl = whatiskde/manifest.php
    

    BE AWARE: In former version of the framework it was common to set the $site_root manually before including the header.inc, this won't work now, as the header.inc will overwrite the $site_root. This should cause no danger, as header.inc should find out the right one, but in the long term, all manual definitions should be removed, the global variables header.inc exports should be used to replace the usage of the old $site_root.

    The framework is clever, it will never add trailing slashs to the $site_root, $document_root and $url_root, therefor they can and must always be used like:

    $some_url = "$site_root/mycoolpage.php"
    

    Configuration Variables

    You can set some variables to alter the behaviour of the framework, either global in your site.inc or in front of your header.inc inclusion in each .php-files.

    Useful variables are:

    • The Name for your whole subdomain/site, best set once in site.inc
    $site_title = "KDE Foo Site Title";
    
    • The title of the individual page.
    $page_title = "Page Title";
    
    • Don't show edit function on the page. The default is $showedit = true;. This setting should normally not be used. site.inc is the preferred place.
    $showedit = false;
    

    Online Editing

    Capacity features online editing and previewing of changes.

    You can make and preview changes of existing pages online by clicking on the [edit] link at the bottom of each page. Try it on this page. Then you can download you changes and commit them yourself via SVN, or you can click the link to email a unified diff to the web team.

    Menu Definitions

    The navigation menu is defined by a number of menu.inc files. They are included by a function in media/includes/classes/class_menu.inc, which is called from media/includes/header.inc. The general menu structure is defined in the menu.inc file of the root directory of each KDE subsite (e.g. http://www.kde.org/menu.inc or http://www.kde.org/areas/kde-ev/menu.inc).

    It should look like this:

    <?php
      $this->setName ("KDE Foo Site Title");
      $section =&amp; $this->appendSection("Inform");
      $section->appendLink("Home","");
      $section->appendLink("KDE Home","http://www.kde.org/",false);
      
      $section =&amp; $this->appendSection("A Second Menu Section");
      $section->appendDir("A Subdirectory","subdirectory");
      $section->appendLink("A Single Page","singlepage.php");
    ?>
    

    Also you could show a little 16*16 Icon for each menu item.You should give the Icon url as the last argument to the appendDir or appendLink:

    <?php
      $section->appendDir("A Subdirectory","subdirectory", true, false, "icon.png");
    

    in the Above code, first argument is the title of the menu, second argument is the url, third argument defines that if this menu item is relative, forth argument should be True if it links to a directory and last argument is the Icon

    To show an Icon with appendDir, just add icon url as the third argument, like this:

      $section->appendDir("A Subdirectory","subdirectory", "icon.png");
    

    Each mentioned subdirectory will then also be searched for a menu.inc file to define a submenu (e.g. http://www.kde.org/whatiskde/menu.inc).

    The format is similar:

    <?php
      $this->appendDir("A Subsubdirectory","subsubdirectory");
      $this->appendLink("A Page in the Subdirectory","singlepage.php");
    ?>
    

    The content of subsubdirectories is currently not added to the menu, but this may change in future. If a subdirectory has just the index.php file or a submenu for the subdirectory is not desired, then an empty menu.inc can be added. If the menu.inc is missing, then the subdirectory is be treated like having an empty menu.inc file.

    Headlines

    The main headline of a page is defined via $page_title. If a page has several sections with a headline each, <h2> is used for them (<h3> for subsections):

    <a name="section1" />Section Headline

    Subsection Headline

    </syntaxhighlight>

    Headlines must never be used to increase the size of a text. Use <b> to make it stick out. The first letters of every word of a headline or link should be capitalized, apart from small words like "a", "to", etc.

    To allow better navigation through the site, each <h2> heading should be linked from a quicklinks section on top of the page: