Youtube Gallery Plugin for CMSimple

Introduction Back to top

This plugin is designed to simplify the creation, management and frontend presentation of youtube video galleries. The backend allows the creation of different galleries, adding videos just with their youtube id, title, description and the position in the gallery.

Version Back to top

This is currently version 1.3.0 of the plugin, released 13th March 2014.

Requiremeqnts Back to top

PHP Back to top

Update: A CSV helper is used. The helper only uses fgetcsv() and fputcsv(). SO a PHP version 5 or higher is required.

Update: Found an alternative for using str_getcsv(), so for PHP versions supporting str_getcsv() this function is still used, for those not supporting str_getcsv() the alternative function is used. So theoretical the plugin can be used with PHP 5 or higher

Note: The alternative function is not tested sufficiently. Use with caution.

Currently the plugin works using fputcsv(), fgetcsv() and str_getcsv(), so a PHP version 5.3.0 or higher is required. I am working on another solution allowing it to use the plugin with PHP 5 or higher.

Supported CMSimple versions Back to top

CMSimple XH 1.5 or higher (recommended)
CMSimple XH 1.4.2
CMSimple XH 1.1.4
CMSimple LE 3.4(.1) (Pluginloader needed, see installation guide below)
CMSimple 3.3 (Pluginloader needed, see installation guide below)

Installation Back to top

CMSimple XH Back to top

Download the plugin.
In the plugins folder, create a subfolder called youtube.
Extract the files into the youtube folder.
The plugin stores the galleries in CSV files in /content/plugins/youtube. The folder is created automatically (mostly).This folder needs write and read permissions. The plugin does check this permissions and tries to alter this permissions if needed.
Go into backend and see if the installation is detected correctly.

CMSimple 3.3 and CMSimple LE Back to top

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

Download a working Pluginloader, see CMSimple Wiki: Pluginloader or the CMSimple Forum to get the current version.
Create a folder named plugins in the CMSimple root directory.
Extract the pluginloader into this directory. You will have plugins/index.php and plugins/pluginloader.
Edit cmsimple/config.php and add:

$cf['plugins']['folder'] = "plugins";

Go in your CMSimple backend, choose 'Settings' and edit configuration:

Look for the plugins_folder configuration key:

In the plugins folder, create a subfolder called youtube.
Extract the files into the youtube folder.

Upgrading Back to top

1.0.x to 1.1.x Back to top

The data (CSV with videos) should be compatible between this version. Do not overwrite plugins/youtube/list.csv and your videos will be kept available.

1.1.x to 1.2.x Back to top

Between these versions there were made many changes. Instead of using one list of youtube videos 1.2.x supports the creation of different galleries of videos. The format of the CSV files (list.csv for 1.1.x and the gallery CSV files in 1.2.x) is the same, but the gallery CSV files of 1.2.x are store by default in content/plugins/youtube/galleryname.csv. So for updating it should work by copying list.csv into content/plugins/youtube/list.csv (or into the directory specified by the filepath option in the configuration). Another small difference is the internal used and in 1.2.x shown id (not the youtube id), 1.2.x uses a current timestamp, whereas 1.1.x uses an own routine for defining a new id, so after updating to 1.2.x the dates shown in backend of the old videos will not make much sense, but that should not be any problem!

1.2.x to 1.3.x Back to top

The csv scheme changed slightly: The width and height of each video are stored. So make sure you add a width and height to each video. If not the plugin will choose a default width and height which is configurable in the configuration: default_video_width and default_video_height.

Configuration Back to top

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

Configuration options Back to top

csv_filepath: The path where to store the galleries CSV files, relative to CMSimple root.
csv_delimiter: The delimiter used between cells in all CSV files.
csv_enclosure: The enclosure used in all CSV files. Must be a single ASCII character. See here for a list with all ASCII characters.

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

date_format: The date format for the backend. It is a date format like date() expects it, so see the manual.
video_default_width: The default width of a video. This is used if no width is found (for example when using videos from previous versions). Unsigned integer.

The configuration file Back to top

