Frequently Asked Questions

The Frequently Asked Questions are to be read as a timelined informational page. Just have that in mind while reading: Some question/content is not in that much of interest as it was years ago. Things change; And may get better, periodically.

General information

Where does the name Serendipity originate from?

While Serendipity in itself means “The faculty of making fortunate discoveries by accident.”, the name was invented by Horace Walpole 1754, which became used and famous since the 19th century.

What does “s9y” mean? “s9y” is an abbreviation of “Serendipity”, much like “i18n” is an abbreviation of “Internationalization”.

top

Installation requirements

How do I install Serendipity?

Just download the release package to your server, unpack it inside your document root, make sure the created directory is writable by the webserver (in most cases /chmod 770 serendipity/ will do) and open it in your web browser. You will see the installation screen that lets you set up Serendipity. You’ll be up and running in about 2 minutes!

top

What system requirements does Serendipity have?

You need a modern PHP installation together with MariaDB (MySQL), PostgreSQL or SQLite . We also require the Apache webserver, because we utilize a number of internal functions to make Serendipity run correctly. To fully enjoy Serendipity, you should have either ImageMagick’s convert binary installed on your server (recommended), or a PHP installation with GD2 support.

The name MySQL is further on used as a synonym for the chosen database.

top

Serendipity asks me for entering data to a database, but when I enter a name and install Serendipity it tells me the database does not exist

Serendipity requires that you have already setup the Database in your favorite database system. For MySQL you can create a database with CREATE DATABASE serendipity; for example, on postgreSQL you can do that via createdb serendipity. The username you enter in the Serendipity Installations also requires that this username already exists. On MySQL you create users via the “GRANT” feature subset. Use a tool like phpMyAdmin to easily create users, or just enter the credentials you were given from your hoster. On postgreSQL you can create a user with createuser serendipity for example.

The reason why Serendipity does not create a database automatically is because on most hosting providers you already have an existing database (like usrdb_htdu1_sql) and are not able to create more databases. To make Serendipity detect that and guess the right user privileges would be too error-prone. So it is best that you create an empty database with the right privileges to use for Serendipity (assign CREATE, INSERT, UPDATE, DELETE, ALTER and INDEX privileges for the SQL user account).

top

Errors/Problems

When I use mod_rewrite URL rewriting, I cannot access any files in subdirectories of my Serendipity install | If I go to any of my own URLs it keeps redirecting me to my blog page

You need to put a .htaccess file into each subdirectory which is not related to Serendipity. The only contents of this file needs to be “RewriteEngine Off”. With this you tell the Webserver that the directory is independent from Serendipity and thus no Serendipity Rewrite-Rules shall be applied. Regard: .htaccess file rules match to any following subdirs.

top

The search doesn’t work!

The search on mysql systems uses the internal fulltext mechanism of MySQL. That system only starts working to find entries once you’ve made a couple of them. With a single entry, the search never shows a result. Dummy entries only containing “test test test” will also not be found. This behaviour is documented in the MySQL documentation.

top

What are the file permissions required to run Serendipity?

Serendipity’s installation usually ships with proper permissions within the named package zip.

Upon installation, Serendipity needs to create the files .htaccess and serendipity_config_local.inc.php. That is why the core directory needs to be writable for your webserver user (775 or 777 on some installations). Those two files will then be created in a way, that Serendipity can always write to those files later on. It needs to be able to do that for upgrading purposes - so leave those files writable after installation. You can then re-adjust your core directory to be only executable for the webserver user (i.e. 755).

Then Serendipity needs to be able to constantly have write and privileges for the directories templates_c, archives and uploads plus all the files contained there. templates_c is an empty directory when installing Serendipity and it holds the compiled Smarty Templates. archives holds additional temporary files, and uploads contains your media files. Always set those folders and files to be writable for your server.

If you are planning to use Spartacus, you also need to make the plugins directory writable for the webserver user, so that plugins can be downloaded to that directory. Also make templates writable for the webserver if you plan to download additional themes via Spartacus. The Spartacus configuration offers you an interface to tell which permissions (chmod/chown) it shall perform for those downloaded files.

To sum it up: After installation, the only permissions you may want to adjust are those of the core directory, which you can set to 755 (of course this depends on your user/group configuration - you need to know that on your own).

