Subjects 2.0 Usage Manual

I. Module Purpose

II. Definitions of terms

1. Categories

2. Subjects

3. Pages

4. Subpages

5. Title

6. Description

7. Keywords

8. Content

9. Activate

III. Multi-languages

IV. Page Submissions by user

V. Permissions

VI. Hack header.php

I. Module Purpose

Module is designed for structured storage and display of textual content with the optional ability to store content in files on the hard drive. Subjects is probably the best means for converting existing HTML pages to a dynamic CMS site.

II. Definition of terms

1. Categories

These are top level categories They may not not be used on some sites. If a category has no subjects within it, it will not be displayed to users. Once created, a category will be displayed as a link, even in a block. Click this link and you'll only see subjects belonging this category displayed on the page

2. Subjects

These are classifications or sections .They are displayed on the subject module's main page. They may be independent or may be within a category. They contain pages within them.

3. Pages

These are the main content items and must be part of a subject. They are stored and displayed inside a subject. Along with textual content they also can include attached subpages which can be listed as links (use !!subpageslist!! on the place where are you want links to appear).

The content of the page itself can be stored in the database or in a file on the hard drive. Any page may contain an unlimited number of subpages.

4. Subpages

Like pages, subpages are items of content and must belong to a page. The only difference is that they cannot have certain attributes (author, logo, etc.) and reviews but may be activated or deactivated for display. Subpages can also have attached subpages of their own in an infinite number of sublevels.

5. Title

This is a required attribute for any element of the module - Category, Subject, Page or Subpage.
Its main purpose is to be used as content of tag <title>...</title>. See "Hack of header.php"

6. Description

This is an optional but important field. Displays description of title in the browser title area. Content of this field is also used as content of <meta description> tag, if filled out.

7. Keywords

Your keywords for search engines. Content of this field is never displayed the browser title area but is used as the <meta keywords> tag.

They use the inheritance principle.

When you create a new category this field will import meta-keywords from you site config settings. You can easily change them and content will be stored in database (DB) and used as content for <meta keywords> tag when list of subjects attached to a category is displayed.

Next, when you create new subjects under a category, content of keywords field for a category will import the subject's keywords field, which you can change at any time. As before, this field is used for content of <meta keywords> tag on the page which displays pages in a subject. The same rule applies for any level of module's items.

8. Content

Value of this field is your content, your article, whatever you have to say. There are two ways to store the content of this field:

1. Store it in the database. Just fill out this field with your text (HTML formatting only for now) using text area or the WYSIWYG built-in editor, then you press the "Add" button. Your text will be stored in DB.

2. Store in file on the hard drive. The data will be retrieved by the module and displayed for the user who accesses it via a browser.

There are two ways to deliver file with content to the hard drive:

  • you can create the file from the module. Just fill out the content field with your text (HTML formatting only for now) using text area or your CMS WYSIWYG built-in editor then specify filename in appropriate field and press "Add" button.
    Module will automatically create the file with specified name and write content into it. Use the same method to edit this file. The module will only use the DB to store attributes of page and path to the file.
  • you can upload formatted file to modules/subjects/pages/ using FTP or any upload module (we suggest you use ew_filemanager). After that you have to create new page (or subpage) and just specify the path to you file. You also able to edit this file in the above mentioned way.
NOTE:
You don't need to use <html>, <body>, <head> for formatting you content. Just real formatting tags like <p>, <br>, etc.
Module assumes that all files with content will be stored in modules/subjects/pages/ directory. Use only the part of the path after modules/subjects/pages/ when you are pointing page or subpage to your content file.

Warning : To be able to write to file you have to set appropriate permissions, but you needn't be concerned about them if you are using ew_filemanager.

You can easily change way of storing for your pages or subpages. For example, you have a page with content stored in DB. Go to 'Edit' this Page and indicate filename in the appropriate field. When you click the 'Save' button, module will create file with content and remove this content from DB, and vice versa. If you have content of a page stored in file, just empty field with filename when you are in 'Edit' and press 'Save'. Content will then be stored in DB (16 Mb maximum). You have to delete file from the hard drive by yourself. The module will not delete it for you.

9. Activate Page (Subpage)

You have to activate pages or subpages to be displayed for users. They are activated by default. However, if you want to postpone publishing a page, such as when it is a work still in progress, you can uncheck this option and page will stored in DB (in file) but will not displayed to users.

You can change the status of a page or subpage to at any time to either active or inactive. You can even program a page to be displayed on a particular date and time but it must be activated first.

III. Multi-languages

The module is multi-language.

It works in the following way:

Module checks browser language for current user language only for the Subjects module. Therefore, if Subjects is set for 'rus' language it will never display for users browsing site with 'eng' language set in their browsers. In addition, pages and subpages attached to a subject will not display either. Assuming that a category usually contains subjects in only one language, if none of the subjects under a category match user's language, no category will be displayed for this user.

The same rules apply for blocks.

IV. Page Submissions by user

User with ACCESS_COMMENT permissions can submit a new page. He will see 'Submit page' link on the top of Page lists pages. After submission is done, page will be stored in DB with the status 'inactive' and link to the waiting content displayed in Subjects' block. To publish a submitted page, admin needs to change status for this Page to 'active'.

V. Permissions

