DokuWiki

You've loaded an old revision of the document! If you save it, you will create a new version with this data.

====== anewssystem Plugin ======

---- plugin ----
description: Simple News system to create news articles and preview them or provide the News tags within a little cloud.
author     : Taggic 
email      : Taggic@t-online.de
type       : syntax
lastupdate : 2012-10-17
compatible : rincewind, angua
depends    : 
conflicts  : 
similar    : tips:newssystem
tags       : NEWS, newssystem, newspaper
screenshot_img: http://img838.imageshack.us/img838/6777/anssexmpl.gif

downloadurl: https://github.com/Taggic/anewssystem/archives/master
bugtracker : http://www.fristercons.de/fcon/doku.php?id=news:issues
sourcerepo : https://github.com/Taggic/IssueTracker/
donationurl: 
----

\\ 
:!: The version 2012-07-17 modified the meaning of parameter prev_length. Now it is a threshold for the max previewed words. Please consider to change global config and syntax lines accordingly. \\ 
\\ 
:!: The version 2012-05-09 introduced tags. Formerly created news does not have such and might be not visible by given date-validity \\ due to tags used as filter. To make them visible edit the news article and add "''%%  *  tags: tag1, tag2, tag3%%''" into the line after author entry. \\ 
\\
:!: Take care that since version 2012-03-29 you need a modification of formerly created news articles. \\ Open your //newsdata// page with DokuWiki Editor and replace all %%----%% by a level 1 headline. The headline text must be identical to the //**head**// content of your news article. \\