If you’re especially paranoid, also change the serendipity_config_local.inc.php and .htaccess files to be only readable for the webserver. But then you need to remember to make those files writable when you upgrade Serendipity!

top

Blog Is Blank / White page

Blank blog pages almost always mean the server has encountered an error. Luckily, web servers almost always keep track of errors in a log file. Ask your provider for the error logs for your web page; they’ll tell you what the problem is.

If you’re having trouble finding the logs, you can try modifying your .htaccess with these lines:

php_value display_errors on
php_value error_log /path/to/your/serendipity/errors.log

Of course, replace path/to/your/serendipity with the path to Serendipity on your server. Unfortunately, not all providers will allow you to do this. But if it works, you can read the errors.log in your Serendipity directory to determine the problem.

top

When I save/preview an entry, it shows my admin panel in the preview section! Or: I need to login after each page request, and can’t perform any action!

This can happen, if your Webserver/PHP is not properly configured to use HTTP Cookie sessions. Serendipity requests PHP to have HTTP Session cookies enabled, and the session extension properly working.

top

The dates / weeknames are not displayed according to my language, but all other things display correctly!

To display date and time formats specific to national conventions, Serendipity uses a system called “Locales”. This system is both available on Linux and Windows and adjusts the native language of the system. A system can contain multiple locales to choose from, and Serendipity employs them via the “LOCALES” constant found in your lang/serendipity_lang_XX.inc.php.

This means, one of the Locales specified there need to be existing on your server. You will need to ask your System administrator to install the locale you want to use or install it yourself with tools like “locale-gen”.

top

Upgrading

How do I upgrade Serendipity?

Serendipity has an automated upgrade system. You can upgrade from any Serendipity version starting from 0.4 to the latest version, even nightlies/snapshots - and you will not loose any previous content. First of all, you should make a backup of your existing installation by copying your whole directory and by creating a Database dump (use phpMyAdmin or something similar).

After you have done that, you only need to extract the new Serendpipity release files over your old directory. Make sure that you never delete the serendipity_config_local.inc.php file, as it contains the most vital Serendipity configuration data.

SECURITY RECOMMENDATION:: To make sure that only you are authorized to execute the update, either use the or edit your .htaccess file to block access only to your current IP or create a username/password combination, as outlined in the following lock notes

top

Locking the blog during the upgrade

Create this .htaccess file in your server webroot (or edit the existing one):

AuthType Basic
AuthName "Authorisation: Serendipity Upgrade IN PROGRESS"
AuthUserFile /absolute/path/to/your/serendipity/.htpasswd
require valid-user
# BEGIN s9y
#
# END s9y

Note the BEGIN/END s9y section - if you use a fresh .htaccess file, this marker needs to exist. If this already exists in your file, you do not add it a second time.

Then create a file .htpasswd using a simple ‘username:md5password’ combination. Look at http://www.htaccesstools.com/htpasswd-generator/ for an online generator for .htpasswd files.

s9y:s9QXoc9dcFOT2

This would create a user “s9y” with password “s9y” with which you’d have to log into your blog.

SECURITY RECOMMENDATION: Do not skip this step due to security implications. You want to make sure that only you are authorized to update the blog, and calls to your site from others are prevented while you are upgrading.

Then go to your Serendipity Admin Panel and you will see the Serendipity upgrader.

It will tell you which version you are running, and which tasks are going to get executed. That means some PHP functions can be called, and some DB updates are called. The DB update files are stored in the sql/ subdirectory of Serendipity.

Before you continue the process, make sure that the PHP/Apache webserver is able to write to your serendipity_config_local.inc.php and .htaccess file, and that the directory templates_c/ exists and is writable. You can change permissions using chmod commands in your favorite FTP or SSH client.

Also make sure that your configured database users are privileged to execute ALTER TABLE, CREATE TABLE and CREATE INDEX commands!

When you have ensured all the things mentioned, you can click on the Upgrade button.

If you encounter any errors on the next page, write them down carefully and go to ask the Serendipity Forums for help. Most errors happen if your SQL user does not have sufficient privileges, or one of the mentioned files could not be written.

top

My upgrade failed! (or: I cannot change permissions of my files)

