Version 1.0.1

Weblog / News Publishing Tool

Requirements - Installation - Template(s) - Query String Usage - XML-RPC (Blogging APIs) - Post Via Email - Notes

# Requirements:

- PHP4 (version 4.0.6 or higher)
- MySQL (version 3.23.23 or higher)
- ... and a link to http://wordpress.org on your site.

The link will help promote WordPress and is its only mean of promotion.

WordPress is the official continuation of b2, which comes from Michel V. The work has been continued by the WordPress developers. If you would like to support WordPress, please consider donating.

This document is currently beta stage, we'll be updating it extensively as WordPress matures. There is also online documentation under development, as well as a wiki.

# Installation:

## New users: 5-minute install.

1. Unzip the package in an empty directory.
2. Upload everything. This release is designed to sit in your root folder; i.e, the folder where your WordPress-powered page will reside.
3. (Optional) If you're going to use it, the weblogs.com cache file needs to be writable by the web server. CHMOD 666 the `weblogs.com.changes.cache` file.

4. Point your browser to wp-admin/install-config.php. This will create a configuration file for your installation. You'll need to know your database name, username, password, and host name.

   Alternately, you may open wp-config-sample.php in a text editor and insert your database name, username, password, and host name as indicated in the comments. (Comments are lines that start with `/*` or `//`.) Save this file as wp-config.php, and upload it.

5. Launch /wp-admin/install.php in your browser. This should setup the MySQL database for your blog. Note the password given to you. If there is an error, double check your wp-config.php file, and try again. If it fails again, please go to the support forums and make a post with all the information about the failure (error messages, etc), and your setup (the PHP and MySQL versions on your server, and the browser you were using).
6. The install script should then send you to the login page. Sign in with the username "admin" and the password generated during the installation. Then click on the item 'My Profile', and change the password. The login page may also be accessed by going to wp-login.php.

## Some notes:

- Whenever you want to post something, just open a browser and go to wp-login.php to log in and post.
- You can also use a bookmarklet and/or a sidebar (IE5+/NS6+) to post.
- You can also post through the Blogger, MetaWeblog, and MovableType APIs, click here for more info.
- By default, your site's blog is located at index.php, which is an elaborate .CSS-based template. There is a non-.CSS template you can also use, called wp.php. You can rename either of these files as any other name you fancy (provided it bears the php extension or is interpreted as a php file by your server).

## Preface for all upgrades:

- Back up your database before you do anything.
- If you haven't already, we strongly suggest that you BACK UP your database.
- Have you BACKED UP your database? Yeah? GREAT!
- If you don't know how to do this, this script may help.

## Upgrading from any previous WordPress to v1.0.1:

- Backup your database. Yes, you. Right now.
- Point your browser to /wp-admin/upgrade.php.
- You wanted more, perhaps? That's it!

## Note on upgrading to v1.0.1:

- It is strongly recommended that you use the new index.php for your templates, rather than simply upgrading your old one. Sure, it'll take a little time, but you'll be much happier with the results when you do!

## Upgrading from b2 v0.6.1/v0.6.2.2 to WordPress v1.0.1:

- Back up your database before you do anything. Yes, you. Right now.
- You must configure `wp-config.php` as indicated in the "5-minute install" section.
- All you really have to do is replace all the files with newer versions and run wp-admin/upgrade.php and you should be ready to go.
- There is also an import script at wp-admin/import-b2.php.
- If you're using an older version of b2, it's probably a good idea to upgrade to at least .6.1 before making the leap to WordPress.
- The templates are better and structured slightly differently, so it might be worth it to start from scratch and work back to your design.
- WordPress issues should be discussed in our support forums.

## Upgrading to WordPress v1.0.1 from Movable Type, Textpattern, GreyMatter, & Blogger

- Did we mention BACKING UP your database first?
- Each of these tools has an import script available. They are all located in the wp-admin directory, and must first be configured with your database information before they are executed.
- Detailed importing instructions are given during the execution of the import script.
- Textpattern: run wp-admin/import-textpattern.php.
- GreyMatter: run wp-admin/import-greymatter.php.
- Blogger: run wp-admin/import-blogger.php.
- Movable Type: run wp-admin/import-mt.php.

# Templates:

For information about WordPress templates, please see our online documentation on them.

## First notes:

# Query String Usage:

WordPress relies a lot on the query string. These variables passed with the URL (note: to pass variables in the querystring, preceed the first variable name with a '?' question mark and every other variables with a '&' sign.)

Most of the time you won't have to do anything about it, but if you want to know how it works, it's here:

How to use the query string:

index.php?m=200107 will display the month of July 2001.

index.php?m=20010701 will display all posts from July 1st, 2001.

index.php?w=20 will display the posts from the 20th week of the year, where January 1st is in the first week (according to PHP).

index.php?p=50 will display the post labeled #50 in the database.

index.php?s=blue+house will display the posts that match the search request "blue house".
here is the code for a simple search box:

`<form name="searchform" action="<?php echo $PHP_SELF ?>" method="get">
<input type="text" name="s" />
<input type="submit" name="submit" value="search" />
</form>`

index.php?cat=1 will display all posts that belong to category #1 (1 is the default). you can add/rename/delete categories from WordPress's interface.

index.php?author=1 will display all posts from the author #1

index.php?p=50&c=1 will display the comments and a form to add a comment below the post.
you should use this variable only with p=, example: index.php?p=50&c=1.

index.php?p=50&page=1 will display the first page of post #50. this, again, should be used only with p=, for individual entries.

You can also mix these variables, example: index.php?m=200107&s=hotdog will display the posts that match the search request "hotdog", but only in July 2001.

# XML-RPC Interface:

