RNM

Summary   : RNM - A Release Notes Manager
Author    : Peter Koch
Created   : 2005-08-23
Revisions :
Based on  : RNM 1.0.0, Facile Forms 1.4.2, Mambo 4.5.1 
Applies to: RNM 1.0.0, Facile Forms 1.4.2 ... 1.4.4, Joomla 1.0.0 ... 1.0.8, Mambo 4.5.1 ... 4.5.3

Contents 1 Abstract 2 Facile Forms Installation 2.1 A tip before you start 2.2 Requirements 2.3 Installation Process 3 RNM Installation 4 Basic Backend Operations 4.1 The component menu 4.2 Manage Applications 4.3 Manage Authors 4.4 Manage Topics 4.5 Manage Releases 5 Multilanguage Support 5.1 Creating other language pieces 5.2 Sharing your translation strings 6 Import and Export 7 Frontend Integration 7.1 Appearence 7.2 Publishing RNM on the frontend 7.3 Publishing a language selection 7.4 Publishing an application selection 7.5 Publishing the query screen

Abstract

The Release Notes Manager (RNM) is a component for maintaining project notes in the backend of your site. It provides a frontend interface for your users to query, read or print the notes. While working with it you will realize that it is not only useful to keep track of what has allready been done, but it is also a good place to note new bug reports, roadmaps, wishes, ongoing tasks and so on. You can later change them into release notes very easy as they are processed.

Allthough it may not compete with full featured systems such as sourceforge, a combination of RNM with other mambo/joomla components as a download manager, a support forum for discussions and a wiki to documentation can make up a perfect site software developers.

RNM handles the following topics, and there are virtually no limits about the number of each:

• Applications
• Authors per application
• Topics per application
• Releases per application
• Items (notes) per release
• Multiple languages
• Export and import of applications

For a first impression you may take a look at the frontend on the Facile Forms site at http://www.facileforms.biz/component/option,com_facileforms/Itemid,95/

Facile Forms Installation

RNM is a Joomla/Mambo component based on Facile Forms. You need not know anything about Facile Forms to install and use RNM. If you allready have the latest version of Facile Forms installed, you can skip this chapter.

A tip before you start

Experienced users will never install a new component on a productive site without checking it first, and I also recommend this to you. An excellent sandbox for such tests are distributions like MSAS or XAMPP: With a few clicks you get a fully functional webserver with preinstalled mambo or joomla on your local computer to check out components, create your templates, develop forms and so on. Dont miss this opportunity.

Requirements

Facile Forms requires one of the Mambo or Joomla releases listed in the header of this document. If you currently dont have any of those, please check out Facile Forms and RNM with one of the distributions listed in the tip above, and decide then if it is worth upgrading your site.

You can download the latest versions of Facile Forms and RNM from http://www.facileforms.biz . The Facile Forms module and mambot are not required to run RNM, but you are of cause free to install them too.

