eWriting Administrator Guide

December, 2005

This guide was written for eWriting Joomla! Component. The current version December, 2005 is eWriting 1.2.1

The guide is design to get eWriting installed and configured quickly, with the minimum of fuss. It is highly recommended that you explore the features of eWriting after working through this guide.

A Joomla! Component to Admin Stories and Fanfictions

Version 1.2.1
Copyright © 2004-2005
License GNU GPL
Developer Bárbara Irene Meclazcke (aka Aclaina)
Website http://ewriting.com.ar/
Development http://developer.joomla.org/sf/projects/ewriting

eWriting Administrator Guide

1. INSTALLATION
    1.1 Preparation
    1.2 eWriting component and module installation

2. CONFIGURING
    2.1 Storage tab
    2.2 Accessiblity tab
    2.3 Integration tab

3. CATEGORIES

4. REVIEWS

5. PROPERTIES AND PROPERTY TYPES
    5.1 Example
    5.2 Property Types

6. UTILITIES

7. STORIES

8. ADVANCED TOPICS
    8.1 Activating integrated components
    8.2 Story Forums - JoomlaBoard
    8.3 Personal Messaging
    8.4 Customising eWriting
    8.5 Style Sheets

9. END NOTE

Administrator Guide

This guide will show you the bare bones of getting eWriting installed and running. It will not detail every feature. Therefore it is recommended to play with the configuration afterwards.

1. Installation

The installation process will detail
- The preparation required
- Installing the components & Modules
- Integrating with other useful components

1.1 Preparation.

There are two website which you can find eWriting:
The developer: http://ewriting.com.ar/
JoomlaForge: http://developer.joomla.org/sf/projects/ewriting

The list files you should download:

   com_ewriting_1.2.1.zip
   mod_ewritingLastAddedStories.zip
   mod_ewritingLastUpdatedStroies.zip

For those Joomla! installations with Community Builder, it is highly recommended to download:

 plug_cbewritingtab.zip

For those Joomla! installations with JoomlaBoard (or SimpleBoard) then it is recommended to download:

 joomlaboard1.1_eW1.2.1hack.zip

Note: there is also a module to show the ‘Most Read’ stories available from http://www.pennadoca.net/. We won’t be covering this here.

1.2 eWriting component and module installation

The preferred process of installing the modules is to install the component before modules.

Log into the Joomla! Administrator backend and select the Installers menu:

Diagram: Menu options for installing Components (1) and Modules (2)

1.2.1 The component

From the Installer menu select Components. Then:
1. Browse and select the eWriting component com_ewriting_1.2.1.zip
2. Click Upload File and Install
3. The response should be something similar to:

4. Make careful note of any areas and check the http://ewriting.com.ar/ forums for trouble shooting.
5. Click Continue.

1.2.2 The modules

In the Joomla! Administrator menu, select Installers > Modules. Then do the following for the modules:

 mod_ewritingLastAddedStories.zip
 mod_ewritingLastUpdatedStroies.zip

In the Upload Package File panel:
1. Select Browse and select the eWriting Module
2. Click Upload and Install
3. The response should be something similar to:

4. Make careful note of any areas and check the eWriting forums for help.
5. Click Continue.

I suppose you want to see the component now? Lets do some housekeeping first & configure it. If everything has gone smoothly then you should be able to find
1. The eWriting component listed in the Component menu
2. The eWriting modules listed in the Site Modules*.

If you note in the previous Module Manager diagram the two modules are not published. You will have to publish (i.e. click the red cross) and also set up which module position they will go. Consult your Joomla! guide for more details.

*A tip for new players: when you list the site modules [Menu: Modules > Site] you may not see your new module. This is because there are too many.

At the bottom of the page change the Display # records shown. You can also change the default shown in the site configuration.


2. Configuring

Under the Components menu you will find eWriting. The important tabs to get going include Storage & Accessibility. The other tab contents are clear with self-explanatory and contents.

2.1 Storage Tab

Web / Stories Path refers to the place where stories are saved. The component install should have created a Stories Path. Check if this does exist, otherwise a story’s chapter can not be saved.

This is especially important on Unix/Linux based systems due to permissions. You need read/write/execute permissions. A file transfer client like FileZilla or FireFTP can be useful here.

The Allowed Extensions refers to the chapter file types authors can upload. Modify this as it suits e.g. XML.

