README.md 6.09 KB
Newer Older
S. Zeid's avatar
S. Zeid committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148
Portal
======

Copyright (C) 2006-2012 Scott Zeid  
[http://code.s.zeid.me/portal](http://code.s.zeid.me/portal)

Introduction
------------
Portal is a PHP script that displays a list of Web sites.  It can be used as
a personal home page, for example.  Here are some features of Portal:

* Each site can have a name, icon, and description.
* The color scheme and various layout options can be customized.
* Contains optimizations for smartphone browsers.
* Contains a "minibar" mode that can be added to the top or side of your other
  sites as an iframe.  The active site can be highlighted.
* Supports Google Analytics with both new- and old-style code.
* Supports OpenID header tags.
* Validates as HTML 5 and CSS 3.
* Free, open source software released under the X11 License.

To see a live example of Portal, go to <http://more.s.zeid.me/>.
You may also [look at its configuration
file](http://more.s.zeid.me/portal-data/settings.yaml).

Installation
------------
To install Portal:

1. Copy `index.php` and `portal-data` to your document root or whatever folder
   you want to install it in.
2. Rename `portal-data/settings.yaml.dist` to `portal-data/settings.yaml`.
3. Edit that file to change the settings and add sites.  (Documentation for
   `settings.yaml` is contained within itself.)
4. Add icons to `portal-data/icons` and `portal-data/icons/small`.
   Corresponding icons in both folders should have the same file names.  Icons
   in `portal-data/icons` should be 32x32 pixels in size, and icons in
   `portal-data/icons/small` should be 16x16 in size.  If you only plan on
   using the small icons and/or minibar, you may leave out the large ones, and
   vice versa.

If you want to change the name or location of portal-data, you will also need
to update the `$CONFIG_DIR` variable in index.php accordingly.

Query string parameters
-----------------------
Portal supports the following query string parameters:

* `device={android,webos,apple,apple-tablet}` - force the mobile device type
* `minibar` - render a minibar (see below for more info and related parameters)
* `mobile` - use the mobile stylesheet
* `!mobile`, `nomobile` - do not use the mobile stylesheet
* `narrow` - force the Portal to be narrow
* `!narrow`, `wide` - force the Portal to not be narrow
* `small` - force the icons and text to be small
* `!small`, `large`, `big` - force the icons and text to be big
* `target` - use the specified value as the target attribute for site links
* `theme` - use the specified theme name (must be a key in `settings.yaml` >
            `themes`)
* `403`, `404` - causes Portal to render a 403 or 404 error page

OpenID support
--------------
If you use OpenID and your provider allows you to, you can use your Portal's
URL as an alias for your OpenID.  To set this up, you would look in your OpenID
provider's help pages for something that looks like "Use your own URL", and
then look for some HTML code that looks something like this:

    <link rel="openid.server" href="http://www.myopenid.com/server" />
    <link rel="openid.delegate" href="http://youraccount.myopenid.com/" />
    <link rel="openid2.local_id" href="http://youraccount.myopenid.com" />
    <link rel="openid2.provider" href="http://www.myopenid.com/server" />
    <meta http-equiv="X-XRDS-Location"
     content="http://www.myopenid.com/xrds?username=youraccount.myopenid.com" />

Then you would copy the URLs from that code and paste them into the respective
keys in `settings.yaml` > `openid`.  You can omit either `provider` and
`local_id` or `server` and `delegate` if your provider does not give you those
URLs.  However, `server` and `provider` are often the same, as are `delegate`
and `local_id`.

For example:

    openid:
        # OpenID server URL
        server:   http://www.myopenid.com/server
        # OpenID provider URL
        provider: http://www.myopenid.com/server
        # Delegate URL
        delegate: http://youraccount.myopenid.com/
        # Local ID URL
        local_id: http://youraccount.myopenid.com
        # XRDS URL
        xrds:     http://www.myopenid.com/xrds?username=youraccount.myopenid.com

Note that Portal sends the `X-XRDS-Location` URL as an actual HTTP header, and
not a meta tag, because the latter would prevent Portal from validating as
HTML5.

Minibar
-------
Portal has a "minibar" feature.  This allows you to add a bar to the top or
left (for example) of a Web page of yours that contains a miniature version of
your Portal.  Example HTML code for a horizontal minibar:

    <div id="portal-minibar" style="width: 100%; height: 23px;">
     <iframe src="http://your.portal.example/?minibar&highlight=awesome-site"
       style="width: 100%; height: 23px; border-style: none; overflow: hidden;"
       frameborder="0"></iframe>
    </div>

The `highlight` parameter is optional, and is the name of the key for the site
you want highlighted.  For example, if your sites section looks like this:

    sites:
        awesome-site:
            name: My awesome site
            icon: awesome-site.png
            url:  http://awesome.site.example/
            desc: There's some awesome s*** here!

and you want "My awesome site" to be highlighed, you would use
`&highlight=awesome-site`.

The default orientation is horizontal, unless you changed `minibar-orientation`
to `vertical` in settings.yaml.  You can also add `&vertical` or `&horizontal`
to the URL to change the orientation.  Here's an example for a vertical minibar
that is fixed to the left-hand side of the screen:

    <div id="portal-minibar"
      style="position: fixed; top: 0; bottom: 0; left: 0; height: 100%;">
     <iframe src="http://your.portal.example/?minibar&vertical&highlight=slug"
       style="width: 24px; height: 100%; border-style: none; overflow: hidden;"
       frameborder="0"></iframe>
    </div>

If you do not want a site to appear in the minibar, add the following line to
your site:

            minibar: False

If you want the site to appear in the minibar but not the main page, add this:

            index: False

You can also add both lines if you want to completely hide the site from your
Portal.  If the URL is not set, then the site will automatically be hidden from
the minibar.