Even though the Serendipity Team strifes to have the best upgrading facility, there might always been errors and you might want to re-execute your update.

In most cases it is no problem to re-execute an update of Serendipity. If you upgraded from Serendipity 2.0.0 to 2.2.0 for example, and your MySQL user had not sufficient privileges, you want to re-execute all SQL statements again.

The easiest method would be to restore the backup you made previously, and then run the upgrade again. If you haven’t made the backup or want to make it faster, you can do that by:

  1. Edit your serendipity_config_local.inc.php file. Usually that file is only writable for the webserver. If you cannot modify it via SSH/FTP, you can create a simple fixperm.php script in your Serendipity directory with these contents:
  2. fixperm.php

    <?php
    chmod('/path/to/your/serendipity/serendipity_config_local.inc.php', 0777);
    ?>

    On some hosts, the user as which your webserver runs is different than the user that you have FTP/SSH privileges for. In usual environments, your FTP user should be within the same group like your webserver user, so that you are able to modify files with the right umask. However, some providers might not think about that and thus deny you access to your own files. In those cases you also need the script above to change file permissions if you need to manually edit/delete a special file. Note that plugins copied by Spartacus and images uploaded via the Serendipity-Admin-Suite are affected by the same problem. You can change the default file/directory of the Spartacus plugin though by it’s configuration.

    Then call that simple script via http://yourblog/serendipity/fixperm.php and the filepermissions will be changed so that you can write the file. For security reasons, change the permissions of the config file back to what it was previously after upgrading (like 0744 or so).

  3. Now that you can edit the serendipity_config_local.inc.php file, locate the string
  4. $serendipity['versionInstalled'] = '2.2.0';

  5. Just set the version to “2.0.0” or whatever version you upgraded from, then save the file and re-enter your Serendipity Config Panel. The upgrader will say hello to you once again and re-execute the steps!
top

How can I move an existing Serendipity installation to a different place (server or path)?

First, you copy over all files from your old server to the new server. Especially pay attention that you copy the .htaccess and serendipity_config_local.inc.php files as well. If those files are not readable by your FTP user, you can use the little fixperm.php script from the “My upgrade failed!” section above to fix the permissions so that you can read the files.

Second you must migrate the database. Use a tool like phpMyAdmin to create a db SQL dump file. Re-import that file on your new server.

On your new server, make sure that all the permissions are set like they were on the old provider. Especially make sure that the files serendipity_config_local.inc.php and .htaccess are read+writable by the server, and the directory templates_c/ and uploads/ is read+writable by the server.

Now edit the serendipity_config_local.inc.php file, you might need to insert the new DB user account data into that file. You also might need to edit your .htaccess file to set the new paths properly.

Now you should be able to re-login into the Serendipity Admin panel without a problem. Go to your configuration and see if you need to reconfigure any of the paths listed.

If you had a lot entries or HTML nuggets where you manually used the path of Serendipity, and this has now changed, you need to manually edit the articles to insert the new URL!

Then you should be done.

top

Operating Serendipity

I’ve changed my SQL user password and now can no longer login to Serendipity!

If you change your SQL account password, you must change it for Serendipity as well. Go and edit your serendipity_config_local.inc.php file to set the new password there. You might then also need to check your serendipity_config DB table and set the new password for the “dbPassword” row there as well, and then you can already access your blog again.

top