2.2 Accessibility Tab

This tab sets controls the access to adding and modifying stories. Here you can protect stories from unregistered users.

2.3 Integration Tab

If you are integrating eWriting with JoomlaBoard etcetera then you should investigate the “Integration” tab. You must install those components before integrating them with eWriting.

The other tabs are up to you configure.

3. Categories

Stories have genres. You can use categories to reflect genres or any other ordering. It’s simply a convenience. You can have categories within categories. And you can keep on creating sub categories ad-infinitum to really confuse your authors and reviewers.

In this configuration section you can publish, unpublish
move, add, edit, delete categories, managing them much in the same way as any other Joomla! item.

You must add a category and publish it before eWriting will work.

4. Reviews

Manage all the reviews from all the stories. Of course you can search and filter the reviews. Nothing is required to get the component installed.

5. Properties and Property Types

Now this is a cool feature – you can provide authors with a means of selecting the properties of a story (or it’s meta information). For example properties allows us to record what language and what genres the story is in. Here you are simply creating the property type and individual properties to enable authors to ‘classify’ their stories.

5.1 Example

To illustrate setting up properties(these are used in the user guide):

Part A – Genre Property Type

- Using the Property Types menu select Add
- Give it the name ‘Genre’.
- Set Multiselect = YES.
- Set its properties (Listing=Yes, Publish=TRUE)
- Click Save


Part B – Language Property Type

- Using the Property Types menu select Add
- Give it the name ‘Language’.
- Set Multiselect = NO.
- Set its properties (Listing=Yes, Publish=TRUE)
- Click Save

Part C – Genre Properties

- Return to the eWriting Control panel and select Properties
- Click Add
- Set Property = Genre
- Set Name = Comedy
- Click Save
- Repeat the Add process for more genres eg Horror, Romance

Part D – Language Properties

- Return to the eWriting Control panel and select Properties
- Click Add
- Set Property = Language
- Set Name = English
- Repeat the Add process for more languages eg Spanish, French
- Click Save

These properties will come in to play when authoring a story. While not required to get going, they are very useful when it comes to searching for a story.

5.2 Property Types

Lets go all ‘advanced’ and explore the property types to really maximise what our authors can do. This provides the detail behind what you achieved in the previous example.

1. Name: simply a title of the property choice. Tip: use a PHP string defined in a language file for when the Joomla multilanguage feature is implemented.
2. Multiselect: whether this property type is for multiselect purposes or not, ie: multiselect properties like Genres, single-select properties like Languages.
3. Extra Field: used to show popup warning (e.g. to warn about adult content) or used for describing the story list property type on the frontend.
4. Warn with popup window: used with the Extra Field, sets the warning to be viewed as a pop-up.
5. Listing: property type will be listed on combo frontend or not.
6. Published: whether to display or not this property type on frontend. All properties are displayed in backend.

6. Utilities

These are simple little tools that help maintain eWriting in tiptop condition.
- Recalculating the story count. Currently eWriting does not automatically update the count when stories are added or modified.
- Finding orphaned files (old chapters). Sometimes the permissions on Linux systems prevent files from being deleted. This utility will help you manage this poor orphans.
- Show statistics.

7. Stories

Ok. Now we’re ready for the stories. While you can add and edit stories here it’s not really the point. This section is provided for you to manage story collections, permissions and publication. The main creative action occurs in the front-end. Check out the eWriting User Guide.

8. Advanced Topics

It is possible to make story writing a much richer experience by plugging in to other systems. Integrating allows authors and reviewers to tap into forums, provide detailed profiles, and users to chat directly with each other.

8.1 Activating Integrated Components

To activate third party components in eWriting:

1. Install & configure the component first (obviously!).
2. Follow the individual component integration instructions below & then return here.
3. Visit the eWriting component Control Panel.
4. Select Configuration.
5. Select the Integration tab.
6. Scroll to the appropriate section – Messaging, Community Builder, & Forum (see below for more details)
7. Check the Installed Status
8. Set the appropriate options.
9. Click Save.

8.2 Story Forums - JoomlaBoard

Website: http://www.tsmf.net/
Files: http://developer.joomla.org/sf/sfmain/do/viewProject/projects.simpleboard

You can directly specify a forum for each story within eWriting. This is very desirable as otherwise you would have to tell readers & authors to visit the forum section & then find that story’s forum.

