Story Management with PHP-Nuke

Exclusive offer: get 50% off this eBook here
Building Websites with PHP-Nuke

Building Websites with PHP-Nuke — Save 50%

A practical guide to creating and maintaining your own community website with PHP-Nuke

$20.99    $10.50
by Douglas Paterson | March 2010 | MySQL Content Management Open Source PHP

In the previous article of the series by Douglas Paterson, author of Building Websites with PHP-Nuke, shows how to manage visitors to your site, how to create users, explore the Your Account module, which is the user's private 'space', and set up other administrators to perform limited administrative tasks on the site.

In this article which is the sixth article of the article series, we will cover the following, paying attention to both the administrator and visitor points of view when required:

  • An overview of stories and the story publication process
  • Organizing stories into topics and categories
  • Adding and editing stories
  • Understanding comment moderation
  • Managing stories
  • The different modules that let you access stories
  • Creating polls and surveys
  • Syndicating your news with the backend.php file

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:

Building Websites with PHP-Nuke

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:

    Building Websites with PHP-Nuke

  • 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:

    Building Websites with PHP-Nuke

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

    Building Websites with PHP-Nuke

    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:

    Building Websites with PHP-Nuke

  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:

Building Websites with PHP-Nuke

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.

Building Websites with PHP-Nuke A practical guide to creating and maintaining your own community website with PHP-Nuke
Published: November 2005
eBook Price: $20.99
Book Price: $29.99
See more
Select your format and quantity:

Adding Stories

With the topic list set up as desired, we can now begin to add stories to our site. Our first story will be about the launch of our new site.

Time For Action—Adding a New Story

  1. From the administration menu, click the News icon (in versions of PHP-Nuke before 7.5, this icon is titled Add Story):

    Building Websites with PHP-Nuke

  2. You are now in the Article/Stories Administration area. At the top of the Add New Article panel, enter the following into the Title field:
    the Dinosaur Portal is Alive!
  3. Select the Dinosaur Portal from the Topics drop-down box.
  4. Don't select any of the Associated Topics.
  5. Leave Article selected in the Categories drop-down box.
  6. Skip over the Publish in Home? and Activate Comments for this Story? fields, they are already set to our required values.
  7. Enter the following into the Story Text field.

    Since the beginning of time, man and dinosaur have wrestled for supremacy
    of the world we all inhabit. Finally, this site, the Dinosaur Portal,
    chronicles and informs of this struggle.

  8. Enter the following into the Extended Text field:
    At the Dinosaur Portal, we believe that just because you haven't seen a 
    dinosaur, doesn't mean that they've all died out.

    As such, this site has been specially created to address the needs of
    those who think likewise, and provide specific content targetted for this
    enthusiastic and unusual audience.

  9. Leave the Do you want to program this story? field set to No.
  10. Click the Ok! button next to the Preview Story drop-down box.
  11. When the page reloads, a preview of the story is displayed:

    Building Websites with PHP-Nuke

  12. Scroll down to the bottom of the story details, and select Post Story from the drop-down box next to the Ok! button:

    Building Websites with PHP-Nuke

  13. Click the Ok! button, and your story is posted.

What Just Happened?

We just posted a story. First we went to the Add New Article panel in the Article/Story Administration area. Here, we went via the News icon in the Modules Administration menu. There is an alternative route; the NEW Story link in the Administration block takes you to this place as well:

Building Websites with PHP-Nuke

We began by entering the story's title into the Title field, followed by selecting its topic from the Topic drop-down box. It is possible to forget to assign a topic to the story; PHP-Nuke will not warn you about this, although when you preview the story before posting, the absence of the topic image should be a clue that something has gone wrong. You can assign a new topic to a story when editing the story after it has been created.

You are able to choose a number of related topics for this story, and links to these topics are displayed under the story, allowing people to browse these other topics for similar stories.

Next it's time to select a category from the Category drop-down box. At the moment we only have one category, the default Article category. We'll look at managing categories in a moment.

The next field we encountered was Publish in Home?. Any story in the Article category is published to the homepage (in other words, displayed on the homepage of the site) regardless of this value. Stories from any other category can be set to appear on the homepage by selecting this option, although Yes is the default value.

The next field is Activate Comments for this Story? We'll spend a lot of time talking about comments in a moment. We left the value at its default, which is Yes.

We did a lot of typing next; we entered the Story Text and then the Extended Text. The Story Text is a summary or introduction to the story, a teaser if you like, and the main part of the story goes into the Extended Text. The Story Text is to introduce the story to the reader, and should only really contain enough to get the reader interested in wanting to read the full story.

When visitors begin submitting stories to your site, and you, as the administrator, begin the process of approving these stories for publication on your site, you may find yourself having to split up the submission of the visitor into a more balanced Story Text and Extended Story division.

Back to our current situation… the next thing we did was to select No for Do you want to program this story? By doing this, the story appears on the site immediately after we have posted it. By selecting Yes, and then entering a date through the various date options, you can schedule the story to be published at the time you choose:

Building Websites with PHP-Nuke

Selecting a date for the publication of the story without selecting Yes for the Do you want to program this story? will not set a date for the story, and the story will be published immediately. Once a story is programmed, its schedule is set and there is no feature to alter the schedule.

With all the story details in place, all that remains is to preview the story (selecting Preview Story from the drop-down box next to Ok!) before posting it. If it looks OK, we can post the story by selecting Post Story from the drop-down box. If we felt bold, we could select Post Story without previewing the story first, and begin the publishing process.

Underneath the Add New Article panel is a panel for attaching a poll to the story. We will discuss polls and surveys later in the article.

Category Management

We saw the Category drop-down box in the Add New Article panel; it has three icons next to it for managing categories:

Building Websites with PHP-Nuke

If you click any of these icons to go off and do a bit of category management, you will lose any text you've entered into the story at that point, so do any category management before you get too far into your story!

These icons are the only means of managing categories. If the category that you want for the story does not exist when you create the story, you can always create the category after creating the story and then change the story's details.

Adding a new category simply requires you to define a name for it. We'll add a few new categories to the Dinosaur Portal; New Theory, Technology, and Tutorial.

Building Websites with PHP-Nuke

Note that after adding a category, there is no link to go back to the Add New Article panel, and if you use the Back button to go back there, you will have to refresh the browser for the new category to be displayed in the list of categories.