Help, my blog looks ugly, no stylesheets seem to be applied, and I get HTTP 404 errors or even 500 internal server errors all the way when browsing the page!

  1. Url Rewriting
  2. Serendipity offers several forms of URL Rewriting, to make your URLs look pretty. So instead of having the URL http://localhost/index.php?article=1 you can have something nice like http://localhost/archives/1-myentry.html.

    To achieve this, Serendipity either uses mod_rewrite or the Apache Errorhandling functionality. Both may not be available on all hosts, and require a certain setup (“AllowOverride All”) to apply rewriting within your .htaccess file. Serendipity tries to auto detect your best setting in the installer, but under certain circumstances, this might fail. Or you might even change the suggested setting during installation without knowing the problems.

    The problems of enabling URL Rewriting without meeting the requirements are the problems you’re now having: Stylesheet URLs cannot be find, article links cannot be found and so on, or even your .htaccess might contain “dangerous” settings.

    You can easily fix this by entering your admin panel with the http://localhost/serendipity_admin.php URL. Then enter the configuration area, and set “URL Rewriting” to “None” and save your config. Make sure your .htaccess file is writable!

    Another problem that calls this symptoms is that your .htaccess file might not be parsed/readable by the webserver. Check your permissions or contact your provider to check the Apache errorlogs for detailed information.

    What can also affect the symptom of “no stylesheets are used” is if you enabled the ‘embed’ directive in Serendipity Configuration. As mentioned in the Configuration, if you enabled this setting, you must take care for the HTML head and body sections for yourself, Serendipity only outputs the straight content and nothing different. So either disable the embed mode, or use it as intended. :-)

  3. CORS - Cross-Origin Request Policy/Security
  4. If you get this kind of error message:

    Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at 'blahblah'. This can be fixed by moving the resource to the same domain or enabling CORS.

    and you main backend navigation buttons look strange, you might have a cross-origin request policy error, assuming some (font) files not allowed to load. Usually, this would only happen if for instance the font files lived on a different server.

    Assuming that you can edit your .htaccess file (with a text editor), you should be able to fix this by adding something to it. First, check if there is a file called .htaccess in the root directory of your web space (i.e. the directory to which you installed Serendipity). The file might not be shown in your FTP tool (FileZilla) because of the beginning dot; check its preferences “Display hidden/system files” to make it show up.

    If you do have an .htaccess file, it should already contain a line that says

    # BEGIN s9y

    Before that line, you would need to add the following code to it (and save it, of course):

    <IfModule mod_headers.c>
        <FilesMatch "\.(eot|otf|tt[cf]|woff2?)$">
            Header set Access-Control-Allow-Origin "*"
        </FilesMatch>
    </IfModule>

    That should allow cross-origin requests for web fonts. Have a little patience with it, on some servers changes to the .htaccess take some time.

top

The text in a blog entry has additional spacing

Check your source using your browser’s View/Source capabilities. Are there extra <br /> tags where the extra space occurs? If yes, check the settings of your nl2br event (serendipity_event_nl2br) plugin.

  • If you use a WYSIWYG editor to write your entries this should not occur.
  • If you just use the simple PLAIN TEXT editor you want them to have.
  • If you use another markup editor like textile or markdown, or write HTML per hand, disable the use for entries.

top

Entries Display HTML

This is sometimes caused by the Wiki Markup plugin. If it’s installed, remove it and see if the problem is corrected. The Wiki Plugin is outdated and unmaintained.

The “Options for trustworthy editing on multi-user blogs” plugin can also cause this problem. It’s main purpose is to escape any HTML that was entered by a non-trusted user, so if you’re not one of the trusted users, your images and formatting will show up as HTML! Either add yourself to trusted users, or remove the plugin to correct the problem.

Other possible causes include entering HTML in the WYSIWYG editor and improper imports.

To enter custom HTML in the WYSIWYG editor, you must click the button that places the editor into tag-editing mode. Sometimes this is marked “View Source” or “Show HTML”. If you tried to enter, for instance, an tag in WYSIWYG mode, you’d see the tag in your entry. Edit the entry to correct the problem.

If your imported entries display HTML tags, you’ll probably have to modify the database. The easiest method is to create a database dump. This is a plain text file; you can then edit it and replace all the instances of “&lt;” with “<” and “&gt;” with “>”.

top

What is “Spartacus”? How do I install Spartacus?

Spartacus is the name of the Serendipity Online Plugin Repository, and the name of the corresponding plugin of your Serendipity blog that connects to this repository.

You can view all the plugins of that repository here Styx additional plugins.

Nowadays this plugin is already installed and activated by default.
To install the plugin on your Serendipity Installation, follow these instructions:

  1. After installation, you go to your Serendipity admin interface.
  2. There you click on “Configure Plugins”. Then go down to the page and locate the link “Install event plugins”. Click that link.
  3. You will now see a list of default Serendipity Event Plugins you can install. Locate the Plugin called “Spartacus” and click on the install button next to it.
  4. After you have done that you will see the configuration screen of that plugin. You can leave all settings as-is. If you later have any troubles with plugin downloads you might want to play with the settings offered there.