__**Changes**__ \\ 
{{rss>http://github.com/feeds/Taggic/commits/anewssystem/master date}}

===== Overview =====
The plugin delivers you three major functions (write news, news flash, read all). You are supported by a simple form to write the article. There you can also specify when the news will be visible and until when. Beside writing news articles you can put a NEWS flash box wherever you want (usually on the start page of your wiki). It will provide a preview of the news you want to tell the world linked to the complete content. Another function is to read the complete set of articles you have written. The news data will be stored into one text file, which can be edited by DokuWiki implemented editor as any other page. The previews also as the complete article are allowed to contain DokuWiki syntax. This will be rendered properly.

* Easily write news articles supported by a form
  * Define publishing and perishing date of the article
  * Get a NEWS flash box where the previews are linked to the articles
  * Outdated news will be suppressed on preview and all news page
  * Preview length and item quantity can be easily modified case by case
  * Use DokuWiki syntax within the article as usual
  * Global and local parameters also as css support provide you control and customizability
  * DokuWiki ACL feature used

==== Installation ====
Install the plugin using the [[Doku>plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. \\ 
Refer to [[Doku>plugin_installation_instructions|DW Installation instructions]] to read more about.

- create a a page news:news and put there the following syntax, which will bring all elements onto one page <code txt news.txt>====== News ======
~~NOCACHE~~
**[ [[news:allnewsdata|all news]] | [[news:news|write news]] | [[news:newsdata?do=edit|edit news]] ]**

{{anss>flash200,40%,right,10}}
{{anss>author}} 
 \\ 
 \\ 
{{anss>allnews}}
</code>
  - create a page news:newsdata and enter there a space or dot sign (filled with articles by using Author Interface)
  - create a page news:allnewsdata containing the following content <code txt allnewsdata.txt>====== Latest NEWS articles ======
~~NOCACHE~~
{{anss>allnews}}</code>

==== The Author Interface ====
{{ http://img403.imageshack.us/img403/251/writenews.gif?nolink|Author Interface}}Number one is a user interface to write News articles, link them and define a validity period.

On top of it a unique anchor will be calculated to link the previewed content properly with the whole article.

Define a Headline and the content of the news article you want to create. You may use standard DokuWiki Syntax within the article, it will be recognized and handled accordingly. The link is automatically created but for what reason ever you may want to change it. Take care that you properly set the anchor or the link will jump to the top of the referenced page. There is a small counter on top of the text input area to give you the quantity of entered words.

Publishing date is by standard the date when you write the article. If you leave this unchanged the new will be visible after pushing the Publish button. The perishing date is the day where the article will disapear from the system (not deleted but not visible for the user anymore). The perishing date is calculated based on global settings in Configuration Manager but you can modify it here towards the special needs you may have on a special NEWS post.

Please take care that all your authors (but only these) have write permission to the newsdata page. Users without proper permission cannot store news to your system.

==== News Output ====
There are 3 output variants available. One is the //**News Flash**// box you can place wherever you want within your page syntax. Styling can be customized by the style.css file. The output is defined by the syntax parameters for width, quantity of articles and count of words to be previewed.

Another method is to display all current valid News Posts completely. The validity is defined by start and stop date. That delivers you the possibility to write news articles which will be displayed in the future, e.g. for Christmas, New Year, Easter or any other date you may chose.

If you have write permission on that page where //**News Flash**// or //**All News**// syntax was placed you will find two little icons below each news article. If you click on these icons you can either edit or delete the related news post. The symbol will change from black & white picture into a colored image if you hover the mouse over it. A click on the cross will immediately delete the related news record. There is no undo function so please use this function wisely. By a click on the blue feather the section edit of the related news record will be opened.

The third method is a page as usual within Dokuwiki containing all news as defined by the template divided into sections, where the Headline is used as section headline. To edit there you may chose the standard DokuWiki Editor itself with section edit.

The news cloud provides you a possibility to present your news tags as links in a cloud as you may know it from the [[doku>plugin:cloud|cloud plugin]]. There is no dependency to install the cloud plugin for this feature. It also delivers you various options to style your cloud either by your own CSS by syntax class option and/or by styling parameters within the syntax line. The News Cloud will display all tags where you have current news articles (not beyond the perishing date). A click on such a tag-link of the News Cloud will open the configured "All News" page but overrule the potentially tag setting of the syntax line to show the current, wanted articles.

==== News Thumbshots ====
{{ http://img803.imageshack.us/img803/3550/newsthumbshots.gif}}Many of the website needs to upload the thumbshot or screenshot manually of your website. So many of them try to use the third party tool or addons to. Nowadays a lot of webmasters are looking for a website snapshot tool in order to make data presentation more attractive to their visitors.

The News Thumbshots are realized by integration of related online Service Providers. There you can choose from variety of the online services, fee-less or highly professional with costs. I have checked the following for you but it is not limited and may change over time (list is not under regular care and there are many more available):

* http://www.thumbshots.de
  * http://images.websnapr.com
  * http://www.artviper.net
  * http://image.thumber.de
  * http://fadeout.de

Most of them are fee of charge but need a registration of your page. The plugin does accept just one online Thumbshot provider. However, it is necessary to open the Configuration Manager and enter the related link as described on the home page (or see below).

The upper mentioned 4 would lead into following configuration values. The //**%s**// parameter is mandatory as is. The plugin use this place-holder to extend the provider link by your News Page link (or whatever page you have linked). It is telling the provider from what page the thumb-shot should be taken.

<code>
http://www.thumbshots.de/cgi-bin/show.cgi?url=%s
http://images.websnapr.com/?size=s&nocache=81&url=%s
http://www.artviper.net/screenshots/screener.php?sdx=1024&sdy=768&w=120&h=80&q=100&url=%s
http://image.thumber.de/?size=XXL&amp;url=%s
http://fadeout.de/thumbshot-pro/?scale=3&url=%s&effect=2
</code>

==== Optional Configuration ==== 
Probably you may want to change something the please have a look into the Configuration Manager for the plugin. There are a few simple and self-explaining parameters. Further you may adapt the text used for controls and/or add further language resource files. How to do so is described within the [[Doku>start|DokuWiki.org]]. To modify the look and feel please check the style.css file. There are many definitions offered for modification. Please refer to css documentation and communities in the event of related questions.

====== Plugin Configuration  ====== 
As most of the plugins this can be configured basically by use of DokuWiki [[Doku>plugin:config|Configuration Manager]]. The news System does provide following parameter:
^ Parameter ^ Effect |
| d_format  | Define the date format (e.g. Y-m-d) |
| news_datafile  | Set the path to the namespace:newsdata file \\ defines where the news records are stored  |
| prev_length  | Define the quantity of previewed words per news post  |
| newsflash_link  | switch on to turn the News preview box headline into a link to News page  |
| soapp  | soapp = show one article per page (instead of current all news)  |
| convert  | insert the link to the online __[[http://www.fristercons.de/fcon/doku.php?id=news:descr#news_thumbshots|Thumbshot]]__ provider to enable preview pictures on NewsFlash box (empty the field to switch off this feature)  |
===== Syntax =====
Simply place the following syntax into the page markup of a page:

=== Write new News === 
Place the following syntax on a page to get the News author interface. The interface will be visible for all (as long as the namespace/page is not ruled otherwise). The user cannot save news articles as long as the user has no write permission to the //news:newsdata// page. The controls depending on the newstemplate definition.
<code>{{anss>author}}</code>

=== Syntax for News preview ===
Put the following syntax on a page where you want to show a preview of latest news to the visitors of your wiki. It will use the settings of config and css.
<code>{{anss>flash}}</code>

Some use cases may need a different preview length, box width, etc. but you want to keep the global settings ? You can modify something by using parameters. The parameters are expected on a dedicated position. The following table explaining syntax and behavior:

^Parameter position^Example^Description^
|1|%%{{anss>flash%% **200**%%}}%%|The content of the article will be previewed by 200 words, independently of the global setting in configuration manager.|
|2|%%{{anss>flash%%**,40%**%%}}%%|The box width will be 40% of the page width. Pixel Width definitions (px) and other valid CSS width expressions are allowed. \\ (:!: Take care of the colon, it is necessary due to it defines parameter position and therewith the relation !)|
|3|%%{{anss>flash%%**,**300px**,right**%%}}%%|This defines the text flow around the box, means the box can be left or right sided. Take care that float does make sense only if you have a width different to 100% of the page width.|
|4|%%{{anss>flash%%**,,,10**%%}}%%|Usually the quantity of preview items is defined by the start and stop dates you providing during the NEWS edit based on the global settings or modified by yourself. However it might be necessary to further shrink the output. The 4<sup>th</sup> parameter defines how many news items to be displayed.|
|  5  |%%{{anss>flash%%**,,,,tag**%%}}%%|Multiple tags are not to be separated (must not be separated by comma). Tags are used as positive matching filters for the output. That means if one of the given tags does match the tags of an article the article will be shown (if date is valid). If no tags are given all date-valid news will be displayed.|
| |%%{{anss>flash200,40%,right,10}}%%|Of course you can do a mixture of all these settings as long as you keep the parameter position in mind|

=== Syntax for Read News ===
Put the following syntax on a page where you want to show the complete articles of latest news to the visitors of your wiki. The articles are linked with related previews.
<code>{{anss>allnews}}</code>

^Parameter position^Example^Description^
|  1  |%%{{anss>allnews%%**,tag**%%}}%%|Multiple tags are not to be separated (must not be separated by comma). Tags are used as positive matching filters for the output. That means if one of the given tags does match the tags of an article the article will be shown (if date is valid). If no tags are given all date-valid news will be displayed.|

=== Syntax for Archive List ===
Put the following syntax on a page where you want to show an archive list of all news by date and headline.
<code>{{anss>archive}}</code>

^Parameter position^Example^Description^
|  1  |%%{{anss>archive%%**,tag**%%}}%%|Multiple tags are not to be separated (must not be separated by comma). Tags are used as positive matching filters for the output. That means if one of the given tags does match the tags of an article the article will be shown. If no tags are given all news will be displayed.|

=== Syntax for News Cloud ===
Put the following syntax on a page where you want to show a cloud of tagged news articles. There are multiple options to style the cloud by CSS and syntax. Please read the table below carefully to get the whole set of style options.
<code>{{anss>cloud [Tag_Alignment] [Text_Transformation] [Cloud_Float] [NewsCloud_user_style_class]}}</code>

Additionally you can add ''newsclouddiv'' followed by a number greater than 1 as parameter to apply your own CSS settings on the NewsCloud div.
===== Examples/Usage =====

An Example can be found here: [[http://www.fristercons.de/fcon/doku.php?id=news:news|Live Example]]

===== Development ===== 
Each valuable help is welcome.

^  Date   ^ Changes  ^
| **2012-12-08** | Extension of Archive and Editor functionality |
| 2012-10-17 | **New Feature:** \\ [[http://www.fristercons.de/fcon/doku.php?issuetracker:issuelist?do=showcaselink&showid=140&project=fcon_project|#140 All News: Headlines and links]] \\ [[http://www.fristercons.de/fcon/doku.php?issuetracker:issuelist?do=showcaselink&showid=139&project=fcon_project|#139 All News Archive: it would be nice to break down entries by month or something]] \\ [[http://www.fristercons.de/fcon/doku.php?issuetracker:issuelist?do=showcaselink&showid=137&project=fcon_project|#137 SOAPP should provide a back link next to Archive link]] \\ \\ **BugFix:** \\ [[http://www.fristercons.de/fcon/doku.php?issuetracker:issuelist?do=showcaselink&showid=138&project=fcon_project|#138 make link title 'News Archive' modifiable]]   |
| 2012-10-10 | **New Features:** \\ [[http://www.fristercons.de/fcon/doku.php?issuetracker:issuelist&do=showcaselink&showid=131&project=fcon_project|(FR #131) news flash posts should link to an individual story page incl link back to the News Flash]] \\ [[http://www.fristercons.de/fcon/doku.php?issuetracker:issuelist&do=showcaselink&showid=130&project=fcon_project|(FR #130) Archives List page]] \\ \\ **BugFixes:** \\ [[http://www.fristercons.de/fcon/doku.php?issuetracker:issuelist&do=showcaselink&showid=129&project=fcon_project|(BF #129) NewsFlash link does not refer to the anchored title at All News]] \\ [[http://www.fristercons.de/fcon/doku.php?issuetracker:issuelist&do=showcaselink&showid=128&project=fcon_project|(BF #128) allnews,tag call always gives me unfiltered output of all news.]] \\     |
| 2012-08-21  | **New Feature:** \\ - News Flash: article links show a page Thumbshot on mouse over   | 
| 2012-08-06  | **BugFix:** \\ - Bugfix on allnews option  | 
| 2012-08-04  | **New Features:** \\ - NewsCloud: provids you the possibility to show a Tag-Cloud of your news. \\ - Localization: This version contains an Italian translation. Many thanks to Diego for his efforts. \\ \\ **BugFix:** \\ [[http://www.fristercons.de/fcon/doku.php?id=issuetracker:issuelist&do=showcaselink&showid=117&project=fcon_project|(FR #117) Pictures disappear in NewsFlash box ]] |
| 2011-07-17  | **BugFix:** \\ [[http://www.fristercons.de/fcon/doku.php?id=issuetracker:issuelist?do=showcaselink&showid=106&project=fcon_project|(FR #106) flash parameter doesn't change size of number of characters, always shows full text]] \\ Attention: preview_length parameter changed meaning from characters to words !   |
| 2011-05-09  | **New Features:** \\ - tags to filter output introduced \\ - red colored length info if global defined preview length will be exceed on Write News GUI  |
| 2011-03-29  | - minor BugFix: suppress anchor ID on GUI according configuration  |
| 2012-03-29  | [[http://www.fristercons.de/fcon/doku.php?id=issuetracker:issuelist?do=showcaselink&showid=83&project=fcon_project|(FR #83)]] \\ - News saved as sections \\ - News Edit and delete function for users with write permission on All News overview \\ [[http://www.fristercons.de/fcon/doku.php?id=issuetracker:issuelist?do=showcaselink&showid=82&project=fcon_project|(FR #82)]] \\ - make Headline "News Flash" and Link configurable \\ [[http://www.fristercons.de/fcon/doku.php?id=issuetracker:issuelist?do=showcaselink&showid=81&project=fcon_project|(FR #81)]] \\ - hide news ID on GUI (config)  |
| 2011-03-25  | - author can be included __[[http://www.fristercons.de/fcon/doku.php?id=issuetracker:issuelist?do=showcaselink&showid=80&project=fcon_project|(Feature Request #80)]]__ \\ - correction for list handling __[[http://www.fristercons.de/fcon/doku.php?id=news:descr#FAQ|(see also FAQ]])__  |
| 2011-03-21  | - Modification: preview output changed from list to div for improved styling possibility \\ - BugFix: closing form tag  |
| 2011-12-07  | - BugFix: Links not retrieved correctly -> wrong links in News flash  |
| 2011-12-02  | - Initial release  |

===== Version/Requirements =====
The plugin was tested with DW 2011-05-25 "Rincewind" and also with related on the Stick version. \\ 
Our standard browser is Internet Explorer 9 due to majority of users of our customers intranet installation are using this. \\ 
Of course, that is no guarantee that it works for all environmental configuration.

==== Potential for improvements ====

Probably interesting questions we could imagine:
  * How to combine the NEWS System with a news feed ?
  * Is there a way to put a picture to the news preview ? // » YES, just use the DokuWiki syntax for media links//
  * Is there a guide describing how to style the output of the plugin ?

If you are interested into these or have whishes for other improvements then please register to our wiki and create a request at related __[[http://www.fristercons.de/fcon/doku.php?id=news:issues|Issue Tracker]]__ . \\ 
You will be automatically informed via email about each request related progress by doing so.

===== Sites using this Plugin =====

You got this plugin up and running? You have got a demo page? Put a link here! \\ 
Feel free to add yours here:
  * [[http://www.fristercons.de/fcon/doku.php?id=news:news|fcon - NEWS System Example]]

===== FAQ =====
A small FAQ is provided on: [[http://www.fristercons.de/fcon/doku.php?id=news:descr#faq|fcon - News FAQ]]
===== Discussion =====
Please use only the [[http://forum.dokuwiki.org|DokuWiki Forum]] for discussion and the plugin related __[[http://www.fristercons.de/fcon/doku.php?id=news:issues|Issue Tracker]]__ page (or even [[https://github.com/Taggic/anewssystem/issues|git]]) to raise issues. \\ 
The plugin development is still ongoing. There might be something to be corrected, to be implement or to be improved.

Please fill all the letters into the box to prove you're human. Y Q T H T Please keep this field empty:

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Share Alike 4.0 International