WordPress has an XMLRPC interface. Currently supported APIs are the Blogger API, metaWeblog API, and the MovableType API. There are talks about a new API that would cover a lot of weblog/CMS systems in the future: when it's ready, WordPress will support it.

The Blogger API has been completely emulated on WordPress, with some little differences:

- using blogger.getRecentPosts with the number 'zero' returns all posts in the blog
- blogger.getTemplate fetches your file $blogfilename (as specified in the config), while blogger.setTemplate overwrites it with the edited data
- blogger.getUsersBlogs is a dummy function that returns '1' and $blogname, since WordPress supports only one blog as of now

If you use blogger.newPost, your post is submitted without title and in category #1.

However, you can type <title>my title</title> and/or <category>2<category> in the body of your post to make its title be 'my title' and its category be #2 (refer to your categories section to find out the ID numbers of the categories). b2 would then delete that extra info from the body of your post once it is posted.

The metaWeblog and MovableType APIs are currently supported with the following exceptions:

- metaWeblog.newMediaObject, mt.getRecentPostTitles, and mt.getTrackbackPings are not yet implemented
- mt.supportedTextFilters is a dummy stub function that returns an empty string
- keywords are not supported in the MovableType API

Extended entries in the MovableType API are automatically converted to/from the WordPress <!--more--> tag.

You can now post to your WordPress blog with tools like BlogBuddy, Bloggar, WapBlogger (post from your Wap cellphone!), Radio Userland (which means you can use Radio's email-to-blog feature), Zempt, NewzCrawler, and other tools that support the Blogging APIs! :)

Your XMLRPC server/path are as described here: if you login to WordPress on http://example.com/me/wp-login.php, then you have:

- server: http://example.com/ (some tools will just want the 'example.com' hostname part)
- path: /me/xmlrpc.php
- complete URL (just in case): http://example.com/me/xmlrpc.php

There's also a b2-specific method: b2.getCategories. Request it with 3 strings: blog_ID (use '1'), username, password. The response is an array of structs with strings categoryID and categoryName.

# Post via Email:

You can post news from an email client!
But first you'll have to edit the options on the options screen, filling the appropriate values for your POP3 email account (this interface doesn't support IMAP yet, only POP3, sorry).

Once you have edited the options, you can make your webserver execute wp-mail.php every set amount of time (depending on your host's performance, this script can be resource intensive, so don't make it run every minute or you'll be kicked).

You can do it with Cron-jobs, or if your host doesn't support it you can look into the various website-monitoring services, and make them check your wp-mail.php URL.

## Preliminary advice:

It is strongly advised to send your email as text-only (Outlook and Outlook Express default to 'html', which may cause problems), but HTML email could work (the script would strip all your html tags though...).

It is also advised not to use your public email address, but create a new one especially for this script. If you use your public email address and the script goes crazy posting every email on your blog and deleting all your emails, I can't take responsibility for this.

Make sure you delete any email sent to your blog in your 'Sent' folder too, just in case (you don't want someone to find your login and password in the 'Sent' folder).

The script will delete the emails that were used to post stuff on your weblog if it successfully posted your stuff. If it didn't manage to post, the email is not deleted.

## How to post:

Now to post something, here's how your email should look like:

To: address@example.com (you set it in the config file)
Subject: blog:the post's title (you can change 'blog:' in the config file)
Body:
login:password (example: Jack:Starwars)
The content of the post, blah blah blah.
More blah blah. ___

Subject must start with 'blog:', or any string you set in the config file (so that the script doesn't check EVERY email in your mailbox).

Body's first line must always be login:password, else the script will just skip the email.

If you don't use '___' (or any body terminator that you set in the config file), the script will post the whole body, which is not what you want if you send email with Yahoo or Hotmail (you don't want their ads on your blog, do you ?).

## Special cases for mobile phone email:

Some mobile phone service providers may allow you to send email with your mobile phone or PDA, but on such devices you can't always include line breaks. In such case, you have to set use_phoneemail = true in the options, and then here's how you write the email:

To: address@example.com
Subject: blog:the post's title :::
Body:
login:password ::: The content of the post, blah blah blah.___

You will have to append ':::' (or whatever string you set in the config file) after the subject, and after the login:password.

Some mobile phone service providers may not allow you to set a subject, and they'll make the subject be the first characters of the body, in which case you would send an email like this:

To: address@example.com
Body:
blog:the post's title ::: login:password ::: The content of the post, blah blah blah.___

# Notes:

On multi-user:

New users can register with wp-register.php. Then you (as an admin) click the "+" next to their name on the Team page in admin to upgrade their level to 1 or more, so they can post. If you don't want an user to post anymore, just click "-" until their level is 0.

Note: you can now disable users registration altogether from the config file.

User Levels:

- 0 - new user: can't post.
- 1 - user: can post & edit/delete their own posts.
- 3 & higher - admin: can post, edit/delete other people's posts, and change the options.
- Any user whose level is higher than 1, can edit/delete the posts and change the level of users whose level is inferior. Example: a level 2 user is not an admin, but can edit the posts of level 1 users, and up the level of a new user from 0 to 1.

Usually, you'll want to have a team of only level 1 users except you. ;)

Note: you can modify an option on the option screens, to enable new users to post once they've registered.

If you don't want users to register on your blog at all, just delete wp-register.php once you've registered your user account.

# Final notes:

- If you've got suggestions, ideas, or comments, or if you found a bug, why not joining us in the Support Forums?
- If you can code in PHP, you'll see the structure of WordPress is flexible enough to allow for more functions and sections to be added.

# Copyright notes:

- Wherever third party code has been used, credit has been given in the code’s comments.
- WordPress is released under the GPL (see license.txt).