In version eWriting 1.2.1 an update to a JoomlaBoard file is required to enable posting within the forum. The file joomlaboard1.1_eW1.2.1hack.zip contains a file called post.php. To patch this:
1. Open the directory <joomla!>/components/com_joomlaboard/
2. Backup the original post.php
3. Copy the new post.php

!Important: this patch only relates to JoomlaBoard version 1.0 and eWriting 1.2.1. The good folks working on JoomlaBoard will be integrating this hack so you can safely ignore this in newer JoomlaBoard versions.

Note: JoomlaBoard also integrates with myPMS II and Community Builder as well. Check the JoomlaBoard Configuration > Integration tab. Neat, huh?

8.3 User Management Community Builder

Website: http://www.mambojoe.com/
Project: http://developer.joomla.org/sf/sfmain/do/viewProject/projects.cb

This component will help you to build and facilitate an online community on your website. Community Builder manages user profile, registration, user lists, and moderation. By integrating with eWriting you get much richer information about your authors and reviewers.

To Integrate:

1. Download plug_cbewritingtab.zip from the eWriting project.
2. From the Component Menu select Community Builder > Plugin Management
3. Scroll to the bottom of the page to Install New Plugin.
4. Click Upload File & Install.
5. Select the new plug-in cb.eWriting.
6. Set the Plugin Detail Published to YES
7. Set the parameters as appropriate.
8. Click save.
9. In the Component Menu, select Community Builder > Tab Management.
10. Select the eWriting Tab.
11. Change the title, details and parameters as appropriate.
12. Click Save.
13. Return to the usual eWriting integration steps.

8.4 Personal Messaging

There are two personal messaging plug-ins available – Missus and MyPMSII. Each have their own installation requirements and process. I’m too lazy to detail these.

Missus

Website: http://ewriting.com.ar/
Files: http://developer.joomla.org/sf/projects/missus

MyPMS II

Website: http://www.mamboy.com/
Files: http://www.mamboy.com/

8.5 Customising eWriting

The eWriting Project development home provides extra icons and languages for you. You can also contribute your own language and icons.

See the website: http://developer.joomla.org/sf/frs/do/viewSummary/projects.ewriting/frs

8.5.1 Icons

There are different icon sets available for eWriting from the development site. These are placed in the directories:
<joomla!>/components/administrator/com_ewriting/images
<joomla!>/components/com_ewriting/images
Do take care when replacing files on the server.

8.5.2 Language

The default languages provided are English and Spanish.
<joomla!>/components/com_ewriting/language

8.5.3 Style Sheets

eWriting depends largely on the Joomla! style sheet for a lot of it’s appearance. Sometime a Joomla! template does have the standard styles. The style sheets will be found in the templates directory of your web site <joomla!>/templates/your_template.

Below is a copy of the styles that is used in eWriting for the User Guide:

   /* Styles for dhtml tabbed-pages */
   .ontab {
   background-color : #EEEEEE; /* #e5e5e5; */
   border-left: outset 1px #BBBBBB;
   border-right: outset 1px #BBBBBB;
   border-top: outset 1px #BBBBBB;
   border-bottom: solid 1px #EEEEEE;
   text-align: center;
   cursor: hand;
   font-weight: bold;
   }
   .offtab {
   background-color: #BBBBBB; /* #ffae00; */
   border-left: outset 1px #EEEEEE;
   border-right: outset 1px #EEEEEE;
   border-top: outset 1px #EEEEEE;
   border-bottom: solid 2px #BBBBBB;
   text-align: center;
   cursor: hand;
   font-weight: normal;
   color: #FFFFFF;
   }
   .tabpadding {
   }
   .tabheading {
   background-color: #EEEEEE;
   text-align: left;
   }
   .sectiontableheader {
   font-weight: bold;
   background: #f0f0f0;
   padding: 4px;
   }
.sectiontablefooter {
}
.sectiontableentry1 {
   background-color : #CCCCCC;
   }
.sectiontableentry2 {
   background-color : #f9f9f9;
   }

9. End Note

This is free software and provides freedom of use and distribution. You might consider how you can contribute:
- Bug spotting & fixing
- Documentation
- Development
- Donation
Each one of these is a valuable contribution to the development of this component and to the general Open Source Software movement. Contact Aclaina at http://ewriting.com.ar/ to contribute today.