Module checks for access level for the following module's items:
  • All module content - 'subjects::' => '::'
  • Category - 'subjects::category' => '::category ID'
  • Subject - 'subjects::subject' => '::subject ID'
  • Page - 'subjects::page' => '::page ID'
Access levels:
  • None: can nothing *
  • Overview: can see titles and descriptions *
  • Read : + can see content
  • Comment: + can submit pages
  • Edit: + can edit item(s)
  • Delete: + can delete item(s) + edit reviews (cannot delete reviews)
  • Admin: can everything.
A new permissions system for Subjects is in the early stages of development. At present, we offer you the choice of the two models of permissions systems as we develop a more flexible and universal algorithm.

Model #1 - 'inheritance'

In a few words - this model is for a large amount of content and sites with several co-admins.

The main point of the model is that any privileges granted to higher (parent) level of content are inherited by subordinate levels..

For example, you grant to a group or user 'EDIT' privileges for a category. In such a case all subjects with pages and subpages which belong to this category will have 'EDIT' privileges for this group or user.

If you want to 'downgrade' permissions level for this group, such as to 'READ' inside THIS category - it will NOT work.

Another example. If you have 'Comments' permissions for group 'User' for all content on the site (Users--.*--.*--Comment) you cannot downgrade this level for the Subjects module.

Meanwhile, you can easily upgrade the permission level for different groups, e.g., from 'COMMENT' to 'EDIT' for subject in a category.

In general for this module - you have to always go UP for the access level while going down with content level and each 'daughter' level inherits rights from parent level

Notes:
Options marked with * are reserved for future versions and may work abnormally in v2.02.

This model of permissions system is the default.

Model #2 - 'per item' or 'unheritable'

This is the common PostNuke rules based model. This model is useful for sites without much content or where the admin needs to hide some content from some groups or hasn't many assistants.

Summary, everything is permitted if not restricted, but daughter content levels do not inherit rights from parents.

This model allows you to set privileges separately for each item of content. You can also easily upgrade and downgrade permissions level for any level of content. BUT you have to be very clear when granting rights if they are different than module permissions.

For example, you want to hide one category with all subjects and pages. In this case you have to step by step restrict all items inside this category.

It should looks like the following:

Group Component Instance Permissions level
Users subjects::category ::1 None
Users subjects::subject ::(1|2|3) None
Users subjects::page ::(1|2|3|4|5|7) None
Users subjects:: .* Comment

This example means that group Users can see in category with id=1 containing subjects with ids = 1, 2 and 3 only page with id=6 or id > 7 if exist and if only indicate direct links to those pages.

Notice:
If you have chosen model #2 you have to change some code in /modules/subjects/pnuserapi.php as the following:

  • Comment code from line 230 to line 308. You can do it by writing '/*' in line 230 and '*/' in line 308.
  • Un-comment code from line 318 to line 352. You can do it by replacing '*' with '/' in those lines.
  • Remember that you have to do BOTH above mentioned actions!
We apologize for any possible inconvenience.

VI. Hack header.php

If you want use values of Title, Description and Keywords of module's items in META tags you have to hack your header.php in PostNuke core. If you are using MD Pro, you should skip this section as it does not apply to you.

Before line:

Start code


  	if ($artpage==1)

End code

insert this piece of code:

Start code


global $module, $type, $catid, $subid, $pageid;
$description="";

if ( ($module=="subjects") && ($type=="user")  ) {

	list($dbconn) = pnDBGetConn();
	$pntable = pnDBGetTables();

	$title="";
	$keywords="";
	$sql="";

	if (isset($catid)) {

		$column = &$pntable['subcategories_column'];
		$sql = "SELECT $column[catname], $column[cattext], $column[keywords]   
                FROM $pntable[subcategories] 
				WHERE $column[catid]=$catid";

	} elseif (isset($subid)) {
		$column = &$pntable['subjects_column'];
		$sql = "SELECT $column[subname], $column[subtext], $column[keywords]   
                FROM $pntable[subjects] 
				WHERE $column[subid]=$subid";

	} elseif (isset($pageid)) {
		$column = &$pntable['subpages_column'];
		$sql = "SELECT $column[pagetitle], $column[pagetext], $column[keywords]   
                FROM $pntable[subpages] 
				WHERE $column[pageid]=$pageid";
	}
	
	$result = $dbconn->Execute($sql);
	if ($dbconn->ErrorNo() == 0) {
		list($title, $description, $keywords) = $result->fields;
		$result->Close();
	}

	if (!empty($title)) $title.=" :: ".pnConfigGetVar('sitename');
	else $title=pnConfigGetVar('sitename').' :: '.pnConfigGetVar('slogan');

	if (empty($keywords)) $keywords=" :: ".pnConfigGetVar('metakeywords');
	if (empty($description)) $description= pnConfigGetVar('slogan');

	echo '<title>'.$title."</title>\n";
	echo '<meta name="KEYWORDS" content="'.ereg_replace('"','\"',$keywords)."\" />\n";
	echo '<meta name="DESCRIPTION" content="'.ereg_replace('"','\"',$description)."\" />\n";

} else

End code

Next, before line:

Start code


  echo '<meta name="DESCRIPTION" content="'.pnConfigGetVar('slogan')."\" />\n";

End code

insert just one line of code:

Start code


	if (empty($description))

End code

That's all.