Now the spartacus plugin is activated and will fetch a list of plugins the next time you choose to install a plugin. So go to the plugin manager again, click on the “Install event plugins” link again. Now Spartacus should fetch plugins from the remote repository and display them to you.

If you get any network errors or download failures, either the repository mirror servers (SourceForge.net or the default GitHub.com) are down. Or your server might be firewalled and does not allow outgoing connections, in which case you’ll need to talk with your provider about this.

Now you can click on any plugin to fetch it; The shortname, plugin-version and short description is hidden in the clickable arrow info box underneath the title.

top

How can my users subscribe to an entry?

It’s possible to get an email whenever new comments are submitted to an entry by leaving your email address with a comment and checking the subscribe box.

If your users don’t want to leave comments, they’ll have to use the Comments RSS feed. The default templates don’t supply the comment feed for individual comments; to do this, you’ll need to edit entries.tpl and insert a line like this:

<a href="http://myblog/myblog_path/rss.php?version=2.0&type=comments&cid={$entry.id}">RSS feed for this entry's comments</a>
top

Customization request

I don’t want to have comments and trackbacks in my blog!

First off, blogging is about getting contributions and comments. Having said that, you can turn of the comments and trackbacks by editing your entries.tpl template and removing the trackback/comment sections. Or you can also even use CSS to set “display: none” for those regions.

You can turn off to receive trackbacks/comments in the configuration of your spamblock plugin. To totally ban trackbacks from your site, you can edit the Serendipity file comment.php After the first <?php add this:

if ($_REQUEST['type'] == 'trackback') die('Disabled');

The other way you have is to edit your .htaccess file and add a mod_rewrite (if your server supports that, of course) rule to block calls to your comment.php:

((Rewrite Cond)) %{QUERY_STRING} ^.*type=trackback.*$ [NC]

((Rewrite Rule)) ^.*comment.php.*$ - [F]

If you do not want your blog to send outgoing trackbacks, you can edit your serendipity_config_local.inc.php file (or serendipity_config.inc.php, just as you prefer) and insert this line:

$serendipity['noautodiscovery'] = true;

This will make Serendipity not send any outgoing trackbacks.

Removing the trackback links from your blog entries won’t stop the spammers, but it will change the appearance of your blog. To disable trackbacks altogether, you’ll want to read about the Spam Protector plugin.

The trackback display is printed from the entries.tpl file. This will be in the templates/ directory, under your current template’s subdirectory. If your theme doesn’t use its own entries.tpl, it will use the one in templates/default/ instead. If it does use its own entries.tpl, the lines below may vary slightly.

All you need to do is remove these lines from your entries.tpl:

{if $entry.has_trackbacks}
 {if $use_popups}
    | <a href="{$entry.link_popup_trackbacks}" onclick="window.open(this.href, 'comments', 'width=480,height=480,scrollbars=yes'); return false;">{$entry.label_trackbacks} ({$entry.trackbacks})</a>
  {else}
    | <a href="{$entry.link}#trackbacks">{$entry.label_trackbacks} ({$entry.trackbacks})</a>
  {/if}
{/if}

Don’t forget to get these ones, too:

<div class="serendipity_comments serendipity_section_trackbacks">
  <br />
  <a id="trackbacks"></a>
  <div class="serendipity_commentsTitle">{$CONST.TRACKBACKS}</div>
  <div class="serendipity_center">
    <a rel="nofollow" style="font-weight: normal" href="{$entry.link_trackback}" onclick="alert('{$CONST.TRACKBACK_SPECIFIC_ON_CLICK|escape:htmlall}'); return false;" title="{$CONST.TRACKBACK_SPECIFIC_ON_CLICK|escape}">{$CONST.TRACKBACK_SPECIFIC}</a>
  </div>
  <br />
  {serendipity_printTrackbacks entry=$entry.id}
</div>

You can check for other lines including the word “trackback” and remove any of them you find problematic, too.

top

How to fight spam

