News Plugin for CMSimple

IntroductionBack to top

This plugin simplifies publishing news on your CMSimple Website. News can be published in different categories.

News frontend preview.

Additionally the plugin supports a smart and simple BBC-like newsticker powered by the newsticker jQuery plugin.

Newsticker.

VersionBack to top

This is currently version 1.1.1 of the plugin, released 27th October 2014.

RequirementsBack to top

PHPBack to top

The plugin works using fgetcsv() and fputcsv() so requires a PHP version 5 or higher, which is supported by most providers.

Supported CMSimple versionsBack to top

jQuery4CMSimpleBack to top

The plugin will work without jQuery4CMSimple, but the use of jQuery4CMSimple is highly recommended!

Get jQuery4CMSimple: jQuery4CMSimple

The plugin uses jQuery4CMSimple if available. This will reduce the possibility of clashes with other plugins and improve the site's web performance, because jQuery and used plugins are included only once.

jQueryBack to top

The plugin requires jQuery for the newsticker functionality. The plugin will use jQuery4CMSimple if available. If not the current jQuery version 1.7.1 will be used automatically.

NewstickerBack to top

The plugin's newsticker functionality uses the newsticker jQuery plugin version 1.8. The plugin will be included using jQuery4CMSimple or by the News plugin itself automatically.

NewssliderBack to top

The newssldier is based on bxSlider jQuery plugin version 3.0. The plugin will be included using jQuery4CMsimple or the News plugin itself automatically.

UpgradingBack to top

Upgrading from version 1.0.xBack to top

First of all: make a backup of the whole CMSimple installation! Upgrading from version 1.0.x is very easy. Just check that your category files will not be deleted. The location of the files is defined by the filepath configuration key of version 1.0.x. Backup your old configuration file of the plugin found in plugins/news/config/config.php. Now delete the old news plugin and extract the new version in the plugins folder. If you have not changed the following configuration keys you are done and the plugin should automatically detect your categories and the entries.

If you have made changes on these configuration keys, copy the configurations of your configuration backup.

Then you can customize the other configuration keys.

InstallationBack to top

CMSimple XHBack to top

CMSimple 3.3 and CMSimple LEBack to top

This installation guide is left from older versions. This version does not support CMSimple LE and the original CMSimple, see supported CMSimple versions.

The images are taken in CMSimple 3.3, but should help installing the plugin in CMSimple LE, too.

$cf['plugins']['folder'] = "plugins";
CMSimple 3.3 settings. CMSimple plugins_folder configuration.

ConfigurationBack to top

GeneralBack to top

Some general notes about configuration:

Configuration can either be done by directly editing config.php or by using the backend.

Configuration optionsBack to top

There is no need to edit csv_filepath, csv_delimiter, csv_enclosure or rss_file. Important: Do not edit these settings in production environments, all old categories and news won't be read correctly.

The 'blog' option

This plugin is not aimed to be a full-featured blog system. Nevertheless using additional plugins for comments and the archive functionality it could be used as one. But to maintain the 'classical' news functionality - meaning only very short news text and no archive functionality - this option is thought to switch between these two modes. If the blog option is enabled ('true') the title of each entry is shown as link and refers to the original fulltext, and a fulltext can be added in the backend. If the option is disabled ('false') the fulltext can not be added in the backend and the title of each entry will not be displayed as link.

If the jQuery4CMSimple plugin (default in the current CMSimple XH version) is not installed the news plugin will include its own jQuery files. The used versions can be defined using the following options.

Datepicker date formatting

Also see here.

The configuration fileBack to top

/** 
 * Filepath storing CSV containing news.
 * @warning NOTE: Without '/' at the end! 
 * @var
 */
$plugin_cf['news']['csv_filepath']="content/plugins/news";
/** 
 * Delimiter for CSV. 
 * @var
 */
$plugin_cf['news']['csv_delimiter']="#";
/**
 * Enclosure for CSV.
 * @var
 */
$plugin_cf['news']['csv_enclosure']="\"";
/**
 * Using the news module as blog system.
 * @var
 */
$plugin_cf['news']['blog']="false";
/**
 * Date format used in frontend.
 * @var
 */
