The Story Story

In PHP-Nuke, a story is a general-purpose, piece of content. Maybe the story is an announcement, a press release or news item, or a piece of commentary or opinion, or maybe a tutorial article. The possibilities are almost endless!

With PHP-Nuke driving your site, the stories that appear on your site are not restricted to ones written by you. Users of the site—either registered or unregistered visitors, or other administrators—can write and submit stories to your site. The process of a story appearing on the site is known as publishing the story.

Of course this does not mean that your site is a free-for-all—stories submitted by users and others do not necessarily get published automatically—they are submitted for moderation by an administrator, and once approved, appear on your site. In this way, the content on your site grows itself through your community, but always (if you want) under your control. PHP-Nuke keeps track of such things as the author of the story, the date when the story first appeared on the site, and the number of times the story has been read, and also allows users to vote on the quality of the story. An impressive feature of PHP-Nuke stories is that users can comment on a posted story to build an open, topical discussion within your site.

You will see community-contributed stories when you visit any typical PHP-Nuke site; for example, on phpnuke.org itself, PHP-Nuke users and developers submit stories describing their latest PHP-Nuke add-on, or drawing attention to the latest theme that they’ve designed.

The ‘story’ engine in PHP-Nuke is provided by the News module. The total story functionality is actually spread across a number of modules, including Submit News, Stories Archive, Search, Topics, Your Account, and Surveys. We will explore all of these in this article.

The Story Publication Process

The path taken by a story from writing to publication depends upon who submits the story. The super user or an administrator with permissions for the News module can post a story through the administration area of the site. In this case, the publication process is simple, and the story appears on the site immediately, or can be scheduled for publication on a particular date.

Since the super user and any other administrators with the appropriate privileges are trusted (they have full power over stories, so they had better be trustworthy), there is no need to moderate or approve the text in the story, and the story is ready to go.

Registered and unregistered visitors can post stories through the Submit News module. When a story is submitted through this route, the publication process is lengthier.

1. The visitor enters the story through a form in the Submit News module.
2. The story administrator is notified that a new story has been submitted.
3. The story administrator checks over the story, editing, rejecting (deleting), or approving it. The administrator is also able to add notes to the story.
4. If the story is rejected, that is the end of the process, and the story is not published.
5. If the story is approved, it is either published to the site immediately, or can be scheduled for publication on a particular date.

Once the story is published to the site, the administrator can edit it further if needed. For a visitor, once they submit their story to the site they have no more control over the story.

Finding and Interacting with Stories

Stories on the site can be accessed in a number of ways, from a number of different places on the site. A limited number of stories can appear on the homepage, with older stories gradually moving down the list as newer stories are posted.

Stories can be retrieved by date from the Stories Archive module. The text in the story is also searchable from the Search module, so that specific stories can be located easily. Stories are organized into topics, and by browsing the list of topics from the Topics module stories can be tracked down.

Stories are not the end of content, they are actually the beginning. Comments can be posted about stories, and comments can be posted to these comments creating a discussion about the story. The quality of submitted comments can be assessed by users of the site and rated accordingly.

The quality or value of the story itself can be voted on by users, links to related stories can be created, and you can view a special printer-friendly version of the story for printing, or even send the story to a friend.

So many features… did I mention that you can also attach a poll to the story so that readers can participate in a survey related to the content of the story? So many features…

Organizing Stories

When you have even a reasonable number of stories on your PHP-Nuke site (and you will have—that’s why you’re reading this article series!), you will be in need of some organization for this content.

PHP-Nuke provides two ways of organizing story content:

1. Topics: what it’s about
2. Categories: what type of story it is

Topics

Topics define what a story is about. By organizing your stories into topics, stories about similar subjects will be grouped together for easy browsing and reading, and also to make it easier for people to contribute their stories to the right place.

When you’re reading through a number of dinosaur-related stories, the sudden appearance of a story about cars would be rather off-putting (unless it was actually about fossil fuels or dinosaurs eating/driving cars).

PHP-Nuke does indeed offer organization of stories into topics, and before we can think of adding stories, we need to set up some topics for our stories.

A topic has an associated image that is displayed on the site whenever you view a story that belongs to that topic, or whenever you are browsing the list of topics. The image overleaf shows a ‘teaser’ of a story displayed on our site; the topic image is shown to the right-hand side of the story:

The Read More… link will take the visitor to the remainder of the story.

Note that this arrangement of the story text and the topic image appearing to the right of the story is just the default layout due to the basic theme. When we come to look at creating our own themes, we will see how the topic image can be made to appear elsewhere relative to the story text.

By default, there is a single topic called PHP-Nuke. This has its own image, which should only be used for the PHP-Nuke topic.

Categories

As topics define what a story is about, categories define the ‘type’ of story. A category could be something like a weblog entry, a security announcement, or a press release.

There is one category defined by default, Article. This category has the following properties:

• You cannot change this category’s name or delete it.
• Any story of type Article automatically appears on the homepage.
• Users can only submit stories of type Article.

Compared to topics, categories do not have particularly extensive support in PHP-Nuke.

Planning the Dinosaur Portal Topics and Categories