Use the Spamblock-plugins provided. We recommend the anti-spam trinity: the core Spamblock-plugin with its wide selection of anti-spam measures (be sure to read about the Spam Protector), the first defense line Spamblock-Bee plugin with its honeypot and hidden captcha, plus (the optional) Spamblock-bayes plugin, a local learning spamfilter.

  1. Spam Protector - Blocking spam with the "Spam Protector" plugin
    What is the core Spamblock plugin?

    Serendipity ships with a default event plugin called “Spam Protector” that is used to fight blog spam. Do not remove!

    This plugin is also installed by default in your Serendipity installation. You can find it’s configuration by going to the Plugin Configuration menu in your Admin Interface and clicking on the title “Spam Protector” of the listing of event plugins.

    The Spam Protector will check each comment and trackback that is made on your blog; either via API (wfwComment, Trackback) or via your using blog interface (extended entry, comment popup).

    Each comment will be analyzed through different, configurable facilities. If any configured option qualifies the comment as spam, it will be set to “moderation” or “rejected” state. Moderated comments will show up in your Admin section “Comments”, where you can either remove the comment or activate the comment to be seen on your blog. If configured, you will also receive a mail about moderated comments.

    Choose logging method

    One very important thing in blocking spam is to check, WHAT you are blocking. Since you are only notified of moderated spam by email, you might want to check what kind of spam you reject every day. For that you can enable this option and either set it to “Database” or “File”. The preferred way is to use database-based logging, because then you can check the “serendipity_spamblocklog” DB table with tools like phpMyAdmin easily. There you will also see rejection details!

    Was that all?

    Since spam adapts nearly daily, the best thing to keep spam low is to check your wordfilters, url filters and author name filters from time to time, and add new common URLs or Author names to your blacklist. But the first thing is is to have the right order of defense. Absolutely recommended is this order in your plugin list: 1. Spamblock Bee, 2. Spamblock Spam Protector, (and optional) 3. Spamblock Bayes.

    Adapting spam from the Comment Moderation Panel

    In your comment moderation panel, you have the option to immediately configure Anti-Spam measurements from the top of that panel.

    Also you will see a wrench-icon near author names and URLs, which will put those names/URLS in the spamblock wordfilter automatically.

  2. Spam Bee - Blocking spam with the "Spam Bee" plugin
    What is Spamblock Bee?

    Spartacus holds an event plugin called “Spamblock Bee” that is used to fight blog spam in first defense line!

    This plugin implements simple comment antispam mechanisms, that are easy to configure but very effective. In it’s configuration you can enable a “Honeypot” and/or use hidden captchas, with an activity to force these entries being “moderated” or “rejected” (recommended).

    The Spam Bee has the less performance impact of all spamblock plugins.

  3. Spam Bayes - Blocking spam with the "Spam Bayes" plugin
    What is Spamblock Bayes?

    Another event plugin called “Spamblock Bayes” is used to fight blog spam in last defense line, since ot has the most performance impact of all spamblock plugins!

    This plugin installs a word rating mechanism, called the bayes gaussian filter, via a learning algorithm. Since it analyzes every comment word by word these word items are valuables; Nothing for “Spam”, better for “Ham”!