$plugin_cf['news']['date_format']="d.m.Y";
/**
 * Date format used in backend.
 * Note that this format should be compatible with the datepicker format. Good choices are d.m.Y for date_format_backend and dd.mm.yyyy for datepicker_format.
 * @var
 */
$plugin_cf['news']['date_format_backend']="d.m.Y";
/**
 * Include newsticker for use in templates.
 * @var
 */
$plugin_cf['news']['template_newsticker']="false";
/**
 * Include bxslider for use in template.
 * @var
 */
$plugin_cf['news']['template_newsslider']="false";
/**
 * RSS file with full path relative to CMSimple root.
 * @var
 */
$plugin_cf['news']['rss_file'] = 'rss.php';
/**
 * Archive entries per page.
 * @var
 */
$plugin_cf['news']['pagination_backend'] = '10';
/**
 * Backend entries per page.
 * @var
 */
$plugin_cf['news']['pagination_archive'] = '10';

/**
 * Speed of newsticker reveal.
 * @var
 */
$plugin_cf['news']['newsticker_speed']="0.1";
/**
 * Display newsticker controls (Stop, Resume, Next, Previous).
 * @var
 */
$plugin_cf['news']['newsticker_controls']="true";
/**
 * Title text for newsticker.
 * @var
 */
$plugin_cf['news']['newsticker_title_text']="Latest";
/**
 * Display (effect) type (reveal or fade).
 * @var
 */
$plugin_cf['news']['newsticker_effect']="reveal";
/**
 * Time between news.
 * @var
 */
$plugin_cf['news']['newsticker_delay']="2000";
/**
 * Fade in speed.
 * @var
 */
$plugin_cf['news']['newsticker_fade_in_speed']="600";
/**
 * Fade out speed.
 * @var
 */
$plugin_cf['news']['newsticker_fade_out_speed']="300";

/**
 * Bxslider speed. Value between 1 and 5000. Small value => fast ticker.
 * @var
 */
$plugin_cf['news']['newsslider_speed']="2000";
/**
 * Pause ticker on hover.
 * @var
 */
$plugin_cf['news']['newsslider_pause_hover']="true";
/**
 * Date format for datepicker.
 * @var
 * 
 * Following conventions:
 *      d - day of month (no leading zero)
 *	    dd - day of month (two digit)
 *	    o - day of the year (no leading zeros)
 *	    oo - day of the year (three digit)
 *	    D - day name short
 *	    DD - day name long
 *	    m - month of year (no leading zero)
 *	    mm - month of year (two digit)
 *	    M - month name short
 *	    MM - month name long
 *	    y - year (two digit)
 *	    yy - year (four digit)
 *	    @ - Unix timestamp (ms since 01/01/1970)
 *	     ! - Windows ticks (100ns since 01/01/0001)
 *	    '...' - literal text
 *	    '' - single quote
 *	    anything else - literal text 
 * 
 */
$plugin_cf['news']['datepicker_format']="dd.mm.yy";
/**
 * jQuery core file. Found in news/jquery/js/.
 * @var
 */
$plugin_cf['news']['jquery_core']="jquery-1.9.1.min.js";
/**
 * jQuery UI file. Found in news/jquery/js/.
 * @var
 */
$plugin_cf['news']['jquery_ui']="jquery-ui-1.8.21.custom.min.js";
/**
 * jQuery UI CSS file. Found in news/jquery/css/.
 * @var
 */
$plugin_cf['news']['jquery_ui_css']="jquery-ui-1.8.21.custom.css";

Backend configurationBack to top

See the help texts of the options to see if your changes are valid.

Backend configuration.

UsageBack to top

Calling the pluginBack to top

For calling the plugin on some of your pages use one of the following scripts:

The function expects two parameters: The first one is a string containing a category name, an array with category names, or an empty string if all categories shall be displayed, the second parameter defines the number of entries displayed. There are two options:

news('categoryname', '-1 week'); // Shows all entries of one week ago until now.
news('categoryname', '-5 days'); // Shows all entries of the last five days.
news('categoryname', '-1 month'); // All entries of the last month.
news('categoryname', '-3 weeks'); // All entries of the last three weeks.
news('', '-13 days'); // All entries of the last 13 days in all categories.
news(array('categoryname1', 'categoryname2'), '-21 days'); // All entries of categoryname1 and categoryname2 of the last 21 days
						
