= sfKsnNews plug-in = == Author == Serg Kalachev (a.k.a. `ksn135`) CIO, MSS GROUP (http://www.mss-group.ru/) == License == Copyright (c) 2007 Serg N. Kalachev <serg@kalachev.ru> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. == Overview == The `sfKsnNewsPlugin` is a symfony plugin that provides complete solutions for building news publishing system. Main features includes: * multilanguage support (the same news item in different languages) * frontend (AJAX or form-based) administration * backend administration * lastest news block component and helper * autogeneration of news item annotation * fully customizable to suit your needs * news item files managment * nested news categories * RSS feed == Prerequisites == * Install sfGuardPlugin to use author field and frontend administration (don't forget to secure your frontend) {{{ symfony plugin-install http://plugins.symfony-project.com/sfGuardPlugin }}} * Install sfPropelFileStorage to use files storage {{{ svn co http://svn.symfony-project.com/plugins/sfPropelFileStoragePlugin/ }}} * Install sfFeed2Plugin to use rss feed {{{ symfony plugin-install http://plugins.symfony-project.com/sfFeed2Plugin }}} * Download and install TinyMCE 2.1.2 stable from http://tinymce.moxiecode.com/download.php == Installation == * Install the plugin {{{ symfony plugin-install http://plugins.symfony-project.com/sfKsnNewsPlugin }}} * Rebuild your model {{{ symfony propel-build-all }}} * Load default fixtures (optional - it creates sample news items and categories) {{{ symfony propel-load-data frontend }}} * Enable one or more modules in your `settings.yml` (optional) * For your frontend application: sfKsnNews * For your backend application: sfKsnNewsItem, sfKsnNewsCategory {{{ all: .settings: enabled_modules: [default, sfKsnNewsItem, sfKsnNewsCategory, sfKsnNews] }}} * Clear you cache {{{ symfony cc }}} == Configuration == === Multilanguage === * There are two different behavior of plugin controlled by multilanguage_enabled option * If multilanguage is ENABLED and in settings.yml i18n option is also enabled then ONE news item has SEVERAL translation. For example, you creating project for some company that has representatives in several countries and you need publish news in several languages. Just add as many languages as you want to app.yml. That's all! {{{ all: sf_ksn_news_plugin: multilanguage: enabled: on cultures: # an array, at least one element must be specified en: English # first culture is default culture ru: Russian fr: French de: German }}} * If multilanguage is DISABLED or i18n option is disabled then ONE news item has ONE translation. For example, you creating some generic local project. And you simply don't need all that i18n features. The first culture will be your default. Just set enabled option to off. {{{ all: sf_ksn_news_plugin: multilanguage: enabled: off cultures: fr: French }}} === Routing === * Routes are automatically registered by the plugin if the module `sfKsnNews` is enabled unless you defined `sf_ksn_news_plugin_routes_register` to false * You can change prefix of routes {{{ all: sf_ksn_news_plugin: routes_prefix: /nouvelle }}} * Plugin automaticaly prefix routes with /:sf_culture if multilanguage is enabled === Profile === * You must define in app.yml class and field of assosiated sfGuardUser profile object {{{ all: sf_guard_plugin: profile_class: Employee profile_field_name: user_id }}} * Also you must specify function to get name and email from profile {{{ all: sf_ksn_news_plugin: profile_name: __toString # function to call to get user name profile_email: getEmail # function to call to get user email }}} * Optionaly you can select profile field. Query results will be ordered by this field. {{{ all: sf_ksn_news_plugin: profile_order_by: last_name # field name used to order by records (by default empty) }}} === RSS feed === * The default setting, don't forget to change it to suit your needs {{{ all: sf_ksn_news_plugin: rss_feed: enabled: on # require sfFeed2Plugin format: atom1 # use one of the following formats: atom1, rss10, rss091, rss201 title: sfKsnNewsPlugin feed # RSS title description: Lastest news # description link: http://www.mss-group.com/ # feed link author: Serg N. Kalachev # feed autor email: serg@kalachev.ru # feed autor's email route: '@sf_ksn_news_item_show' # feed item route }}} === Behavior configuration === {{{ all: sf_ksn_news_plugin: use_files: on # use files (require sfPropelFileStoragePlugin) use_author: on # use author (require sfGuardPlugin) use_categories: on # use categories use_annotation: on # use annotation }}} === Auto annotation === * If enabled and user enter empty annotation it will be autogenerated from striped body {{{ all: sf_ksn_news_plugin: auto_annotation: enabled: on # autogenerate annotation based on striped body length: 100 # maximum allowed length of autogenerated annotation }}} === Frontend administration === * To use frontend administration you must secure your application first * Only authenticated user with correct credentials can use it. * Several options avaiable: {{{ all: sf_ksn_news_plugin: frontend_admin: on # enable frontend administration function: add, edit, delete frontend_admin_ajax: off # AJAX administration mode (Javascript, Prototype 1.5.0, Scriptaculous 1.7.0 and TinyMCE 2.1.2 required) frontend_add_category: off # allow rename and append new top-level categories, if off only select from list frontend_credentials: news: append: news_item_add # user can append news items modify: news_item_chg # user can modify news items delete: news_item_del # user can delete news items category: news_item_cat # user can add new categories }}} * If frontend_admin_ajax is ON then system allow user inplace editing ALL elements of news item by ONE mouse click, including HTML WYSIWYG editor for news content using TinyMCE control. * To customize TinyMCE control behavior or/and apperance change initialization script or use your own {{{ all: sf_ksn_news_plugin: tiny_mce_init_js: /sfKsnNewsPlugin/js/mce_init # TinyMCE initialization script }}} * If frontend_add_category is OFF user can only select category from drop-down list. * If frontend_add_category is ON user also can append new top-level category and rename existing one. * If frontend_admin_ajax is OFF: ordinal form-based administartion will be used. == Using sfKsnNews module in your frontend application == === Lastest news block === * In your template call ksn_news_include_lastest_news_block() from provided helper {{{ use_helper( 'KsnNews' ); ksn_news_include_lastest_news_block(); }}} * Or in your layout.php you can include news component {{{ include_component('sfKsnNews', 'lastestNewsBlock' ); }}} * You can change number of lastest news items to display (i.e. desired value is 10) * by changing default value in app.yml {{{ all: sf_ksn_news_plugin: number_of_items: 10 }}} * by setting first parameter of helper function {{{ use_helper( 'KsnNews' ); ksn_news_include_lastest_news_block( 10 ); }}} * You can filter lastest news items * by adding custom Criteria {{{ use_helper( 'KsnNews' ); $criteria = new Criteria(); $criteria->add( sfKsnNewsItem::CATEGORY_ID, array( 1, 3, 5), Criteria::IN ); ksn_news_include_lastest_news_block( 10, $criteria); }}} * by extending via sfMixer methods of sfKsnNewsLib class {{{ function filterCategories( &$criteria ) { $criteria->add( sfKsnNewsItem::CATEGORY_ID, array( 1, 3, 5), Criteria::IN ); } sfMixer::register('sfKsnNewsLib:createCriteria', 'filterCategories' ); }}} === RSS feed === * Optionally you can add in layout.php in head section to auto-discover RSS feed in modern browsers {{{ <?php echo auto_discovery_link_tag('rss', '@sf_ksn_news_rss', array('title' => __('RSS Feed'))) ?> }}} * Optionaly you can output RSS logo with link to your RSS feed {{{ echo ksn_news_output_rss_link(); }}} == Using sfKsnNewsItem and sfKsnNewsCategory modules in your backend application == * Note: if you change any plugin setting you MUST manualy clear cache, because generator.yml and edit.yml files AUTOgenerated based on current settings in app.yml == Quick start guide for sandbox == * Before we start you must complete Prerequisites and Installation steps. * Create file /path_to_sandbox/apps/frontend/modules/default/templates/indexSuccess.php {{{ <?php use_helper( 'KsnNews' ); echo ksn_news_output_rss_link(); ksn_news_include_lastest_news_block(); ?> }}} * Enable the following modules: `sfGuardAuth`, `sfKsnNews`, `sfPropelFileStorage` and change the default login and secure modules and enable i18n in `settings.yml`: {{{ all: login_module: sfGuardAuth login_action: signin secure_module: sfGuardAuth secure_action: secure .settings: enabled_modules: [default, sfGuardAuth, sfKsnNews, sfPropelFileStorage] i18n: on }}} * Change the parent class in `myUser.class.php` {{{ class myUser extends sfGuardSecurityUser { } }}} * Secure your entire application in `security.yml` {{{ default: is_secure: on }}} * Create user profile in schema.yml {{{ propel: sf_guard_user_profile: _attributes: { phpName: sfGuardUserProfile } id: user_id: { type: integer, foreignTable: sf_guard_user, foreignReference: id, required: true, onDelete: cascade } first_name: varchar(20) last_name: varchar(20) email: varchar(40) birthday: date }}} * Rebuild your model and load default fixtures {{{ symfony propel-build-all-load frontend }}} * Add profile record assosiated with sfGuardUser into newly created table {{{ INSERT INTO sf_guard_user_profile VALUES ( NULL, 1, 'Serg', 'Kalachev', 'serg@kalachev.ru', '1975-02-25' ); }}} * Append method `__toString()` to class sfGuardUserProfile {{{ public function __toString() { return $this->getFirstName().' '.$this->getLastName(); } }}} * Clear your cache {{{ symfony cc }}} * Login as admin (password: admin) * Now you can play around with options in app.yml. Note: DON'T FORGET TO CLEAR CACHE EACH TIME YOU CHANGE SETTINGS. == Design, hmm... == * Create your own or modify existing CSS to suit you need {{{ all: sf_ksn_news_plugin: css_file: /sfKsnNewsPlugin/css/sf_ksn_news_plugin }}} * Feel free to send me updated CSS for inclusion in future relases == Features requests == Please, submit any feedback or features requests on the [http://www.symfony-project.org/forum/index.php/t/9946/ forum] == Active tickets == [[TicketQuery(component=sfKsnNewsPlugin&status!=closed)]] == Changelog == === 2007-11-24 | 0.1.0 === * Serg.Kalachev: Initial public release === 2007-11-26 | 0.1.1 === * Serg.Kalachev: Fixed partial _body.php === 2007-11-27 | 0.1.2 === * Serg.Kalachev: Fixed validation file