Editing a category allows you to change the name of the category. Note that another list of categories is displayed, and you have to select the category from that list; you will not be editing the category selected in the Category drop-down box of the Add New Article panel.

Deleting a category is more interesting. Clicking on the Delete link next to the Category drop-down box brings up another list of the categories, from which we choose the one we want to delete and click on a Delete button. If there are any stories in the category, we are presented with a warning screen. If there are no stories in the category, the category is simply deleted. Deleting a category will delete all the stories in that category, and so PHP-Nuke gives us a lifeline:

Building Websites with PHP-Nuke

If you click No! Move My Stories, you are able to select a category into which all the stories of your about-to-be deleted category will move. The stories are moved, and the category is deleted—the option No is rather misleading here, since the end result is still the removal of a category.

If you have changed your mind and do not wish to delete the category, click on the Back button in your browser or click on one of the other icons in the Administration Menu to continue with your administration, rather than selecting one of the two Delete Category options.

Deleting a category contrasts with deleting a topic; there we saw that deleting a topic removes all the stories within that topic and there was no opportunity to move them as a group.

The Visitor View of a Story

Let's have a look at how the story will look to the visitor. Click on the Home link in the Modules block to return to the homepage of the site. There, in the middle of the page, you will see the story you just entered.

Building Websites with PHP-Nuke

This view shows the introduction to the story, the story text, along with some further details:

  • Who posted the story to the site
  • When was the story posted
  • The number of times the story has been read
  • The number of comments (if any) made on the story
  • The remaining amount of text in the story (in bytes, which is more or less characters)
  • A link to view the remainder of the story

The creator of the story is usually different from the person who posts (approves) the story to the site. The person who publishes the story is almost always one of the site administrators. This current view of the story can give a misleading impression, and have you believe that this story is written by admin.

Click on the Read More... link, and we will see the story's Extended Text.

Building Websites with PHP-Nuke

Note the extended text of the story is displayed along with the 'story text' of the story. To the right of the story text, the visitor will see a few blocks. If the visitor is not currently logged in, they will see four blocks. Otherwise, a visitor will see three blocks to the right of the extended story text. The extra block for the visitor who isn't logged in is a Login block, inviting the visitor to login or create an account if they don't have one. Apart from that, the other three blocks are the same if you are logged in or not.

These blocks guide the reader towards related content, allow the reader to rate the story, and allow the reader to view the story in a form more suitable for printing or pass it on to a friend.

Related Links, Scoring, and Friends

The Related Links block shows a link to other stories from the same topic as the current story, other stories from the author of the current story (in this case the author is admin), and the most viewed story from the same topic:

Building Websites with PHP-Nuke

There isn't much competition for the most viewed story at this point!

Underneath the Related Links block is the Article Rating block:

Building Websites with PHP-Nuke

This block allows visitor to score or rate the story, from one star (very bad) to five stars (very good). The result of the rating so far is displayed at the top of the panel—the average rating and the total number of votes cast. The score of the article was shown, if you recall, on the summary view of the story on the homepage.

Let's exercise our rights, and select five stars, and then click on Cast my Vote! We will receive a message thanking us for voting:

Building Websites with PHP-Nuke

When the page reloads, the article tally has updated:

Building Websites with PHP-Nuke

Let's abuse our right, and continue to vote. This time, select one star (boo), and click on Cast my Vote! Fortunately, PHP-Nuke has seen through our villainy:

Building Websites with PHP-Nuke

PHP-Nuke is able to detect that you have already voted from a cookie it stores on your machine. In fact, PHP-Nuke won't let somebody else from the same IP address vote in the poll again.

The block underneath the Article Rating block is the Options block:

Building Websites with PHP-Nuke

For ordinary visitors, this block shows a link to a printer-friendly version of the page, and an opportunity to email details of the page to a friend.

When logged in as the administrator, extra icons are displayed, allowing you to modify the story being viewed. We'll look at this activity later in the article.

The printer-friendly page displays a 'clean' version of only the story and its content:

Building Websites with PHP-Nuke

The image stamped at the top of the printer-friendly page is the image specified as the Site Logo in the site preferences. If you are particularly observant, you may have noticed that on the Site Preferences page, the Site Logo had the following text next to its field:

must be in /images/ directory. Valid only for AvantGo module

That statement turns out to be not entirely true; the image displayed at the top of the printer-friendly page (which is part of the News module) is also determined by the Site Logo field.

The other link in the Options block allows the visitor to send a link to the story to someone via email. Here is the email received by my friend Count Dracula about our first story:


Hello Count Dracula:

Your Friend Testuser considered the following article interesting and wanted
to send it to you.

the Dinosaur Portal is Alive!
(Date: 2005-08-09 11:22:13)
Topic: the Dinosaur Portal

URL: http://thedinosaurportal.com/modules.php?name=News&file=article&sid=1

You can read interesting articles at theDinosaurPortal
http://thedinosaurportal.com

By clicking on the URL after URL:, my friend, Count Dracula, will be able to read the story in full. And then probably email me asking why I thought it was interesting to him.

You will note that the full domain name of your site is included in the email; this is taken from the Site URL property of the Web Site Configuration menu. If you haven't set this properly, then the link will point to the wrong site! (It will be phpnuke.org if you haven't set the Site URL property.)

The subject of the email consists of the text Interesting Article at followed by your site name, which is the Site Name property of the Web Site Configuration menu. You will want to make sure you have set that property as well. For all of this, you must also have your site's mail server working.

Everyone Has an Opinion... Comments

Comments can be posted on stories, allowing readers to express their own carefully formulated opinion of the story content. Comments can be posted directly to the story (top-level comments), or they can be posted as replies to existing comments. In this way, 'threads' of discussion can be created related to the story, or at least, related to the comment they are replying to. Comments are 'owned by the poster'. This means that no one can edit the comments, not even the super user.

