source: products/SimpleBlog/branches/plone-2.1-Blogging-APIs/readme.txt

Last change on this file was 1, checked in by myroslav, 14 years ago

Building directory structure

File size: 8.0 KB
Line 
1Tip: read this document in ZMI/Products/SimpleBlog/README or in another stx aware reader.
2
3What is SimpleBlog?
4
5SimpleBlog is an easy to use Plone based weblog application. It has no fancy blogger-api/backlink
6stuff etc. but it does supports categories. Writing entries is done from inside Plone.
7
8SimpleBlog comes with three new portal types: Blog, BlogFolder and BlogEntry:
9
10Blog -- Folderish object that is the container for the BlogEntries and the front-page of the weblog.
11
12BlogEntry -- Entry object inside the weblog.
13
14BlogFolder -- Folder that can only exist inside the Blog container. The folder allows you to organize the BlogEntries in any way you like.
15
16Getting started
17
18    After you have set the permissions correctly in ZMI (see install.txt) you can go to any folder that you have
19permissions for and add a Blog from any of the dropdown lists. You will be given a form where you can
20provide the necessary information to create a new Blog:
21
22    * **Short Name**, **Title**, **Description** will speak for themselves.
23   
24    * **Display Mode**: tells SimpleBlog how to render the
25front-page, when you click on the Blog object.
26
27    * **BlogEntries to display** defines how many items should be visible on the Blog's front-page.
28
29    * **Possible Categories** is a list of categories that can be used inside
30BlogEntries (one category per line). More about categories later.
31
32After you have created the Blog, you can start creating BlogEntries.
33Choose BlogEntry from the Add items list and fill in the form:
34
35    * **Short Name**, **Title**, **Description**, **Body** will speak for themselves. **Note** when you
36use the Upload a file field, be aware that it will replace the current content!!
37   
38    * **Categories** Select one or more categories from the list to classify
39the BlogEntry.
40
41   * **Entry is always listed on top.** Controls if the Entry, when published is always shown first. This can be
42handy for announcements etc.
43
44After the BlogEntry is saved, it will be in the 'draft' workflow state and is only visible by the owner and the manager (by default).
45So, in order to make it appear on the Blog's front-page, it must be set in the 'published' state. The Blog will search and
46display the BlogEntries that have this state (this state is defined in the simpleblog_tool in ZMI and in the configlet in
47Plone setup). When putting the BlogEntry in the published state, you can also choose
48to give it an effective date somewhere in the future. SimpleBlog uses the standard way of publishing content.
49
50Inside the Blog you can create BlogFolders. These are a bit similar to the Blog itself in that it has roughly the
51same view but this time it only shows the Entries that are stored inside the BlogFolder (and subfolders). BlogFolders are there
52for your convenience, to organize or archive Entries in any way you want and to have additional categories (see below).
53
54Categories
55
56    SimpleBlog can use categories to classify BlogEntries. When you edit and configure
57the Blog object, you can provide it with a list of categories that will
58present itself as a multi-selection list when you edit/create a BlogEntry.
59Next to that, BlogFolders can define additional categories.
60In BlogEntries created inside the BlogFolder, a selection can be made out of the categories
61defined in the Blog *and*, additionally, out of the ones defined by the BlogFolder(s) it sits in. All the
62categories will add up. This feature can be useful when the Blog is
63maintained by several authors. You can then incorporate some policy that certain Entries must be
64created in specific BlogFolders because of the additional categories. Categories you can later search for but you
65don't want exposed to all the other authors.
66
67Next to categories defined by the Blog object and the BlogFolders, you can also define a
68set of global categories. These categories are available to all the BlogEntries created in the portal.
69Defining these global categories can be done in ZMI in the simpleblog_tool or in the Plone setup.
70
71BlogEntries can be searched for in the Catalog and in Topics using categories. Use the EntryCategory index.
72
73Portlets
74
75    SimpleBlog comes with 5 different portlets. The portlets behave mainly in two different ways.
76The portlet names ending with _local are only visible inside the Blog structure. They are hidden as soon as you
77are not within an BlogEntry, BlogFolder or Blog. Portlets ending with _global on the other hand, are visible
78everywhere and will summarize among Blogs deeper in the folder structure.
79
80There are two display modes for both the _local and _global portlets. The Full version shows the calendar, the top
81most recent entries and the available categories. Clicking on the entries will lead to the full BlogEntry view
82and clicking on the category will display a list of BlogEntries within that category. Next to the Full version
83there is also a Recent version. That version will not display the categories and only presents a list of the recent
84additions.
85
86So, summarizing, you can use any of these values inside the left_slots or right_slots:
87
88    1 here/portlet_simpleblog/macros/portletBlogFull_local
89
90    2 here/portlet_simpleblog/macros/portletBlogFull_global
91
92    3 here/portlet_simpleblog/macros/portletBlogRecent_local
93
94    4 here/portlet_simpleblog/macros/portletBlogRecent_global
95
96There is an additional 5th portlet: portletRecentComments_local that shows the latest comments within the blog.
97
98Configuring SimpleBlog
99
100    SimpleBlog allows you to control a few things in its behavior. In ZMI you can alter a few properties in
101the simpleblog_tool or, when you use Plone 2.0, you can go to Plone setup and go to the SimpleBlog control
102panel. The following properties can be set:
103
104    * **publishedState**: the name of the workflow state that indicates when the BlogEntry is
105published. Usually this will be set to 'published' but if your state is called differently in your workflow, then
106you can change it here. This state is used when SimpleBlog searches for
107BlogEntries that can be displayed on the front-page. So, if no Entries show up,
108check the workflow state of the BlogEntry and check if this property is correct. And check if the BlogEntries
109themselves have the proper state and make sure the user has the proper permissions to view the entries even
110when they are in the published state. (If entries still don't show up and you're sure you've checked everything,
111contact me).
112
113    * **maxItemsInPortlet**: Tells how many BlogEntries are shown inside the portlets when SimpleBlog
114displays the most recent BlogEntries.
115
116    * **globalCategories**: Lists the categories that are globally available in all BlogEntries in the portal.
117   
118    * **showStandardButtons**: Controls if you want to see default buttons for the actions below the BlogEntries
119(like Add comment, Edit) or have them presented as links (which is not standard since they are actions and not links, but some
120people prefer this display mode).
121
122    * **createPortletOnBlogCreation **: By default, when you create a new Blog, SimpleBlog will create the portletBlogFull_local
123portlet. You can turn this feature off by un-checking this option.
124
125   *  **showIcons**: Controls if the Entry icon is displayed in front of the entry titles.
126
127**Note**: In the SimpleBlog control panel inside Plone setup, these variables are called a bit differently but the explanations
128will be sufficient.
129
130
131Using SimpleBlog as your homepage in Plone
132
133    Inside the skin folder there is a template called **simpleblog_standalone**. First get rid of the current index_html
134in your portal root by deleting it or renaming it. Then create a new Page template in the root and call it index_html.
135Then copy/paste the code from simpleblog_standalone in there and adjust it at will. All this is done in ZMI.
136
137Well, that's all you have to know to set up SimpleBlog. Enjoy it.
138
139Danny Bloemendaal (danny.bloemendaal@companion.nl)
140
141PS: I'd like to thank everybody in #plone and everybody who sent me their suggestions for
142modifications and additions.
Note: See TracBrowser for help on using the repository browser.