After downloading you should have these 2 files on your computer (the version numbers in the filenames will of cause change accordingly for future releases:

com_facileforms_142.zip

The Facile Forms component release 1.4.2

rnm_100.xml

The Release Note Manager package release 1.0.0

If you download the files from other locations, make sure the Facile Forms component is packed in a zip file, while the RNM package must not be zipped, but the plain XML file.

Installation Process

Start by logging into your site backend:

Go into the component installer of mambo:

Click on Browse:

Select the Facile Forms component file and then click on Open:

Click on Upload File and Install:

Click on Continue to finish the first installation step:

Now basicly the component is installed on the site, at least it is visible in the components menu and the files are in place. However unlike other components you may know, Facile Forms delays the part of the installation process related to database setup and configuration and manages this in a second step. That allows more flexibility in upgrading the component. Dont worry about the options, you mostly just need to read the screen and click on Continue or Save respectively.

Locate facile forms in the component menu and click Configuration: (Actually you could as well click *any* of the facile forms menus)

Since facile forms detects your first access to it, it starts with the installation step 2 instead of going into the selected program. This second part of the installation process enables choosing the database installation or upgrade mode, and the installation of optional packages included in the component. Facile Forms will detect automaticly wether you are upgrading from an older version and propose the correct mode. But anyway its a good idea to check if the selections are ok.

Check the installation mode and then click on Continue:

When everything goes smooth there should no messages be emitted by the database installation tasks, as in seen the screenshot below. Again, check it before proceeding. Click Continue to complete the process:

The last thing to do is to optionaly enter your email address and confirm saving of the settings. Dont care about the other settings in this configuration window at the moment. If you just use Facile Forms to execute RNM or other form packages, the proposed settings should be fine. If something needs special tweaking on your site to make Facile Forms run smooth, you can get help in the Facile Forms support forum.

Click on Save to save the configuration settings:

Now facile forms is installed in your site and ready to use:

RNM Installation

At this point we assume that Facile Forms is installed on the site. If new releases of RNM are published over time, it may also require a newer version of Facile Forms, so check to really have the latest available Facile Forms release, and in case upgrade it before installing the RNM package.

Go into the facile forms configuration:

Start the package installer:

You will see allready installed packages here. Between one and three packages are allready installed depending on the options selected during the second part of the facile forms installation. Additional packages that you may have installed before will also be seen here. The only package really required for RNM is the standard library.

Note:
In case you allready have on old version of RNM installed and are now upgrading, do not uninstall the old version before installing the new one. Just install the new version and all necessary steps for a proper upgrade will be taken automaticly.

Click on Browse to locate the RNM package file:

Browse to the directory on your PC where you have stored the RNM package to. Select the RNM package file and then click on Open:

The path of the package on your local computer should now be in the entry field left of the browse button, as in the screenshot below. Click on Install Package to upload the packager to the server:

After successful installation, a report will be displayed where you can see the details of the package. Click on Continue:

The RNM package will now appear in the  list of installed packages:

The RNM backend programs are now also visible in the component menu:

Basic Backend Operations

The component menu

Release Notes Manager

Clicking on Release Notes Manager has the same effect as Last Position.

Last Position

Brings you back to the position where you last have been in the RNM backend programs.

Manage Applications

Enter the application manager: All the functions for managing applications, authors, topics, releases and items are found here.

Manage Languages

Lets you add, modify or delete languages.

Frontend Preview - Last Position

Brings you back to the position where you last have been in the frontend preview.

Frontend Preview - Applications

Show application selection window of frontend. If only one application is present, you will be forwarded to the item selection screen. The diffrence of the preview compared with the real frontend is that you will also see unpublished stuff. This allows checking out everything before you publish it.

Frontend Preview - Languages

Show language selection window of frontend. If only one language is present, you will be forwarded to the application selection. Again here in the preview you will also see unpublished languages.

Manage Applications

Enter the application manager by the component menu. The list of applications is of cause empty since we just installed RNM, and the first thing we are going to do is add an applications. Click on the button New:

The window for the application settings appears now:

Enter the name of the application, choose the status from the drop-down list and check Published in case you want the application to be published immediately. Dont care about the translation drop down list at the moment, this will be explained in the chapter Multilanguage Support in case you need to maintain different languages in the release notes.

After entering the data, click on Save to store the new application:

Congratulations, you just entered your first application into RNM!

Now basicly this is the same procedure througout all managers, whether you want to add topics, authors or whatever. So lets explain the elements on RNM screens, you will find similar functions them in all other manager windows.

At the right side of the title bar you find the Close button. It is not labeled, just a white cross in a red square. Its purpose is quite obvious at least for windows users: It closes the current RNM screen and returns to the previous one. In the application management screen there is no previous RNM screen, we entered it by the content menu. So clicking on the cancel button right now would bring us to the backend homepage:

The icon buttons assemble the main functions that can be applied to the listed data rows. The New and Delete buttons are available in all manager screens, while the Import and Export buttons are special functions of the application manager:

Some functions such as Delete or Export require that you first select the data rows that shall be processed. You do this by checking the box in the first column of the data rows before clicking the function icon. The checkbox in the heading allows to check or uncheck all displayed data rows thogether:

Most columns in the data row are clickable. When clicking on the name, the window with the application settings will open again so we can change the name, the status or the publish state:

Clicking in the columns Status or Published will immediately change that value instead of opening the application settings window. Every time you click on the status it will change to the next option, and when you click in the published column the publish state will toggle between on and off:

The three columns Authors, Topics and Releases show the number of authors, topics and releases that are present in the application. Since our application is brand new all three columns are 0. You might have allready guesed it: When you click on one of those numbers, the respective manager screen will open and let you manage authors, topics and releases of that application:

Manage Authors

In the previous chapter we learned how to open the author management. Click on the 0 in column Authors now to enter the author manager:

The author management screen appears, and again the list is empty since this is a new application. Click New to add an author:

The entries required are a shortcut and a name:

In this sample I have entered some more authors. After entering all your authors, leave the author management and return to the application manager by clicking the Close button. You can allways return to add more authors, change shortcuts or names or delete authors.

Upon returning to the application manager you can see the number of authors now in the Authors column:

Manage Topics

You allready know now ho to get into the topic manager, right? So click New thereafter to enter a new topic:

The only setting is the name of the topic. You may ask yourself for what this is good at all: By first defining the topics per application, you protect yourself from misspellings, and you later in the item editor need only click in the list of topics instead of entering the topic names over and over every time you add a note:

After saving, the new topic appears in the list. I have entered some more of them here. Leave the topic manager and return to the application manager by using the Close button:

You can see that the number of entered topics are now also visible in the application manager:

Manage Releases

Get into the release manager by clicking the number of releases in the application manager. Then click New to add a new release:

Enter the version number. Well version number does not exactly match it, since you can enter any text here. This may also be something as Wishlist, To do, Open bugs, Roadmap or whatever you can think of to organize your daily software developments.

After saving you will see how to enter notes (called items) into the release: Click on the number of items, as allready known when entering the author, topic and release managers from the application manager:

Click New to enter a new item:

Enter a title and the text for the item, als select the matching options from the authors, type and priority select lists. You can assign any number of application topics to the item to categorize the note.

The text may be formatted by Markdown: This is a very intuitive way to markup text, it is allmost as writing an email text.

You can at any time check the appearence of the note with the Preview button:

The preview shows the note as it will appear in the frontend:

After saving, the item will appear in the item manager. I entered some more items here too. Click the Close button to return to the release manager:

The number of entered items will now be visible in the release manager. Close the release manager by clicking the Close button:

The entered release is now visible in the application manager:

This concludes the main backend operation tasks.

Multilanguage Support

Adding new languages will be quite obvious if you read the previous chapter. I will only cover what is special about multilanguage support here in this chapter.

RNM supports languages in 2 diffrent areas:

• The texts of the application itself, such as labels, titles and messages. Lets call these texts application strings.

• The translation of the contents that you enter, say application and topic names, item titles and texts and so on. Lets call this content translations.

You can add any number of languages to RNM. However keep in mind that the database space used by every item will be multiplied by the number of languages too. So only add languages when you really need them.

Have a look at a typical language settings screen:

• The Name is used in the frontend when you allow users tocchoose language, so it makes sense to enter it in the language that the visitor unterstands. (You need not do so, you can also switch joomla/mambo language with another tool and have RNM use whatever language is known by the joomla/mambo variable mosConfig_language.)

• In Mambolang 1 you enter the mnemonic that the language has in joomla/mambo. You can also add a second mambo language mnemonic which makes sense for languages having a formal and informal speech like german. Leave Mambolang 2 empty when it is not used.

• In Piece you enter the name of the facile forms piece holding the application string translations. In the standard distribution there are only pieces for english (rnmEnglish) and german (rnmGerman), but you can create additional pieces yourself as explained later, or get them from other users who allready did it and share the piece on the facile forms site or other file distribution sources.

Once the language is added, you can return to the application, topic and item managers and switch with the translation dropdown list to translate the contents.

The default language, which is normally english, cannot be deleted. If you dont need english at all, just change the settings in the default language instead of adding a new language.

Creating other language pieces

To create a new piece a little facile forms knowledge is preferable but not really necessary. It is no rocket science and can basicly be done by anybody even without any special programming skills.

Open the facile forms piece manager by the component menu:

Switch to the RNM package:

Locate the english or german translation piece, and check one of them as copy source:

Scroll back up to the function icons and click Copy to make a copy of the checked piece:

Find the copy that you made:

Click on the title to open it:

Change all settings to reflect the new language. Changing the package name is one of the most important things here: If you dont change the package name, you cannot share the translation, and even worse your piece will be deleted silently if you install a new version of RNM!

Translate all the strings in the code section. The version number in front of every string definition reflects in what version the string was last modified or added and shall help you maintain your translation when new releases of RNM are published. You can then print out a copy of the new rnmEnglish or rnmGerman piece and cross check what you need to change in your old translation piece. Dont forget to also change the version in your own translation piece after.

Take care that whenever you need to enter a single quote, it must be preceeded by a backslash as seen in one sample below. Click on Save when all is done. (You might want to save your work from time to time if translation takes longer)

Sharing your translation strings

Sharing your translation piece with others is easy: You need just export the package with your translations with the facile forms package creator. You can then upload the XML file to the facile forms site and others can download it from there. Installation of the package works equal as the installation of the RNM package itself.

Go into the facile forms configuration:

Click on Create Package:

If your package is not selected automaticly, select it from the drop down list labeled ID.

Enter the package informations and make sure that the version matches the version of RNM your translation is made for. This informations will be saved, so you only need to enter it once, and if you later create new versions of the package you will only need to change the version number.

Click on Continue to start package creation:

Save the file on your local hard disk. From there you can upload it to the file distribution of your choise.

Import and Export

This chapter is yet to be done. No rocket science though, I'm quite sure you will be able to figure it out yourself.

Frontend Integration

Appearence

You may have allready played with the frontend preview, and you realize that the screens look poor compared to the sample RNM frontend seen on the facile forms site. This is because your frontend template stylesheet is lacking the necessary styles. You therfore start out by cutting and pasting the following styles into your frontend stylesheet file (you find it normally in templates/<name>/css/template_css.css):

/******************************************************************************
 * Standard styles for facile forms
 */

/* Title bar general settings */
.ff_titlebar {
    background-color:#306EB9;        /* the background color */
    border-top:2px solid #5299D1;    /* make this lighter than background color */
    border-bottom:2px solid #163B7F; /* make this darker then background color */
    border-left:none;                /* dont change this */
    border-right:none;               /* dont change this */
    border-spacing:0px;              /* dont change this */
    border-collapse:collapse;        /* dont change this */
    line-height:24px;                /* dont change this */
}

/* Title bar font settings */
.ff_titlebar div {
    font-size:14px;                  /* the font size */
    font-weight:bold;                /* the font weight */
    color: #ffffff;                  /* the font color */
    margin:0px;                      /* dont change this */
    padding:0px 0px 0px 30px;        /* dont change this */
}

/* Standard buttons */
.ff_button {
    padding: 3px 10px 3px 10px;      /* internal spacing above, right, below and left of text */
    border:outset 1px;               /* style of the border */
    background-color: #f0f0f0;       /* the background color */
    color: #404040;                  /* the font color */
    text-align: center;              /* the text alignment */
    font-size: 12px;                 /* size of the font */
    font-weight: bold;               /* weight of the font */
}

/* Text, Textarea, Select */
.ff_inputbox {
    margin: 0px 0px 0px 0px;         /* external spacing above, right, below and left */
    padding: 2px 0px 2px 0px;        /* internal spacing above, right, below and left */
    border:solid 1px #707070;        /* border appearence */
    background-color: #f4f4f8;       /* background color */
}

/* query list table general settings */
table.ff_querylist {
    margin: 0px 0px 0px 0px;         /* external spacing above, right, below and left */
    padding: 0px 0px 0px 0px;        /* internal spacing above, right, below and left */
    background-color: #ffffff;       /* background color */
    border-spacing: 0px;             /* spacing between borders */
    border-collapse: collapse;       /* collapse adjacent borders to one */
}

/* querylist header cell appearence */
table.ff_querylist th {
    padding: 3px 3px 3px 3px;        /* internal spacing above, right, below and left of content */
    background-color: #b0b0b0;       /* background color */
    border-top:2px solid #e8e8e8;    /* make this lighter than background color */
    border-left:1px solid #e8e8e8;   /* make this lighter than background color */
    border-right:1px solid #707070;  /* make this darker than background color */
    border-bottom:2px solid #707070; /* make this darker than background color */
    font-size: 11px;                 /* font size */
    color: #ffffff;                  /* font color */
}

/* querylist basic data cell settings */
table.ff_querylist td {
    padding: 2px 3px 2px 3px;        /* internal spacing above, right, below and left of content */
    border:1px solid #858585;        /* border settings */
    border-collapse: collapse;       /* collapse adjacent borders to one */
}

/* querylist odd data rows standard settings */
table.ff_querylist tr.data1 {
    background-color: #f4f4f4;       /* background color */
}

/* querylist even data rows standard settings */
table.ff_querylist tr.data2 {
    background-color: #f8f8f8;       /* background color */
}

/* querylist odd data rows hovered settings */
table.ff_querylist tr.data1:hover {
    background-color: #ffffff;       /* background color */
}

/* querylist even data rows hovered settings */
table.ff_querylist tr.data2:hover {
    background-color: #ffffff;       /* background color */
}

/* querylist links standard settings */
table.ff_querylist a {
    color: #333388;                  /* font color */
    font-weight: normal;             /* font weight */
    text-decoration: none;           /* font style */
}

/* querylist links hovered settings */
table.ff_querylist a:hover {
    color: #883333;                  /* font color */
}

/* querylist page navigation row settings */
table.ff_querylist tr.footer {
    background-color: #b0b0b0;	     /* background color */
    border-top:2px solid #e8e8e8;    /* make this lighter than background color */
    border-left:1px solid #e8e8e8;   /* make this lighter than background color */
    border-right:1px solid #707070;  /* make this darker than background color */
    border-bottom:2px solid #707070; /* make this darker than background color */
}

/* querylist page navigation cell settings */
table.ff_querylist td.footer {
    text-align: center;              /* text alignment */
    font-weight: bold;               /* font weight */
    color: #ffffff;                  /* font color */
}
/*
 * End of standard styles for facile forms
 *****************************************************************************/

You shall of cause adapt the colors to fit into your frontend scheme. Test it with the preview functions of RNM until you are satisfied. Then continue with the next chapter to bring it to the real frontend.

Publishing RNM on the frontend

Publishing is basicly done by creating a menu item. You however have three different options:

• Show a language selection screen. This makes just sense if you have more than one language published, otherwise visitors will automaticly be redirected to the application selection - no problem so far, but calling the application selection directly in this case is faster. After visitors have selected the language they will be redirected to the application selection.

• Show a application selection screen. This makes just sense if you have more than one application published, otherwise visitors will automaticly be redirected to the query screen - calling the query screen directly is faster of cause. By passing parameter ff_params_langid you can optionally control what language is displayed. If you dont provide this parameter, the language will be determined by the mambo variable mosConfig_language.

• Directly show the query screen of a certain application. This requires passing the mandatory parameter ff_param_applid to select the application. Like in the application selection you also have the option of forcing a certain language with the parameter ff_param_langid.

Publishing a language selection

Open the mambo menu where you want to add an RNM item:

Click on New to create a new menuitem:

Select Component as menu item type and click Next:

• Enter the name of the menuiten as you want it to appear.
• Select Facile Forms from the component list.
• Select Yes as published state

Click on Apply to save the settings and make the Parameters appear:

• Enter RnmSelectLanguage as form name.
• Select the border to be shown

Click on Save to save the settings and close the menuitem:

Check it out in the frontend:

Publishing an application selection

The steps for creating a component menuitem are basicly identical as above, I dont want to bore you with the details again. Instead, here are the settings that are diffrent:

• Select another name for this menuitem.
• Enter RnmSelectApplication as form name.
• Optionally enter the parameter ff_param_langid in the private parameters as shown to enforce e certain language. If you only have one language this will have no effect at all of cause. The language ID 1 is allways the default language. Supplemental languages will have the ID's 2, 3, 4 and so on. You can also check the language ID in the database table mos_rnm_language in case. Leave the parameters empty to let RNM determine the language itself by the mambo settings mosConfig_language.

Check it out in the frontend:

Publishing the query screen

The steps for creating a component menuitem are again the same as above, here are the settings that are diffrent:

• Select another name for this menuitem.
• Enter RnmSelectItems as form name.
• Enter the parameter ff_param_applid in the private parameters as shown to select the application. The first application will have ID 1 and the next will have the ID's 2, 3, 4 and so on. You can also check the application ID in the database table mos_rnm_application in case.
• You may optionally also enforce the language as in the application selection sample above. Just append it to the other parameter without any spacing between as &ff_param_applid=3&ff_param_langid=2 for example.

Check it out in the frontend:

This concludes the Release Notes Manager manual. If you have any problems or additional questions, you may get assistence in the Facile Forms support forums.