|
From: <gar...@us...> - 2004-02-25 08:49:03
|
Update of /cvsroot/php-blog/serendipity In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv28429 Added Files: README Log Message: Added temporary README file. Should be superseded by a real documentation somewhen. :-) --- NEW FILE: README --- ############################################################################### # README # ############################################################################### (Temporary document until a final documentation draft is finished!) ############################################################################### # THE 'embed' CONFIGURATION DIRECTIVE # ############################################################################### In your serendipity configuration, you can set an 'embed' option to true or false. This defines, whether you use your blog as a standalone webpage - or if you have different content wrapped around your blog, like the menu of your usual homepage. By setting the 'embed' option to true, you have to make sure the following things to get everything to work well: 1. 'indexFile' option. This configuration option needs to be set to the wrapper file you want to use. Let's say you normally have a 'content.php' file for your webpage. This 'content.php' file sets up your internal templates, your menu structure and such. Now you want this file to be used to include your weblog. A simple content.php could look like this: <?php $homepage = new Template_Class; $homepage->set_template($_REQUEST['page']); $homepage->output_header(); $homepage->output_content(); $homepage->output_footer(); $homepage->track_statistics(); ?> So normally your file would be called with 'content.php?page=about' to display your 'about' page of your personal homepage. Now we want this file to be displayed, having the 'page' variable being set to 'blog'. For this, we set up a 'wrapper.php' file: <?php $_REQUEST['page'] = 'blog'; // Let serendipity generate our content: ob_start(); require 'index.php'; $blog_data = ob_get_contents(); ob_end_clean(); // Now we include our normal content building file. // This one has to make use of your $blog_data variable to print // the content where appropriate! require 'content.php'; ?> You would then set your 'indexFile' serendipity-option to the 'wrapper.php' file. 2. Plugin panes & HTML-headers With the example above, we only get the main blog data printed. One of the most visible actions when using the 'embed' option is that the plugin panes are not generated. And HTML headers/foooters are also not provided by s9y in this case, as this should be done by your 'content.php' file. So you have to include them in your 'content.php' file, to have them visible in your embedded setup. You can use this snippet: <?php serendipity_plugin_api::generate_plugins('left','div'); serendipity_plugin_api::generate_plugins('right','div'); ?> somewhere in your 'content.php' file. The 'embed' option is therefore only recommended to be used by advanced users going for a most flexible setup! ############################################################################### # NOTES FOR CONDITIONAL GET IN RSS FEEDS # ############################################################################### Serendipity supports an HTTP-cache compatible way of only showing items in an RSS feed which where modified since the last request from a client. Typically, an RSS reader fetches your RSS feeds (15 items, per default). It then remembers the timestamp when those items where fetched. By the time your RSS reader updates the feed (typically after 1 hour) Serendipity will now only serve all new or modified items since the last time of refresh. If no entries where updated since then, serendipity will only serve the 304 Header (Not Modified) and saves a lot of bandwidth for both client and server on periodical updates. Technically an RSS reader catches the "Last-Modified" Header of the RSS output as well as a special "ETag"-Header. Both are set to the last modification time of your article base. On the next fetch, those received headers are sent as "IF_MODIFIED_SINCE" (= Last-Modified) and "IF_NONE_MATCH" (= ETag) Headers and will affect your rss feed. This saves a lot of bandwidth on both client and server side. Users who have been watching your feed and where not able to catch up the latest articles may miss some of them, because you usually only get 15 items per feed. In case your reader provides the IF_MODIFIED_SINCE header the client can now catch all items (resp. a maximum of 50 articles to prevent abuse). If you want to permanently disable that feature (whatever the reasons are) you can either set a "$_REQUEST['nocache'] = true" inside your rss.php file (first line) or append the '&nocache=true' request variable to your feed so that it looks like: http://example.host/serendipity/rss.php?version=2.0&nocache=true. Of course, the usual feed behaviour is not affected if none of the caching headers are provided. So if you use syndication methods to embed content from a blog inside an application, just tune your application to either send the 'nocache'-Variable to a Serendipity blog, or to not send the caching headers. The syndication plugin can be configured to append that variable to your feed URLs from your blog. ############################################################################### Serendipity Weblog - http://s9y.org Licensed under the BSD License # $Id: README,v 1.1 2004/02/25 08:42:01 garvinhicking Exp $ |