Time For Action—Posting a Comment

  1. Log out of the administrator account if you are still logged in.
  2. We're going to work as the testuser user, so log in as the testuser with password testuser.
  3. Click on the Home link in the Modules block to return to the homepage of the site.
  4. The story that we entered in the Adding Articles section will be displayed in the middle of the homepage. Click on its comments link.
  5. Underneath the extended story text you will see the comments bar. Click on the Post Comment button:
  6. Building Websites with PHP-Nuke

  7. When the page reloads, the extended story text is displayed again, and underneath is the panel for entering your comment:
  8. Building Websites with PHP-Nuke

  9. Let's enter some text for the comment into the Comment field:
      I am really excited by this prospect. It is the answer to so many of 
      my needs.
  10. Click on the Preview button.
  11. When the page reloads, you can indeed see a preview of your comment, with the comment editing panel underneath:
  12. Building Websites with PHP-Nuke

  13. We are satisfied with the look of our comment, so let's click on the Ok! button at the bottom of the comment editing panel to submit our comment.
  14. When the page reloads, the story is displayed again, our newly posted comment is shown underneath, and the comment count in the comments bar has been updated:
  15. Building Websites with PHP-Nuke

What Just Happened?

We just posted a comment to a story. The posting process itself was straightforward. To get a view of the comments, we chose to click on the comments? link, although the Read More... link on the story text takes us to the same page.

Once we clicked on Post Comment, it was simply a case of entering the text into the Comment field, which forms the body of the content. A subject was already provided for us in the Subject field (Re: followed by the title of the story), although we could have edited this field if we wanted. We chose to preview the story before posting (which is always wise).

Clicking on the Ok! button on the comment edit panel posted the story to the site, and we were presented with the story along with the comment we just posted.

The comment panel is made up of two boxes (as seen in the last screenshot):

  • The top box is the comments bar, and is used by the user to work with comments. Through the comments bar, the user can customize their view of the comments, search the current discussion, or post a comment (if this is allowed).
  • The lower box is a posted comment. It shows the title of the comment, the comment's score, the name of the user who posted the comment and at what time they posted it, the text of the comment, a link to reply to the comment, and some further links about the user.

Time For Action—Replying to a Comment

It may seem rather sad replying to our own comments, but that is what we are about to do. You can pretend you are a different user if you like, or you could even create a new user account and log in as that user to complete the masquerade.

Following on directly from the last task, you should have a view of the comment you just posted (if not, click on the comments (1) link of our story to return to the comments view). Click on the Reply to This link.

You will be taken to a page with the comment you are replying to, followed by the comment edit panel for you to enter your response. Let's enter the text I second that! into the Comment field and click on the Ok! button.

When the page reloads, our new reply is shown:

Building Websites with PHP-Nuke

What Just Happened?

We just replied to a comment. Like posting comments, the replying process is straightforward. The subject of the comment is provided; this time it is the same subject as the comment you are replying to, but you are able to edit from the comment editing screen as you enter the text of your comment.

Seeing Your Comments

You can view a list of your ten most recent comments from the Your Account module. Click on the Your Account module link and scroll down the screen to see them:

Building Websites with PHP-Nuke

Clicking on one of these links will take you to the story with that comment, and will even have automatically moved you to the part of the page where the comment is displayed, so you do not have to scroll through all the comments to find it. With these links, the comment display is different from the view we saw earlier. All the comments are displayed in a long list with the full text of the comment visible. This is different from the 'thread' view we saw earlier, where only the comment subject was shown for replies. We'll see more about comment views later.

Controlling Comment Posting

However, the possibility of posting comments to stories does not mean anarchy on your site. There are a number of actions you can take as the administrator to control the posting of comments.

  • You can allow/disallow comments to be posted for an individual story.
  • You can allow only registered users to post comments.
  • You can remove comments.
  • The comments of certain users can be checked.
  • The comments can be 'moderated' by other visitors.

Allowing Comments

First of all, you have to allow comments to be posted for the story in question. This is controlled by the Activate Comments for this Story? option when the story is created or edited:

Building Websites with PHP-Nuke

By default, this option is set to Yes, so that comments can be posted for the story. If you wished to disable comment posting for a particular story, you would set this option to No.

Disallowing Comments

To turn off comment posting for every story, there is an option in the Web Site Configuration menu of the site preferences. The Miscelaneous Options panel in the Web Site Configuration menu has the following option:

Building Websites with PHP-Nuke

The default value of this option is Yes, so comments are activated for articles (the first type of story). Any story that has the Activate Comments for this Story? option set to No will override this value and not allow the posting of comments.

If the Activate Comments in Articles? option is set to No, then comments cannot be posted for any article, regardless of the value of the Activate Comments for this Story? option set for that story.

In general, disabling comment posting does not disable the display of comments. If comments have already been posted and you disable posting, then comments already posted will still be displayed. The options we have just discussed handle comment posting, not display.

Restricting Comment Posting to Registered Visitors

The next safety feature is to stop anyone other than registered visitors from posting comments on a story. This feature is controlled in the General Site Info panel (top bit) of the Web Site Configuration menu:

Building Websites with PHP-Nuke

Recall that an Anonymous user is an unregistered user. Setting this option to No means that only registered visitors can post comments. Anonymous users will still be able to read the comments; they simply will not be able to participate in the discussion unless they register on the site. By default, this option is set to No.

Thus the default comment posting settings for a particular story are:

  • Comments are enabled.
  • Only registered visitors can post comments.

Therefore, without doing any extra configuration, any story posted to our site can be commented on only by registered visitors.

By default, an anonymous comment post is said to have been posted by Anonymous. You can change this from the Comments Option panel further down the Web Site Configuration menu:

Building Websites with PHP-Nuke

Here you can restrict the size of a posted comment with the Comment Limit in Bytes (this is a count of all the characters used in the comment, including any HTML tags). You can also change the name of the anonymous poster from the Anonymous Default Name field. As ever, when working with site preferences remember to save your changes with the Save Changes button at the bottom of the Web Site Configuration menu.

Administrator Removal of Comments

When you are logged in as the administrator, a Delete link appears on each comment:

 

Building Websites with PHP-Nuke

By clicking this link and confirming, you can remove the comment. Since the comment discussion is 'threaded', there could possibly be replies to that comment; in this case, all the replies to that comment will also be deleted. Also, all the replies to those replies will be deleted as well, and so on. This is the only way to remove comments from a particular story.

You may want to delete a comment if it is particularly offensive, or is just basically nonsense. This brings us onto a rather delicate topic...

Filth Filter

Some people have a rather 'colorful' vocabulary, and may feel the need to emphasize their point with bad language. I don't mean poor grammar, I mean BAD language. To prevent your site being filled with rude words from visitor-submitted content, PHP-Nuke has a built-in filter for obscenities, words that I'd rather not put on this page.