news('categoryname', 5); // The last five entries, independant of their publishing dates.
news('categoryname', 11); // The last 11 entries.
news(array('categoryname1', 'categoryname2'), 3); // Three entries of the categories: categoryname1 and categoryname2

Calling the newscaseBack to top

Calling the newscase is interesting for usage within the template. For using the newscase within the template no additional configuraiton is required.

// Shows all entries of the last week.
// Only the short description of the entry is shown.
// The title of each entry references the complete news entry which is shown on the page 'News'.
newscase('News', 'categoryname', '-1 week');

The second and third parameters are known from above.

The first parameter is a stirng referencing some othe page on the site. The easiest way to get this site name is to call the site in the frontend and copy the part of the url behind the ?. Example:

www.example.de?News
www.example.de?Angebote_und_Aktionen

Take the part behind the '?' which will reference the given site.

Calling the newstickerBack to top

Calling the newsticker works using the following scripts:

The arguments are more or less the same as calling the news normally.

The newsticker does only show the publishing date, the title and the link (if given) of the entry.

Calling the newsticker in the templateBack to top

Calling the newsticker in your templates requires the configuration key template_newsticker set to 'true', either by directly editing config.php or by configuring the plugin in backend.

$plugin_cf['news']['template_newsticker']="true";

In addition the plugin call changes to:

echo newsticker('categoryname', 5, TRUE);

where the TRUE indicates the usage within a template. Make sure to wrap this code within opening and closing php tags:

<?php echo newsticker('categoryname', 5, TRUE); ?>

Calling the newsscrollerBack to top

Calling the newsscroller works using the following scripts:

The aruments are the same as for the newsticker or the news in general.

The newsscroller shows the date and the title (as link if given) only.

Calling the newsscroller in the templateBack to top

Calling the newsscroller in your templates requires the configuration key template_newsscroller set to 'true', either by directly editing config.php or by configuring the plugin in backend.

$plugin_cf['news']['template_newsscroller']="true";

In addition the plugin call changes to:

echo newsscroller('categoryname', 5, TRUE);

where the TRUE indicates the usage within a template. Make sure to wrap this code within opening and closing php tags:

<?php echo newsscroller('categoryname', 5, TRUE); ?>

Calling the newssliderBack to top

Calling the newsticker works using the following scripts:

The arguments are more or less the same as calling the news normally.

Calling the newsslider in the templateBack to top

Calling the newsslider in your templates requires only one configuration key set: template_newsslider must be set to 'true', either by directly editing config.php or by configuring the plugin in backend.

$plugin_cf['news']['template_newsslider']="true";

In addition the plugin call changes to:

echo newsslider('categoryname', 5, TRUE);

where the TRUE indicates the usage within a template. Make sure to wrap this code within opening and closing php tags:

<?php echo newsslider('categoryname', 5, TRUE); ?>

News archiveBack to top

Calling the news archive works using the following scripts:

The function expects one parameter: The category name as string. The string cannot be empty!

The news archive is supposed to get a whole CMSimple site. The archive currently only includes pagination. Set the number of entries shown per page using the configuration key pagination_archive.

As title the category name will be used.

News archive.

RSS feedBack to top

To get the RSS feed working rss.php is required. The file is included in the download and it is recommended to place the file in the CMSimple root directory. Check that the rss_file configuration key matches the path to rss.php.

RSS configurationBack to top

Go to the category configuration using the settings icon of selected category (see Backend).

RSS configuration.

Fields:

RSS feed linkBack to top

Go to the category rss using the rss icon of selected category (see Backend).

Category RSS link.

BackendBack to top

Select the plugin in your CMSimple backend. You will see some information about the plugin:

News information of installed version.

Click "Manage entries" in the toolbar.

The first thing to do is to create a category.

Create the first category.

After creating a new category click "Manage entries" again:

News backend.

Managing categoriesBack to top

NOTE: It is recommended to use a name without any whitespace or special (for example non-ascii) characters. The category name is used as file name for the CSV file storing the news and their content, so use only valid names for files.

There are several options managing the categories:

New categoriesBack to top

For creating a new category click the "New category" button. The form is the same as for creating the first category.