top
  1. How to modify and manage themes
  2. Themes, also known as “Styles” or “Templates”, are just one of the ways that you can personalise your new Serendipity blog. Themes are available to install directly from your administration screen, or you could download a zipfile of the theme from the Serendipity repository, or even from the designer’s own blog.

    Many users of Serendipity eventually want to modify a theme to suit their needs. All Serendipity themes are written using standard HTML and CSS, but with the addition of the easy to learn and very powerful Smarty templating language.

  3. Installing a new theme
  4. By default Serendipity ships with several attractive themes for you to try. Simply login to your administration suite and click the “Themes” link in the left menubar. This produces a list of all available and recommended themes with screenshots to make it easy for you. Below the preview image are normally two buttons. The smaller info-button opens additional theme information and the second is used to change/install the new frontend theme you select. If the theme provides an admin theme you get a third button to set this theme as the default backend theme. It now moves to the upper theme-list “Current Theme” section and there you may be presented with a theme config button, which opens the themes configuration, if have.

    If your Serendipity blog isn’t able to use Spartacus, perhaps because your webhost won’t allow it, you can still install new themes for your blog. Either visit the web-based version of the Spartacus themes repository or download a zipfile of the theme directly from the template designer. You’ll need to unzip the theme and upload it (using ftp) to the templates folder of your Serendipity installation. Once you have uploaded your new theme, select the theme from ‘Themes’ page within the administration suite. Don’t forget to deeply check content from unknown sites first!

  5. User Modifications
  6. You can add any HTML or Javascript to your Serendipity blog! And there’s more than one way to do it.

  7. The easiest way is to install the “HTML Nugget” plugin.
  8. This plugin provides a block in the sidebar where you can insert your custom code.

  9. If you want your code in the head of the document, you can use the “Head Nugget” plugin.
  10. This does exactly the same thing, but inserts your code in the head of every Serendipity page. You can verify that it works with your browser’s “View Source” capability.

  11. If you want to make the changes directly, you should modify your template.
  12. To put Javascript in the head of the page, for instance, you’d want to modify the index.tpl in templates/{your currently selected template’s name}. If it doesn’t exist, please copy it from templates/default/index.tpl.

    Just remember, all *.tpl files are parsed by Smarty, and both Smarty and Javascript assign special meaning to the curly braces “{}”, so there’s going to be a conflict.

    Smarty is going to win, since it goes first – on the server, whereas Javascript has to wait until the client’s browser is ready to execute it.

    To slip the braces past Smarty and on to Javascript, you need to convince Smarty to either ignore the braces, or generate them.

    Ignoring the braces is the simpler solution. Smarty passes on anything between {literal} tags, thusly:

    {literal}
    some_javascript
    {
      with(braces);
    }
    {/literal}

    So when you modify index.tpl, you could just enclose all your Javascript in {literal} tags. Smarty 3.1 adds an even simpler solution, since { with a following whitespace are ignored.

    The other option, generating the braces, isn’t difficult, just annoying. Smarty will turn any instance of {ldelim} into a left-curly-brace, and any instance of {rdelim} into a right-curly-brace. Thusly:

    some_javascript
    {ldelim}
      with(braces);
    {rdelim}

    So you could just replace all occurrences of “{“ with {ldelim} and all occurrences of “}” with {rdelim} in your Javascript only.

    When you visit your page, if your Javascript doesn’t work as expected, first check the page source. If the script looks like you wanted, there’s likely a problem with the script. If it’s missing all its braces, you need one of the solutions above.

top

I want to keep one entry at the top

The Extended Properties for Entries plugin (serendipity_event_entryproperties) includes exactly this capability! Just install it from your admin screen like any other event plugin, if not already installed by default.

After it’s installed, an extended options section appears at the bottom of each entry while you edit it. Just click the “Make this entry sticky” box to make it appear at the top of any list it appears in.

The Staticpage (serendipity_event staticpage) plugin also supports doing this for out-of-blog context pages, like a startpage.

top

How do I add PHP code to my templates?

Hm…, lets say: “A thousand roads lead [...] to Rome”!

First: Internals have changed between Smarty 3.0 and 3.1. Plugins must assign variables at the $template object, not the $smarty object, though it doesn’t matter using ($params, $smarty) as long the second is just an unused dummy.

<?php
//function.run.php

function smarty_function_run($params, $template)
{
    // pass template object
    call_user_func($params['method'], $template);
}

function addVariable($template)
{
    $template->assign("variable", "from run");
}
?>

Now lets see how to to follow some of these roads…:

  1. Register a custom Smarty function
  2. The coolest solution for you is to register a custom smarty function. For that, create (or edit) a file “config.inc.php” inside your template directory. Then register your markup like this:

    <?php
    $serendipity['smarty']->registerPlugin('function', 'my_custom_function', 'styx_my_custom_function');
    
    function styx_my_custom_function($params, $template) {
      return 'I customized this: ' . $params['stuff'];
    }
    ?>

    Then you can just edit your template (index.tpl, for example) and place this piece of code somewhere:

    {my_custom_function stuff="Cool!"}

    With the same way, you can also include foreign PHP applications:

    <?php
    $serendipity['smarty']->registerPlugin('function', 'my_custom_function', 'styx_my_custom_function');
    
    function styx_my_custom_function($params, $template) {
      include 'my_existing_tool.php';
      return my_existing_foreign_function($params);
    }
    ?>
  3. Create your own Serendipity plugin
  4. The second and often the best way is to create your own Serendipity plugins that deal with content. You can then access them with {serendipity_hookPlugin …} Smarty calls.

    Please read all about creating plugins in detail here.

  5. Extend the Smarty plugin system
  6. The third alternate is to create additional Smarty plugins as filters, modifiers, or functions. You can then access them with {myCustomSmartyExtendPluginFunction(…)} Smarty calls.

    This approach is using the Smarty internal Add-on system, which, instead of writing in your templates, i.e.:

    {str_replace($smarty.const.DIR_EXAMPLE_NAME, '', $smarty.current_dir) }

    lets you create a custom Smarty function and place it as a file smarty_function_mydir.php inside the bundled-libs/Smarty/libs/plugins/ directory.

    <?php
    function smarty_function_mydir($params, Smarty_Internal_Template $template) {
       return str_replace(DIR_EXAMPLE_NAME, '', dirname($template->source->filepath));
    }
    ?>
top

I don’t want the login screen to expose the Serendipity and PHP version

Per default, Serendipity’s login screen exposes the Serendipity and PHP version you’re using. If you would like to disable this for security reasons, you can set

$serendipity['expose_s9y'] = false;

in your serendipity_config_local.inc.php. Since this file is not part of the Serendipity core distribution, this is safe in case of an update to Serendipity.

The Stxy backend theme does not expose the Serendipity and PHP version either by default, for non-logged in users.

top

Blog editors/interfaces

Support for XML-RPC requests

Serendipity supports XML-RPC through the serendipity_event_xmlrpc XML-RPC plugin.

Start the application and make the following settings in the “account wizard”:

  • Blogging Service = Custom Blog
  • Blog System = Movable Type
  • Server API URL = http://{yourblog}/serendipity_xmlrpc.php
  • User Name = {your Serendipity user name}
  • Password = {your Serendipity password}
  • click on “next”
  • follow the further description
top

POPfetcher: Posting new entries by email

Serendipity’s POPfetcher plugin allows you to post new entries just by emailing them to your blog!

First, get yourself an email account only for adding blog entries. Either you can create a mail adress on your hosting server, or use a free POP3 service like hotmail.com or Gmail. Let’s pretend you picked up john@example.org.

Next, install the POPfetcher plugin. Enter the username and password to the blog Email account in the POPfetcher configuration. You’ll also need to tell it what host the POP3 mail server is running on. In our example, the user is blog-this, and the host is gmail.com.

Now you can write a mail to the account. In our example, just send it to john@example.org. The content of the mail will be used as the blog entry.

When you want Serendipity to check the mail, log in to your Admin screen and click the “Fetch Mails” link. POPfetcher will connect to the mail account, fetch all its mails, and insert them as Serendipity entries. Alternatively, just set your browser’s “Go” or address bar to the special URL: http://{yourblog}/index.php?/plugin/popfetcher_poll (You could even bookmark it and visit the bookmark whenever you feel like checking blog mails.)

Of course, you probably want Serendipity to check the mail account automatically. Unfortunately, blogs like Serendipity don’t run all the time; they can only perform tasks when they’re called.

You could hire an army of monkeys to visit that special URL regularly. Or you could use the “cron” utility. Cron acts like an army of monkeys that perform tasks as often as you tell them to. Any cron facility will do; some webservers offer them, and every Linux installation has cron.

Just configure cron (or the crontab, if that’s how your cron utility works) to visit the popfetcher_poll URL every hour with a lightweight browser, such as lynx or wget.

top

Windows Live Writer setup

Serendipity supports Windows Live Writer through the serendipity_event_xmlrpc XML-RPC plugin. There is now a Serendipity preset in Windows Live Writer! Unfortunately, it does not configure Live Writer properly to interact with Serendipity.

Thanks to Xeno Phage from the Serendipity forums for the following information:

  • Install Windows Live Writer and set your blog up as “Custom (Moveable Type API)”. Make sure you have the xmlrpc plugin installed in Serendipity.
  • When it asks for the URL to post, it will be something like this: http://{full path to Serendipity}/serendipity_xmlrpc.php
  • Give it your login info and you’re good to go. Categories, keywords (tags), and trackbacks all seem to work fine.
top
What next?