If you’re a developer building a content-rich Web site, you’ve
probably looked at several solutions that include (a) a database for your
content, (b) a templating system that separates GUI from content, (c) a
user-friendly interface to maintain the data in the database, and (d) control
over the final appearance of the rendered pages.

One very interesting solution that offers all of the above
is Yaapi, an acronym for “Your Article Application Programming Interface.”
It’s a PHP class that offers built-in methods to access content stored in a
database. An administration module ships with the class to assist in managing
the data, while the API itself is sufficiently sophisticated to perform most
common tasks required of a CMS.

Installation

To install and use Yaapi, you’ll need a PHP-compliant Web
server such as Apache, PHP of course,
and a MySQL database server. You can download a copy
of Yaapi
and uncompress it to a location under your server root.

You also need to create a MySQL database to hold the Yaapi
data structures. Use the yaapi.sql file from the source archive to create this
database, and then open up the Yaapi configuration in the class constructor
(the article.class.php file), and update it with the name and access parameters
for the database.

Adding content

To add content to the database, you must use the Yaapi
administration module at http://your-server/yaapi-root/admin/ (replace
“your-server” with the name of the server where you’ve installed
Yaapi, and replace “yaapi-root” with the path to the directory where
you’ve uncompressed Yaapi). You use this admin module to create (and delete)
content categories, and then place articles in those categories. Here’s a brief
list of the fields you’ll encounter during this process:

  • Category:
    The category for the article
  • Section
    ID: If you have a two-level hierarchy for your articles, use this
    parameter to define the second level.
  • Title:
    The title of the article
  • Author:
    The article author
  • E-mail:
    The e-mail address of the article author
  • Approved:
    A flag indicating if an article has been “approved” for display
  • Image:
    An optional image URL to be associated with the article
  • Content:
    The content of the article

A small note in the context of the last item above: Yaapi
comes with the ability to break your large article into smaller pages by
inserting delimiters in the article text, as exemplified below:

Introduction of article here
#intro#
Page 1 content here
#page#
Page 2 content here
#page#
Page 3 content here
#page#
and so on…

Remember to approve the article after entering it, as only
approved articles can be retrieved with the API.

Retrieving categories and lists

Now that you have your content in the database, it’s time to
use the API to retrieve it and populate a standard HTML template (this template
can be altered to match your site design).
Listing A contains
the base code for the template.

You begin by using Yaapi to retrieve a list of all the
articles in a particular category, and displaying their titles, authors, and
introductions in the center block.
Listing B has the PHP code and Yaapi API calls to accomplish this. That code
deserves a bit of explanation.

A necessary first step when using Yaapi is to instantiate an
object of the class; this object then exposes API methods and properties to
access the content in the database. In order to obtain a list of titles, you
use the category ID—this may either be passed on the URL or a default value.
The get_titles() method uses this category ID to return an associative array
containing article IDs and titles of the (approved) articles present in that category.

Next, the get_article() method drills down further, iterating
over the list of article IDs returned in the previous step and returning an
object representing each article. The title, author details, and introduction
are exposed as properties of this object and can be retrieved using standard object->property
notation. Notice that the article title is further object->linked to a
separate PHP script, article.php, by the article ID…more on this shortly.


Tip

You can pass the
get_article() method an optional s
econd
parameter—the page number—to return a specific page of the article.


To finish work on this page, all that’s left is to obtain
and print a list of available categories (you’ll need this for the menu on the left,
remember). You accomplish this with the get_categories() method, which returns
an associative array containing the names of the categories and their
respective IDs. Listing C contains
the necessary update to the script from Listing B.

You can see what the end result might look like in Figure A:

Figure A

Output using the get_categories() method

Retrieving article content

The display of the complete article is handled by the
article.php script, which is invoked with the article ID. Listing D contains the code for this script, which includes support
for page delimiters by allowing you to jump to any page of the article via page
number links at the bottom of the page.

The content for each page is retrieved via the get_article()
method discussed previously, passing it the article ID and page number. The
only significant difference is that the “content” property of the
returned object will now store a particular page of the article and not the
introduction.

The num_pages() property is used to obtain the total number
of pages in the article. This can be combined with a simple for() loop to
generate a navigation bar of page numbers and hyperlink each number back to
the same script with the same article ID but different page ID.

Figure B shows what the output might look like:

Figure B

Output using the get_article() method