New category button. New category button.

Category configurationBack to top

Each category offers several configuration options. Most of them can be found here andare only important when using the RSS functionality. The configuration options left are:

Deleting a categoryBack to top

For deleting a category click the "Delete category" button. Note: All news entries in the category will be deleted, too.

Delete category button. Delete category button.
Delete category.

Managing entriesBack to top

There are several options to manage the entries of your categories:

Fields:

How about using special characters and quotiation marks within the fields?

Currently special characters and especially quotation marks can be used for the title, the description and the link title. This is accomplished using a combination of using htmlspecialchars($content, ENT_QUOTES) for saving the data to the CSV file and using html_entity_decode() for displaying the descritpion. For the description and short description the use of HTML code is ok.

Note: There can still be combinations of characters this solution does not work for!

Add newsBack to top

For adding an entry click the "Add"-Button (the green plus-symbol). If either the "Link" or "Link title" field is empty no link will be added. At the bottom of the form you can choose whether to publish the news entry immediately.

Add entry. Add entry.
Add entry.

Successfully created entry:

Successfully added entry.

Publish newsBack to top

To publish an entry there are three options:

Publish entry. Publish entry.

The publishing date will be the last editing date with option "Publish" chosen. So after editing an entry, the publishing date will be reset.

Take out newsBack to top

An entry is taken out if he is not seen publicly. So "taken out" means the opposite of "published". There are two options:

Take out entry. Take out entry.

Edit newsBack to top

Editing an entry is similar to adding a new one. For editing a video click the "Edit" button in the row of the entry. You will see the form filled with the current data. At the bottom you can choose to publish the entry.

Edit entry. Edit entry.

Delete newsBack to top

For deleting an entry click the "Delete" button in the row of the entry.

Delete entry. Delete entry.
Delete entry.

After clicking "I'm sure.":

Successfully deleted entry.

Custom stylingBack to top

Custom styling can either be done in the templates stylesheet or by modifying the plugin's stylesheet. The plugin's stylesheet is located in plugins/news/css. Delete the frontend part in the stylesheet of the plugin if you want to do custom styling in the template's stylesheet.

The frontend part of the stylesheet looks like this:

/*
 * Frontend style.
 */
/* Entry div. */
.news-entry {
	margin: 1.5em auto;
}
/* Entry's title div. */
.news-entry-title {
	font-weight: bold;
	font-size: 12pt;
	padding: 5px 0;
	margin-bottom: .5em;
	border-bottom: 1px solid #777;
}
/* Entry's date span (in title). */
.news-entry-title-date {
	float: right;
	font-style: italic;
	font-weight: normal;
	font-size: 10pt;
}
/* Entry's short description div. */
.news-entry-short {
	
}
/* Entry's description div. */
.news-entry-description {
	
}
/* Entry's link div. */
.news-entry-link {
	display: block;
}

/* News archive div. */
.news-archive {
	width: 100%;
	padding: 2%;
}
/* News archive header. */
.news-archive-header {
	font-size: 16pt;
	margin-bottom: 1em;
	font-weight: bold;
}
/* News archive footer. */
table.news-archive-footer {
	width: 100%;
}

/**
 * 	Newsticker.
 */
.newsticker-wrapper {
	height: 20px;
}

.newsticker-title {
	font-weight: bold;
	margin: 0;
	float: left;
	width: 10%;
	padding: 1% 0;
}

.newsticker-content {
	margin: 0;
	float: left;
	width: 70%;
	padding: 1% 0;
}

/* Li of the entry. */
.newsticker-wrapper .newsticker-entry {
	width: 100%;
}

/* Date of the entry. */
.newsticker-wrapper .newsticker-entry-date {
	margin-right: 1em;
}

.newsticker-wrapper .newsticker-entry-title {
	margin-right: 1em;
}

/* Link of the entry. */
.newsticker-wrapper .newsticker-entry-link {
	
}