Before we move on to looking at managing topics and categories, we’ll quickly discuss the kind of topics and categories that we would like for organizing our stories on the Dinosaur Portal. These are not set in stone, and after we create them, we can edit or delete them, or even add new ones.

First of all, there will probably be stories about the Dinosaur Portal itself that will contain general information about the site, such as new features that have been added to it, or warnings about planned site downtime (or apologies about unplanned site downtime!).

We will also have stories about dinosaurs, fossils, and dinosaur hunting; these can be the other topics on the site. What types of story will we have? In addition to the standard article, we can have new theories, technologies, or discoveries, maybe even tutorials (for example, how to identify fossils, or how to avoid being eaten when dinosaur hunting). There will also be stories about Project Chimera, but we can’t reveal what that is just yet.

Thus a story about a controversial new dinosaur extinction theory could be given the ‘dinosaur’ topic, and the ‘new theory’ category.

This isn’t an exhaustive list, but it is enough to give an idea of the topic-category split.

Topic Management

Before we do anything else, we’ll create our topics. For each topic, we’ll add the images first. After we create our topics, we’ll look at how to modify them, and the consequences of deleting topics.

Before we get started creating our topics, we will add the topic images. To do this, you will need to copy all the files from the topics folder in the Ch06 folder of the code download to the images/topics/ folder in the root of your PHP-Nuke installation.

You should have these files: thedinosaurportal.gif, dinosaurs.gif, fossils.gif, and dinosaurhunting.gif, in addition to files called index.html, phpnuke.gif, and AllTopics.gif, which were already present in the folder.

The images/topics folder is the place where PHP-Nuke will look for the topic icons. When adding image files to the images/topics folder, ensure that only alphanumeric characters or the underscore are used in your filename, or else PHP-Nuke will fail to pick up the filename when displaying the list of topic images.

Note also that the total length of the filename and its extension must not exceed twenty characters, or PHP-Nuke will truncate the name when it stores a record of the filename. In this case, your topic image will not be displayed, because PHP-Nuke has not stored the correct name of the file. Also, if your image has an extension of more than three characters (such as jpeg) then it will be missed by PHP-Nuke.

The AllTopics.gif file in the images/topics folder does not correspond to a single topic, but is the image used when displaying the lists of topics. This file can be replaced by an image of your own.

Time For Action—Creating New Topics

• Log in to your site as the administrator.
• From the Modules Administration menu, click on the Topics icon:

  

• You will come to the Topics Manager area. Scroll down to the Add a New Topic panel
• The first topic we create will be Dinosaur Hunting. Enter the text dinosaurhunting in the Topic Name field, enter Dinosaur Hunting into the Topic Text field, and select the file dinosaurhunting.gif from the Topic Image drop-down box:

  

• Click on the Add Topic button.
• When the screen refreshes, the newly created topic will be displayed in the Current Active Topics panel:

  

  This process can be repeated for our other topics:

Topic Text	Topic Name	Topic Image
Fossils	fossils	fossils.gif
Dinosaurs	dinosaurs	dinosaurs.gif

What Just Happened?

The Topics Manager, reached through the Topics icon in the administration menu, is the area from where we can add, edit, or delete topics.

The Topics Manager has two panels, one showing the Current Active Topics, and the other being the Add a New Topic panel.

A topic requires three pieces of data:

• A topic name, which is a short piece of text with no spaces. This is mostly used internally by PHP-Nuke. The topic name is usually the same as the topic text, but in lower case and with no spaces.
• The topic text, which is the title of the topic.
• The topic image, the name of which is selected from the list of files in the images/topics folder. You can use the same image for more than one topic if you choose.

Once you have saved a topic, clicking on its image in the Current Active Topics panel takes you to the Edit Topic area, from where you can edit or delete your topic.

You may have noted that we haven’t created the Dinosaur Portal topic. We’ll do that now by editing the existing default topic, since we would like this to be the default topic for the portal anyway.

Time For Action—Editing Topics

We will edit the default topic to get the Dinosaur Portal topic:

1. In the Topic Manager area, click on the PHP-Nuke topic icon in the list of Current Active Topics.
2. When the page loads, enter the details as shown below:

   

3. Click on the Save Changes button to complete your editing.
4. When the page reloads, you will need to click on the Topics icon again to return to the Topic Manager area, since you will be returned to the page for editing the topic.

What Just Happened?

We just edited the properties of an already existing topic. To get at a topic’s properties, you click on its icon in the list of Current Active Topics in the Topic Manager area. The possible topic icons are again picked from the images/topics folder and displayed in a drop-down list for you to choose. Once you are done making changes to the topic, clicking on the Save Changes button updates the topic.

Note that there is no cancel button, and if you decide to make no changes here, you can click on the Topics icon in the Modules Administration menu to return to the Topic Manager area, or use the back button on your browser.

Deleting a Topic

It is possible to delete topics by clicking on the Delete link next to the Save Changes button. However, deleting a topic will delete all the stories that belong to that topic. Fortunately, there is a confirmation screen before the topic is deleted:

Since the Delete link is positioned so close to Save Changes, it’s probably good that there is this screen. There is no turning back after you click on Yes on this screen. Your topic is gone, and so are all the stories, and any comments attached to those stories. Note that the image associated with the topic is not deleted, and it still remains on the server, and can be used for another topic if wished.