/** 
* Filepath storing CSV containing videos.
* @warning NOTE: Without '/' at the end! 
* @var
*/
$plugin_cf['youtube']['csv_filepath'] = "content/plugins/youtube";
/** 
* Delimiter for CSV. 
* @var
*/
$plugin_cf['youtube']['csv_delimiter'] = "#";
/**
* Enclosure for CSV.
* @var
*/
$plugin_cf['youtube']['csv_enclosure'] = "\"";
/**
* Date format used in backend.
* @var
*/
$plugin_cf['youtube']['date_format'] = "d.m.Y";
/**
* Default width of a video.
* @var
*/
$plugin_cf['youtube']['video_default_width'] = "420";
/**
* Default height of a video.
* @var
*/
$plugin_cf['youtube']['video_default_height'] = "315";

Backend configuration Back to top

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

Usage Back to top

Getting StartedCalling the plugin Back to top

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

CMSimple scripting: #CMSimple $o .= youtube('galleryname'); #
New CMSimple_XH scripting: {{{PLUGIN:youtube('galleryname');}}}

The function expects one parameter: A string defining the gallery to show. The string must be the same as the gallery name in backend.

Backend Back to top

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

Youtube information of installed version.

Click "Manage galleries" in the toolbar.

The first thing to do is to create a gallery.

Managing galleries Back to top

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

There are several options managing the galleries:

Create a new gallery.
Remove a gallery.

New galleries Back to top

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

Deleting a gallery Back to top

For deleting a gallery click the "Remove gallery" link when the wished gallery is selected. You will be asked if you are sure you want to delete the gallery. If there are still videos in the gallery they will be deleted, too.

Managing videos Back to top

There are several options to manage the videos in a gallery:

Create a new video.
Edit a video.
Delete a video.

Fields:

Youtube ID: The Youtube ID, see "How to get the Youtube ID?"".
Position: The positioning number, defining the position of the video within the gallery.
Title: The title of the entry.
Description: The body of the entry.

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. So the conclusion: the title can not be filled with HTML code. For the description the use of HTML code is ok.

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

Adding a new video Back to top

For adding a new video click the "Add"-Button (the green plus-symbol). A title and a Youtube ID is required, the description and position of the video is optional, if no position is given the order of the video is dependant on the CSV file the videos are saved in. If no description is given the description-div will not be printed.

How to get the Youtube ID?Back to top

Go to Youtube and select a video:

Successfully added the video:

Editing a video Back to top

Editing a video is similar to adding a new one. For editing a video click the "Edit"-Button in the row of the video. You will see the form filled with the current data.

Deleting a video Back to top

For deleting a video click the "Delete"-Button in the row of the video. You will be asked if you are sure you want to delete the video:

After clicking "I'm sure.":

Custom styling Back 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/youtube/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.
 */

/* The title div. */
.youtube-title {
	margin: 1em auto;
	border-bottom: 1px solid #777;
	font-size: 18pt;
	font-weight: bold;
	padding: 10px 0;
}

/* The video div. */
.youtube-video {
	margin: 1em auto;
}

/* The description div. */
.youtube-description {
	border: 1px solid #777;
	padding: 10px;
	margin: 1em 0;
}

Classes:

youtube-title: It is the class of the title div of each video.
youtube-video: The video div class.
youtube-description: The description div class.

Icons Back to top

All icons used in the 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!

Notes Back to top

The plugin was tested, but there may still be bugs.
If you are using the plugin: Support the development by making bug reports and giving ideas how to improve the plugin.
As platform you can use the SourceForge project's page: SourceForge project

David Stutz
davidstutz@web.de

Changelog Back to top

Version 1.3 Back to top

Beta 5.

Update to support CMSimple XH 1.6.x.

Up to Beta 4.

Bug fixes, see https://sourceforge.net/p/cmsimpleyoutube/discussion/1774240/thread/1969f728/.
Video description should support links and special characters.

Beta 1.

Get rid of str_getcsv().
Migrated from functional programming to object-oriented programming.
Minor changes concerning HTML entities and special chars.
Integrated help on some pages.
Added version.nfo file.
Added configurable width and height fields for all videos.

License Back to top

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.