.newsticker-wrapper .newsticker-controls {
	list-style-type: none;
	float: right;
	width: 48px;
	margin: 1% 0;
}
.newsticker-wrapper .newsticker-controls li {
	float: left;
	cursor: pointer;
	height: 16px;
	width: 16px;
	display: block;
}
.newsticker-wrapper .newsticker-controls li.newsticker-play-pause {
	background-image: url('../images/newsticker/pause.png');
}
.newsticker-wrapper .newsticker-controls li.newsticker-play-pause.over {
	background-image: url('../images/newsticker/pause.png');
}
.newsticker-wrapper .newsticker-controls li.newsticker-play-pause.down {
	background-image: url('../images/newsticker/pause.png');
}
.newsticker-wrapper .newsticker-controls li.newsticker-play-pause.paused {
	background-image: url('../images/newsticker/play.png');
}
.newsticker-wrapper .newsticker-controls li.newsticker-play-pause.paused.over {
	background-image: url('../images/newsticker/play.png');
}
.newsticker-wrapper .newsticker-controls li.newsticker-play-pause.paused.down {
	background-image: url('../images/newsticker/play.png');
}
.newsticker-wrapper .newsticker-controls li.newsticker-prev {
	background-image: url('../images/newsticker/previous.png');	
}
.newsticker-wrapper .newsticker-controls li.newsticker-prev.over {
	background-image: url('../images/newsticker/previous.png');	
}
.newsticker-wrapper .newsticker-controls li.newsticker-prev.down {
	background-image: url('../images/newsticker/previous.png');		
}
.newsticker-wrapper .newsticker-controls li.newsticker-next {
	background-image: url('../images/newsticker/next.png');	
}
.newsticker-wrapper .newsticker-controls li.newsticker-next.over {
	background-image: url('../images/newsticker/next.png');	
}
.newsticker-wrapper .newsticker-controls li.newsticker-next.down {	
	background-image: url('../images/newsticker/next.png');	
}

/* Newsslider driver. */
/* Main window containing the ul (not the controls and pager). */
.bx-window {
	
}

/* Main li with entry content. */
.newsslider-entry, .bx-window li {
	padding: 10px;
}

.newsslider-entry-title {
	font-weight: bold;
	font-size: 12pt;
}

.newsslider-entry-title-date {
	font-size: 10pt;
	font-style: italic;
	font-weight: normal;
	margin-left: 2em;
}

.newsslider-entry-description {
	
}

.newsslider-entry-date {
	
}

/**
 * 	Blockquotes.
 */
.blockquotes-entry {
	
}

.blockquotes-entry-title {
	font-size: 18px;
}

.blockquotes-entry-short p {
	font-size: 14px;
}

.blockquotes-entry-date {
	
}

/**
 * Newsscroller.
 */
.newsscroller-container { 
    width: 400px; 
    height: 27px; 
    margin: 0; 
    padding: 0;
    overflow: hidden; 
}
.newsscroller-mask {
    position: relative;
    left: 10px;
    top: 8px;
    width: 380px;
    overflow: hidden;
}
ul.newsscroller {
    position: relative;
    left: 380px;
    list-style-type: none;
    margin: 0;
    padding: 0;

}
ul.newsscroller li {
    float: left;
    margin: 0;
    padding: 0;
}
ul.newsscroller li a {
    white-space: nowrap;
    padding: 0;
    margin: 0 50px 0 0;
} 
ul.newsscroller li span {
    margin: 0 10px 0 0;
}

Classes:

IconsBack to top

All icons used in backend of this plugin are part of the spirit20 icons set (licensed under GPL). See here for the complete set. Thanks to Dale Morrell for this great set of icons!

The icons used for the newsticker controls are part of the splashyfish icons set (free for comemrcial use). See here for the complete set. Thanks to Dat Nguyen for this great set, too!

ChangelogBack to top

Version 1.1Back to top

Version 1.1.1

Version 1.1.0

Beta 17.

Beta 16.

Beta 15.

Beta 14.

Beta 13.

Beta 12.

Beta 11.

Beta 9 and 10.

Beta 8.

Up to beta 7.

LicenseBack to top

The plugin's licenseBack to top

Copyright 2012, 2013 David Stutz

The plugin is published under the GNU Public License Version 3. For more information see: GNU Licenses

The plugin is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The plugin is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

jQueryBack to top

See here for license information.

NewstickerBack to top

See here for license information.

NewsscrollerBack to top

See here for license information.

NewstickerBack to top

See here for license information.