This filter is controlled from the panel called Censure Options of the Web Site Configuration menu (it's right at the bottom, you will have to scroll all the way down):

Building Websites with PHP-Nuke

PHP-Nuke has a list of words (stored in the file config.php, if you really must look) that it will scan text for, depending on the value specified in the Censor Mode option. These options allow you to decide how the bad words should be matched.

You can choose one of the following options (let's pretend love is a bad word for the sake of argument here):

  • No filtering: This option allows any kind of language in the comments. This turns the 'filth filter' off.
  • Exact match: This option only matches exact occurrences of the bad words in your text. It will match the word love in the text this is love I think, but will not match in I think it is lovely.
  • Match word at the beginning: This option will match occurrences of the bad words when they are the start of words. It will match the word love in the text I think it is lovely, but not in I am wearing a glove.
  • Match anywhere in the text: This option will match bad words wherever they appear; at the start of words, or the middle of words, it will hunt them down and match them. With this setting, the word love will be matched in all the previous examples. This setting is the default value.

Once a bad word is found, it is replaced with the text specified in the Replace Censored Words with field.

Note that filtering happens before the text is stored in the database, but after any previewing. Thus if a bad word is found in the text with filtering turned on, that word is immediately replaced by the censor text, and the bad word is gone forever. If you change the settings of the filth filter later, then the bad word will not reappear; only the censored text remains. And another thing—turning on the filth filter will not 'retrospectively' filter text. If you have bad words in comments, they will not be censored automatically. You have been warned!

The filter does not apply to administrator-submitted stories. As the administrator, you are in a very trusted position, and you should always be careful what you write!

Karma and Comment Moderation

In an earlier screenshot of the comments, you may have caught sight of the poster's karma displayed next to their IP address:

Building Websites with PHP-Nuke

The karma of the comment poster has consequences for the fate of their comments. Users who are marked with bad karma cannot post comments directly to the site. When they post a comment, they will be greeted with the following screen:

Building Websites with PHP-Nuke

The super user will have to approve the comment of a user marked with bad karma before it goes onto the site. If a user is marked with devil karma, then their comment is immediately rejected. This method of censorship isn't simply to keep dissenting or controversial opinions off your site; it is also to prevent people posting 'comment spam', which could be annoying adverts for other products or sites, or simply obscene and irrelevant comments.

We have just seen how PHP-Nuke handles obscene comments, but karma can be used to control situations where there seems to be a systematic abuse of your comment posting facility. After all, posting a comment is the easiest way for anyone to get their information up on your site, unopposed. Not everyone who registers with your site may be intending to use it as you imagine. If your site becomes successful, with good traffic, then people may view posting comments to stories on your site as an opportunity for free promotion, often for a product that is completely unrelated to your site, and often for something that you rather not have promoted on your site, if you take my drift....

If, as the super user, you find comments from a particular user that you do not feel belong on your site, then you can click on the User Info link in the comment, and you will be taken to that user's Your Account module, and you will be able to see their current karma:

Building Websites with PHP-Nuke

You can change the karma of that user by clicking on one of the images in the middle of the panel. The default value, good karma, allows users to freely post comments to new stories. If you feel the need to keep a user under observation, you can mark them with regular karma, but they can still post freely. Should they continue to misbehave with their comments, you can upgrade them to bad karma. This is when you have to approve their comments before they are accepted. If the comments continue to be unacceptable to you, marking them with devil karma prevents them from posting entirely.

Another alternative for dealing with systematic abuse of your system by a user is to disallow any access to the system from their IP address by clicking on the Ban This IP link. This takes you to the Ban IP module. Banning IP addresses is a very drastic measure, especially since you may be banning an entire group of innocent people who may share the same IP address as the villain you are attempting to exclude. If people are accessing the Internet through a network or a proxy server then that will determine their IP address. Also, the villain may reconnect to the Internet and be assigned a new IP address by their ISP, in which case they will have avoided the ban.

After a marked user posts their comment, the super user can approve or reject their comment by first clicking on the Moderation icon in the Administration Menu:

Building Websites with PHP-Nuke

This will bring up the karma-moderation panel. This panel shows the number of comments that are waiting for you to approve, and also the number of marked users, if any.

Building Websites with PHP-Nuke

Clicking any of the Comments links will bring up a list of the comments waiting for you, a link to view the comment, and a pair of buttons to approve or reject these comments. You can't edit a comment, only approve or reject it. After approval, the comment will go onto the site as usual. You will note that this karma-approval system also applies to comments from some other modules, Surveys and Reviews.

You can click the All Marked Users link to bring up the list of users whose karma you have marked:

Building Websites with PHP-Nuke

Clicking on the user name will take you to that user's Your Account module, from where you can modify their karma or ban their IP address as we discussed earlier.

This has been moderation by the super user. Now we turn our attention to another form of moderation; moderation by other users.

Comments in Moderation

We are now about to enter the arcane world of PHP-Nuke comment moderation by users. Moderation isn't quite the right word; nobody can alter another person's comment (apart from the administrator who can remove a comment entirely). First things first; we shall enable comment moderation from the Administration Menu.

Time For Action—Enabling Comment Moderation

  1. Log in in as the administrator.
  2. Go to the Web Site Configuration menu by clicking on the Preferences icon in the Administration Menu.
  3. Scroll down the page until you see the Comments Moderation panel:
  4. Building Websites with PHP-Nuke

  5. From the drop-down box, select Moderation by users.
  6. Scroll further down the page, and click on the Save Changes button.

What Just Happened?

Before we can use comment moderation, it needs to be enabled, and this is done through the Comments Moderation panel in the Web Site Configuration menu.

There are three options:

Building Websites with PHP-Nuke

The default option, No Moderation means comments cannot be moderated. Moderation by Users allows registered visitors to moderate comments, and Moderation by Admin allows only administrators to moderate comments.

By selecting Moderation By Users we have chosen to allow any registered visitor to moderate the comments.

Users are able to 'rate' a comment with one of the following ratings:

  1. As Is
  2. Offtopic
  3. Flamebait
  4. Troll
  5. Redundant
  6. Insighful
  7. Interesting
  8. Informative
  9. Funny
  10. Overrated
  11. Underrated

These ratings, rather than assigning a score to the comment, provide a description of the value of the comment. Some are straightforward; it's clear what Insightful, or Interesting means. Some, such as Flamebait or Troll are more steeped in the lore of discussion boards. Flamebait is a question or comment that people should really be able to find the answer about somewhere else easily. Marking a comment as Troll would indicate that you think it is making a provocative point just to start a heated argument. The poster looks like they're more interested in arguing than stating or learning sensible views.

Although the ratings do not directly assign a score, a comment does have a score and the type of rating does alter the comment's score.

When a comment is first posted, it is awarded a score of one (anonymous posts, if allowed, are awarded a score of zero).

When a user rates a comment, the score of the comment can change in one of the following ways:

  • No change: The user has chosen the As Is rating.
  • The score increases by one: The user has chosen a 'positive' rating. This is one of the Insightful, Interesting, Informative, Funny, or Underrated ratings.
  • The score decreases by one: The user has chosen a 'negative' rating. This is one of the OffTopic, Flamebait, Troll, Redundant, or Overrated ratings.

In this way the score of the comment changes as users rate the comment. The score can take a value from a minimum of –1 up to a maximum of 5. Note that the score of a comment has nothing to do with the score of the story that it is posted to; the score of a story is determined by user voting in the Article Rating block next to the story. We saw that earlier.

Now this is where the 'moderation' comes in. Every user has a 'comment score threshold', by default set to zero. The option to change the score is present on the Comments Configuration page (go there from the Comments link in Your Account or by clicking the Configure link in the comments bar). Any comment with a score less than this threshold value is not displayed to the user.

By adjusting their 'comment score threshold', the user can filter out comments that are not worth reading.

Other users who have read and rated the comment have made the judgment for you of whether a comment is worth reading.

That's the idea. Let's try it out.

Time For Action—Moderating Comments

  1. Log out from the administrator account.
  2. Click on the Home link in the Modules menu to return to your homepage.
  3. In the Login block on the right-hand side of the page, log in as testuser (enter testuser as the Nickname and testuser as the Password, then click on the Login button).
  4. Once you are logged in, click on the Home link in the Modules menu to return to the site homepage.
  5. Find our first story, and click on the Read More... link
  6. Scroll down the page to find our existing comment that we added earlier:
  7. Building Websites with PHP-Nuke

  8. We really like this comment. Let's select Informative from the drop-down box.
  9. Click the on MODERATE! graphic. When the page reloads, you will see this:
  10. Building Websites with PHP-Nuke

  11. Actually, upon reading the comment again, I'm not that impressed. Select Offtopic from the drop-down list.
  12. Click the MODERATE button.
  13. When the page reloads, the comment should now look as in the first image above.

What Just Happened?

We just moderated a comment, twice in fact.

After logging out from the administrator account, and then logging back in as testuser, we had a look at the existing comment. We had seen this comment earlier (we added it!), but this time, the rating drop-down box has appeared.

First of all, we selected a 'positive' rating from the drop-down box—Informative. Clicking on the MODERATE button got the moderation process underway, and when the page reloaded, the score of the comment had increased by one (to two if you must know).

Next, we chose a 'negative' rating—Offtopic, clicked on the MODERATE! button and the score of the comment decreased by one.

Multiple Comment Moderation

It's worth noting that if there is more than one comment displayed on the page, then separate drop-down boxes will appear for each comment.

In cases like this, you can moderate several comments at once by selecting their rating from the relevant drop-down boxes. If you don't touch one of the comments, its rating will be submitted as As Is, and the score won't change.

Building Websites with PHP-Nuke A practical guide to creating and maintaining your own community website with PHP-Nuke
Published: November 2005
eBook Price: $20.99
Book Price: $29.99
See more
Select your format and quantity:

Customizing the User View of Comments

Each individual user is able to customize their view of the displayed comments. This is done by clicking on the Configure link in the comments bar (shown enclosed in a box):

Building Websites with PHP-Nuke

Clicking on this link brings you to the Comments Configuration page of the Your Account module.

Another way to reach this page is to click on the Comments link in the navigation bar of the Your Account module (shown below enclosed by a box):

Building Websites with PHP-Nuke

Note that if the option Activate Comments in Articles? in the site preferences is set to No (so that comment posting is disabled for all articles), then the Comments link is not displayed in the Your Account menu, and the comments bar is not displayed under any stories. In this situation, no customization can be made by the user.

The Comment Configuration page has a number of options for customizing the display of comments:

Building Websites with PHP-Nuke

Do Not Display Scores is the most straightforward option, selecting this and clicking on Save Changes causes the score of any comment to be not displayed. The scoring process still goes on, but the scores are never seen.

The Sort Order field allows you to order the list of comments by the date they were posted or by the score for the comments. The comments used in the sorting are only the top-level comments. If you have an old comment with a new reply, that is still viewed as an old comment from the sorting point of view.

You truncate the displayed length of any comment by putting a new value for Max Comment Length field. This does not prevent any comments being longer than that value; it simply abbreviates the display. Here we've set the Max Comment Length to 32 and are viewing our first comment:

Building Websites with PHP-Nuke

A Read the rest of this comment... link has appeared, and clicking on that link brings you to the full text of the comment:

Building Websites with PHP-Nuke

Clicking on the Root link takes you back to the list of all the top-level comments.

The Comment Configuration page allows you to choose from four ways of displaying comments. These options are available in the Display Mode drop-down box:

  • No Comments
  • Nested
  • Flat
  • Thread

The default value is Thread. This displays all the top-level comments, and any replies are shown indented, with only the title of the reply displayed. This is the view that we have been seeing on comments so far.

Choosing the No Comments option means comments will not be displayed to you, and the Flat option displays all the comments underneath each other, with no indentation, grouping a comment and all its replies together.

The Nested view is similar to the Thread view, in that it displays all the comments, grouping together a comment and its replies with indentation, but the text of any reply to a comment is displayed rather than just the title of the reply:

Building Websites with PHP-Nuke

The final comment customization option for users is the 'comment-threshold value' that we mentioned earlier. You may recall that the point of this is to prevent any comments whose score is less than the 'comment-threshold value' from being shown. There are seven values for the 'comment-threshold value' selected from the Threshold dropdown:

  • -1: Uncut and Raw
  • 0: Almost Everything
  • 1: Filter Most Anonymous
  • +2: Score +2
  • +3: Score +3
  • +4: Score +4
  • +5: Score +5

The default value is 0: Almost Everything. This means that majority of the comments will be displayed. The only comments that will not be displayed are those with score –1, which are comments considered to be poor by other users (or maybe even by you).

The value +1: Filter Most Anonymous value will filter out most of the anonymous postings made to the site; remember that an anonymous posting is assigned a score of zero by default. For an anonymous posting to be displayed with this setting means that it will have to have been 'moderated up' by other users.

The other values are quite straightforward; they will filter out any comments with value less than the score mentioned in the value. Thus choosing +5: Score +5 will mean that only the best 'quality' comments will be displayed to you.

Time For Action—Filtering out Comments

  1. Make sure that you are logged in as the testuser user, and are on the Comments Configuration page (go there from the Comments link in Your Account or by clicking on the Configure link in the comments bar).
  2. Select +2: Score +2.
  3. Click on the Save Changes button.
  4. When the page reloads, you will find yourself back in the Your Account module. Click on the Home link in the Modules block to return to the homepage of your site.
  5. Find our first story, and click on the comments link.
  6. When the story is displayed, the comments bar will be displayed underneath, but no comments can be seen! (that wouldn't make a very interesting screenshot).

What Just Happened?

We set the 'comment-threshold value' to a score of two in the Comment Configuration page. This meant any comment with a score of less than two is not displayed to us, in this case testuser. Our existing comment has a score of one (when we left it at the end of the last Time For Action moment it had). Thus it is not displayed to us. Visitors are able to moderate comments with impunity.

Story Management

For the administrator, story management begins on the homepage of the administration area. Scroll down the page and you will see the last 20 published stories:

Building Websites with PHP-Nuke

The story titles are displayed, along with their story ID (in the left-hand column of the table), the language they were entered in (All), the name of the topic (that short string with no spaces, remember that?), and then icons to edit or delete any of these published stories.

When a story is posted to your site and stored in PHP-Nuke, the story is assigned a story ID. The story ID is unique to each story, and is used to identify the story. For example, the URL of the extended text view of the story uses the story ID:

http://localhost/nuke/modules.php?name=News&file=article&sid=N

where N is the story ID.

Editing Stories

There are three ways to begin the editing process. One way is from the front end of the site, the other two are from the administration area:

  1. From the extended text view of the story itself there is an Edit icon in the Options block:
  2. Building Websites with PHP-Nuke

  3. If the story is displayed in the Last 20 Articles table on the administration homepage, it will have an Edit link.
  4. By entering the story ID into the textbox under the list of Last 20 Articles, selecting Edit from the dropdown, and clicking the Go! button.

Each of these brings you to the Edit Article page.

The Edit Article page has almost the same fields as the Add New Article page. However, it is missing the ability to attach a poll to the story, and you cannot alter the schedule of a programmed story.

You can change the title of the story, the topic or category to which it belongs, and any related topics, and of course edit the story and extended text. The Publish in Home? and Activate Comments for this Story? fields are also there, on call to be changed if desired.

An additional field in the Edit Article page is the Notes field. This field allows the administrator to add notes about the story, for example to express the fact that the views of the story are not those of the site for a particularly contentious story.

Clicking on the Save Changes button on the Edit Article page updates the story.

Deleting Stories

As with editing stories, there are the three same ways to delete a story.

  1. From the extended text view of the story itself there is the Delete icon in the Options block:
  2. Building Websites with PHP-Nuke

  3. If the story is displayed in the Last 20 Articles table on the administration homepage, it will have a Delete link.
  4. By entering the story ID into the textbox under the list of Last 20 Articles, selecting Delete from the dropdown, and clicking on the Go! button.

Each of these brings you to a screen asking you to confirm if you want to delete that story, and giving you the opportunity to back down. Deleting a story means deleting the story and all its comments.

User-Submitted Stories

So far we've been adding stories ourselves, as the site administrator. One of PHP-Nuke's coolest features is the ability for site visitors to submit their own stories for administrator approval and then, hopefully, publication to the site. In this section that's what we'll do.

Setting Up the Mail Notification

When a visitor submits a new story to your site it goes into a submissions queue, pending moderator approval. PHP-Nuke will email a notification of this to an administrator, alerting them to come and approve the story.

As we discussed in earlier articles, using email in this way requires your site to have access to outbound mail functionality. We won't discuss that here, but leave that until we have deployed the live site. However, we will discuss the settings to form the notification email sent out.

The notification settings are set in the Web Site Configuration menu, in the Mail New Stories to Admin panel:

Building Websites with PHP-Nuke

Firstly, to get any email notifications at all, you need to select Yes in Notify new submissions by email?. The default value is No.

The Email to send the message: field is the email account of the person who will receive notification of the new submission. It is not the email account that sends the notification. In this field you will enter the email address of the administrator who is going to be responsible for approving the stories (that would be you!).

If you need to specify more than one person to receive notifications, enter all the email addresses separated by semi-colons (;) into this field.

The Email subject: field holds the subject of the email notification. You can enter a short message for the receiving administrator into the Email message: field.

The Email Account (From): field specifies the account name from which the notification mail will be sent. You should not include the domain of the account in here; this is handled by the outbound mail server. Note that the account you specify here does not actually have to exist, since it is not actually 'sending' the mail, but only appears to be doing so to the sender.

Once you have set up these details, click on the Save Changes button at the bottom of the Web Site Configuration menu and you're ready to receive notifications.

Visitor Story Submission

Users submit stories from the Submit News module. Stories can be posted by unregistered visitors. The Submit News module shows them a form similar to the Add New Article form, into which they type the title of their submission, select a topic, and then enter the story text and the extended text.

Users cannot select a category for the story, nor can they activate comments, nor program the story.

At the bottom of the form is a Preview button; once they have clicked on that to see their story previewed, an Ok! button appears next to it for them to submit the story. Visitors cannot submit their stories without previewing them first. Whether they read the preview is another matter!

Once the visitor clicks on Ok! and their story is submitted, their work is done. They are thanked for submitting their story, and told how many stories are waiting in the submission queue.

Approving Stories

Once the visitor has submitted their story, a notification is sent to the administrator. The email sent is of this form:

Hey there...
You got a new story submission for your site.
========================================================
TITLE OF THE STORY
This is the story text
This is the extended text.
testuser

The message at the top of the email is from the Email Message field of the Mail New Stories to Admin panel of the Web Site Configuration menu, and the subject of the email is from the Email Subject field.

Underneath the top message is the story title, then the story text followed by the extended text, with the author's name at the bottom. The message is sent as a plain text email rather than in HTML form. Upon receipt of the email, the administrator will know that there is a new story waiting for them, and they will head off to the administration area of the site to check it out.

If there is no mail sent, or the administrator does not receive the mail for some reason, this does not alter the approval process. The administrator stills need to log into the administration area of the site, and the Waiting Content block will advise them of any submissions:

Building Websites with PHP-Nuke

Clicking on the Submissions link brings you to the Stories Submission Administration page, which lists the submitted stories that are still waiting approval:

Building Websites with PHP-Nuke

From this table, you can view the user profile of the submitting author by clicking on the author's name in the Author column. The user's karma is also displayed next to their username, so you can easily identify pests. If you wanted to delete the story without reading it, clicking on the Delete icon allows you to do this. This removes the story entirely from the list of submissions.

The Delete link under the table clears the entire queue of submitted stories.

Clicking on the title of the story, or on the Edit icon, brings you to a form similar to the one for adding a new story. Here you can edit any part of the story, add some notes to the story, or even change the topic or category if you desire. It is also possible to program this story or attach a poll. None of these things can be done by the user.

There is also a link to email the submitter directly, or send a Private Message. Possibly you want them to clarify something.

At the foot of the form is the familiar drop-down box to select previewing the story or posting it, an Ok! button for publishing the story, and a Delete link, which will delete the story from the list of waiting stories.

Once you click on the Ok! button after selecting Post Story, the story will be posted to the site in the usual way, and the story is removed from the list of submissions.

If you post the story (accept it), there is no notification to the author that their story has been accepted. They will be able to see it on the site! If you delete the story (reject it), again there is no notification to the author. This is only a two-stage process—submission and approval. There is no real scope for sending comments about the story back to the author and having them resubmit, without having them type in the whole story again.

With users submitting their own stories, the content on your site will hopefully grow quickly, and users will have the satisfaction of contributing and participating in the community of your site.

Finding Stories

The visitor (and administrator) can access stories from a number of places on a PHP-Nuke site. These places are:

  • The site homepage
  • The Topics module
  • The Search module
  • The Story Archive module
  • The Categories Menu block

In this section, we will run through how these places gain you access to particular stories.

From the Homepage

On the homepage of your site, provided the News module is selected as the Home module, the most recently published stories are listed. The number of stories displayed in this list is controlled by the Stories Number in Home option of the Web Site Configuration options. By default, the value is 10.

Clicking on the Read More... link will take you to the extended text view of the story.<

From the Topics module

The Topics module displays the list of topics and their associated images, along with the titles of the ten most recent stories posted on that topic.

Clicking on any of the story titles will take you to the standard, extended view of the story.

From the Search module

The Search module allows the visitor to search most of the content stored in PHP-Nuke (there are some other modules whose content is searchable from this module; we'll see them in the next article).

Of particular relevance to stories is that you can choose to refine your search like this:

  • Search all topics or a single topic.
  • Search stories in all categories or a single category.
  • Search stories by all authors or a particular author. Note that here author means the user who posted the story to the site (usually the administrator), not the original author of the story.
  • Search only stories posted within the last week, last two weeks, or up to three months ago.

These options are chosen from the drop-down box in the Search module:

Building Websites with PHP-Nuke

If any results are found, the titles of the stories and information like the author of the story is displayed. Clicking on the title of a story will take you to the extended text view of the story.

From the Story Archive

The Story Archive module first displays a list of months for which stories were posted, and clicking on any of the months will bring up all the stories posted that month:

Building Websites with PHP-Nuke

From this table, you can click on the story title to view the extended text of the story, or jump straight to the printer-friendly view of the page or send the story to a friend using the icons on the right-hand side of the table.

From the Categories Menu Block

There is no built-in module for displaying the list of story categories. However, the Categories Menu block is included with the PHP-Nuke installation, and this block gives you a display of all the story categories that actually have stories assigned to them.

This block is already loaded into PHP-Nuke but is not activated. It is also set up as a right-hand block by default.

Each of the category titles displayed in the block is a link to the page displaying the most recent stories in that category. The page containing the most recent stories in a category has a URL of this form:


http://localhost/nuke/modules.php?name=News&file=categories&op=newindex&...

where catid is known as the category ID, with 0 being the Article category.

The category that you are currently viewing is indicated in the Categories Menu block in bold, and is not a clickable link. This can be quite frustrating if you click on a story in that category, read it, and then want to return to the list of stories in the category. You will have to use the Back button in your browser since the link to the category in the Category Menu block is not a link at all.

Special Administrator

For working with stories, a special administrator account can be created with privileges for only the News module.

This administrator is created in the usual way from the Edit Admins link in the Administration Menu. Here we are creating an administrator with News privileges:

Building Websites with PHP-Nuke

When logging into the administration area with this account, the administration menu looks desolate with only two icons displayed in the Modules Administration menu, and there is no sign of the Administration Menu, since this administrator does not have the permissions to access the core administration operations, only News operations:

Building Websites with PHP-Nuke

We can still create, edit, and manage stories with this account, but we cannot do anything outside the confines of the News module. We cannot for example, disable comment posting from the Web Site Configuration menu with this account; we do not have those privileges.

There is also a Surveys privilege in the administrator account menu. If you have News privileges but not Surveys privileges then you can fill in the details to attach a new poll to a story, but the poll itself will not be created.

If you create a News administrator without access to the Topics module, then they cannot create or edit topics. They can create manage categories, but not topics.

If you wish to use the email address of the News-only administrator to receive email notifications of user-submitted stories, then the site super user must set this from the Web Site Configuration menu. Just because an administrator has News privileges does not mean they will receive the notification emails.

Points and Prizes

There are a lot of opportunities for visitors to interact with stories, and as such, there are many opportunities for them to collect points:

  • Submitting a story from the Submit News module that is actually published by the administrator
  • Posting comments
  • Sending a story to a friend
  • Rating a story
  • Voting in a survey
  • Commenting on a survey

The points for these activities are, as usual, determined from the User Groups area of the administration area.

Sharing your News

In an earlier article, we saw the RSS/RDF block. This block was able to pull headlines from another site via RSS and display them in the block. With PHP-Nuke it is possible to have your stories 'exposed' in a similar way.

Browse to the http://localhost/nuke/backend.php file in your browser, and you should see something like this in your browser window:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE rss PUBLIC "-//Netscape Communications//DTD RSS 0.91//EN"
"http://my.netscape.com/publish/formats/rss-0.91.dtd">
<rss version="0.91">
<channel>
<title>the Dinosaur Portal</title>
<link>http://localhost/nuke</link>
<description>
Just because you haven&#039;t seen a dinosaur, doesn&#039;t mean
they&#039;ve all died out!
</description>
<language>en-us</language>
<item>
<title>the Dinosaur Portal is Alive!</title>
<link>http://localhost/nuke/modules.php?name=News&amp;
file=article&amp;sid=1
</link>
</item>
</channel>
</rss>

That's clearly not a standard HTML webpage, and it's not supposed to be. It's a specially structured file, an XML file in fact, with the story titles and a link to them. This is the format of the RSS news feed, and can be consumed by RSS readers, such as your own RSS/RDF blocks that we saw in previous articles.

The description and language elements are set from the Backend Configuration panel in the Web Site Configuration menu:

Building Websites with PHP-Nuke

A maximum of ten stories can be included in the output of the backend.php file. Adding a cat parameter to the URL, say http://localhost/nuke/backend.php?cat=1 will display the stories in the category corresponding to the category ID specified by the cat parameter. We discussed the category ID earlier in the From the Categories Menu Block section. There is nothing else that you need to do to prepare your stories for RSS syndication.

Polls and the Surveys Module

As we mentioned earlier, when a story is created there is the option to associate a poll with the story. This can only be done at the time of story creation; you cannot add a poll to the story later. A poll attached to a story can be thought of as a survey related to the story's content.

Although you can't add a poll to a story after the story has been created, you can create a survey independently of a story from the Surveys module. If you want your poll/survey to appear in the Survey block (like the What do you think of this site? poll) then you must create it as a survey.

First we'll look at adding a poll to a story.

Attaching a Poll to a Story

As the administrator, you get the option to attach a poll to the story before you post a story to the site. Underneath the Add New Article panel is the Attach a Poll to this article panel. To create a new poll you simply enter the question into the Poll Title field, and then enter the options below:

Building Websites with PHP-Nuke

There is no need to click on any more buttons. When the story is posted, provided there is some text in the Poll Title field, the new poll will be created and attached to the story.

The poll is displayed to the right of the extended view of the story:

Building Websites with PHP-Nuke

Note that the Article Rating poll is still there as well, but pushed further down the page.

By selecting one of the options and clicking on the Vote button, you can participate in this poll—the same voting restrictions apply as seen earlier with the Article Rating poll. After your vote is registered, the current results of the poll are shown. This is all happening in the Surveys module.

Building Websites with PHP-Nuke

Here you can see the total number of votes cast in the poll, and the percentage split of the votes. This is also the view you will get by clicking on the Results link in the poll block itself. It is also possible to post comments for an individual poll. The comments are displayed underneath the poll as they are with stories.

The image above actually shows the administrator view of the results, with the extra Add and Edit links that are not visible to the standard visitor. As administrator, you can change the options of the poll by clicking on the Edit link. The Add link allows you to create a new survey.

Curiously, when creating a new poll from the Add link, you are actually able to attach a story to the poll, for announcing the poll if you like. However, the poll will not be displayed alongside the story in the way that a poll attached to a story is. If you want to include a link to the poll from the story announcement, the link will be of the form:

http://localhost/nuke/modules.php?name=Surveys&pollID=NNN

However, you won't know the pollID until the poll has been created, so you will have to edit the story after creating the poll to correct the link.

The Surveys Module

Voting and seeing the result of polls takes place in the Surveys module. When you click on the Surveys link in the Modules block and go to the homepage of the Surveys module, you are shown the list of surveys and any surveys attached to articles.

Building Websites with PHP-Nuke

The What do you think about this site? survey is added to the site by default. From here you can vote in the survey by clicking on the title of the survey, or view the results from the Results link. Administrators are able to edit the story options by clicking on the Edit link (shown in the image above).

Survey Management

In addition to this front-end way of managing surveys through the various Edit and Add links, there is also functionality in the Modules Administration area for managing surveys.

First of all, if you scroll down the screen on the administration menu page you will see the title of the current poll (the most recently created poll that is not attached to an article) displayed:

Building Websites with PHP-Nuke

You can use the links there to edit the options of that poll, or create a new one.

In the Modules Administration menu of the Administration Menu page is the Surveys icon:

Building Websites with PHP-Nuke

Clicking on this icon brings you to the Polls/Surveys Administration area. In this area you can add new polls and edit existing polls as we have seen already, but you can also delete polls.

Clicking on the Delete Polls link in the Polls/Survey Administration area brings up a list of the current polls. Selecting the poll to remove and clicking on the Delete button removes the poll. There is no confirmation screen, it goes straight away.

Summary

This article gave us an overview of stories and the story publication process. We saw the way stories on our site are organized; stories are classified into topics and categories. We also added our own stories and saw how to edit and manage them.

One of PHP-Nuke's great features with its handling of stories is the number of opportunities for visitors to contribute. We saw how visitors can post their own stories, and the process the administrator follows to approve these stories for publication on the site.

Comments are an important part of any community-driven site and we had an in-depth look at these. We also saw how comments are moderated, both by the administrator and by the users of the site.

[ 1 | 2 |3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 ]

If you have read this article you may be interested to view :

About the Author :


Douglas Paterson

Douglas Paterson is a full-time acquisition editor and part-time author for Packt Publishing. He is a doctor of Mathematics and has over five years experience of working on programming books across a number of different subjects. He lives in Birmingham, England, with his wife, and his unusually hairy dog, Zak.

Contact Douglas Paterson

Books From Packt


Drupal 6 Performance Tips
Drupal 6 Performance Tips

CMS Made Simple 1.6: Beginner's Guide
CMS Made Simple 1.6: Beginner's Guide

Moodle 1.9 Teaching Techniques
Moodle 1.9 Teaching Techniques

Getting started with Audacity 1.3
Getting started with Audacity 1.3

Python Testing: Beginner's Guide
Python Testing: Beginner's Guide

Grok 1.0 Web Development
Grok 1.0 Web Development

MediaWiki 1.1 Beginner's Guide
MediaWiki 1.1 Beginner's Guide

iReport 3.7
iReport 3.7


Your rating: None Average: 3 (1 vote)

Post new comment

CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.
u
x
6
Y
L
r
Enter the code without spaces and pay attention to upper/lower case.
Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software