Wiki source code of Mail Archive User Guide
Last modified by Thomas Mortagne on 2023/07/08 08:57
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{velocity}} | ||
| 2 | $xwiki.ssx.use('Extension.Mail Archive Documentation') | ||
| 3 | {{/velocity}} | ||
| 4 | |||
| 5 | {{info}} | ||
| 6 | Note : screenshots might differ from actual display. | ||
| 7 | {{/info}} | ||
| 8 | |||
| 9 | {{toc numbered="true"/}} | ||
| 10 | |||
| 11 | = Viewing Topics and Mails = | ||
| 12 | |||
| 13 | The __[[homepage>>MailArchive.WebHome]]__ of the application presents links to main pages, and a display of the topics of registered mailing-lists : | ||
| 14 | |||
| 15 | (% class="figure" %) | ||
| 16 | [[image:MA_User_Home_Header.png]] | ||
| 17 | **Figure 1 - MailArchive home page** | ||
| 18 | |||
| 19 | The following features are available from this home page : | ||
| 20 | |||
| 21 | * "Switch to [Time-Line/Table] view": change the topics display | ||
| 22 | * "Mailing-list statistics" | ||
| 23 | * "Documentation" : the documentation, including this user guide | ||
| 24 | * "Open Issues" : known issues/improvements | ||
| 25 | * "Feeds Generator" : to feed filtered content from the archive in other sites / tools | ||
| 26 | * "Administrate and Configure" and "Operations" are restricted to admins and described in the Admin Guide. | ||
| 27 | * "Legend": a legend, to give you the list of configured mailing-lists (that have an associated colour) and configured mail "categories" or types (that have an associated icon). | ||
| 28 | |||
| 29 | == Legend == | ||
| 30 | |||
| 31 | (% class="figure" %) | ||
| 32 | [[image:MA_User_Legend.png||width="439px"]] | ||
| 33 | |||
| 34 | == Table View == | ||
| 35 | |||
| 36 | The __[[homepage>>MailArchive.WebHome]]__ shows the list of all topics : | ||
| 37 | |||
| 38 | (% class="figure" %) | ||
| 39 | [[image:MA_User_Home_TableView.png]] | ||
| 40 | **Figure 2 - MailArchive home page - Table view** | ||
| 41 | |||
| 42 | To filter a column depending on text values, enter some text in the "Filter..." field above column title, then click on "Filter" button on the right. | ||
| 43 | |||
| 44 | To sort a column just click on the column title. Click again to sort in reverse order. By default mails are presented in reversed chronological order. | ||
| 45 | |||
| 46 | //Note : it is not possible to sort by ratings for now ...// | ||
| 47 | |||
| 48 | To filter on a specific mailing-list, and / or on a type of topic (if any configured), just click on its name once in the tag cloud, above the table. To remove the filter, just click again on the same tag. | ||
| 49 | |||
| 50 | The size of the tag in the tag cloud, gives you an idea of the number of topics related to it. | ||
| 51 | |||
| 52 | To show a topic, just click on its title (see in more details later in this document). | ||
| 53 | |||
| 54 | Clicking on a user name would bring a specific user page with statistics and lists of topics and emails from this user. | ||
| 55 | |||
| 56 | //Note : the user statistics are available only if unlocked by the administrator// | ||
| 57 | |||
| 58 | == TimeLine view == | ||
| 59 | |||
| 60 | As an alternative to the table view, the mailarchive can be viewed as a time-line by clicking on "Swich to Time-Line view" link in the homepage. It's a different way to present and browse the same information : | ||
| 61 | |||
| 62 | (% class="figure" %) | ||
| 63 | [[image:MA_User_Home_TimeLineView.png]] | ||
| 64 | **Figure 3 - MailArchive home page - TimeLine view** | ||
| 65 | |||
| 66 | Each topic is represented by a colored line, and the topic title just below this line. The colors match each possible Mailing-List (see the legend above the timeline). The line extends from topic beginning to topic last update date (last mail received). | ||
| 67 | |||
| 68 | Moving along the time line is done by left-click and drag on the timeline bands. The lower band moves faster than the upper (more detailed) band. | ||
| 69 | |||
| 70 | The icons in front of each line indicate different topics types, depending on what is configured. | ||
| 71 | |||
| 72 | Clicking on a particular topic will open a "bubble" pop-up on top of the timeline with following info : | ||
| 73 | |||
| 74 | (% class="figure" %) | ||
| 75 | [[image:MA_User_TimeLine_TopicBubble.png]] | ||
| 76 | **Figure 4 - TimeLine - Topic bubble** | ||
| 77 | |||
| 78 | The bubble presents the topic title, creator, and a list with initial mail and answers about this topic. Common parts of the mail subjects are represented by "...". | ||
| 79 | |||
| 80 | Clicking on topic title will show the Topic page (see below). | ||
| 81 | |||
| 82 | Clicking on a particular date will move the time-line toward (or backward) this date. | ||
| 83 | |||
| 84 | Clicking on a particular mail subject will open the related mail page. | ||
| 85 | |||
| 86 | Clicking on a user name will open the user profile in the wiki (if it exists). | ||
| 87 | |||
| 88 | == Topics == | ||
| 89 | |||
| 90 | When clicking on a particular topic, a page shows all messages (mails) that compose it. You can view topics using three different views : list, threads or forum. | ||
| 91 | |||
| 92 | It can be displayed as a List in a table (columns can be filtered and/or sorted) : | ||
| 93 | |||
| 94 | (% class="figure" %) | ||
| 95 | [[image:MA_User_Topic_Table.png]] | ||
| 96 | **Figure 5 - Topics - Table view** | ||
| 97 | |||
| 98 | The same kind of sorting and filtering than you can find from homepage can be applied here. | ||
| 99 | |||
| 100 | You can also display a topic as a discussion thread : | ||
| 101 | |||
| 102 | (% class="figure" %) | ||
| 103 | [[image:MA_User_Topic_Threads.png]] | ||
| 104 | **Figure 6 - Topics - Threads view** | ||
| 105 | |||
| 106 | The last possibility is to view topics as a forum : | ||
| 107 | |||
| 108 | (% class="figure" %) | ||
| 109 | [[image:MA_User_Topic_Forum.png]] | ||
| 110 | **Figure 7 - Topics - Forum view** | ||
| 111 | |||
| 112 | The forum view is the only one where you can view the content of the different mails in a same view. Panels are adjusted to present last mail information, you have to use scrollbars to visualize the replies history. | ||
| 113 | |||
| 114 | The default view is configured by the administrator. | ||
| 115 | |||
| 116 | == Mail Messages == | ||
| 117 | |||
| 118 | When clicking on a particular message link from a topic view, its content is displayed. | ||
| 119 | |||
| 120 | In this page you can also have access to all attachments of the email, as links, and to mail headers by clicking on "Show details" in top-right corner. | ||
| 121 | |||
| 122 | (screenshots to be added) | ||
| 123 | |||
| 124 | == Ratings == | ||
| 125 | |||
| 126 | You have the possibility to vote and attribute a rating to Topics and/or Emails. | ||
| 127 | |||
| 128 | //Note: ratings are available only if unlocked by the administrator// | ||
| 129 | |||
| 130 | To do so, navigate to the item you want to vote for, then navigate on the symbol in top-right corner of the page to choose appropriate number of 'stars'. Finally, left-click to vote. | ||
| 131 | |||
| 132 | Average ratings are displayed for topics (in homepage) and mails inside topics, in table views. | ||
| 133 | |||
| 134 | |||
| 135 | = Statistics = | ||
| 136 | |||
| 137 | == Global statistics == | ||
| 138 | |||
| 139 | __[[Link to statistics page>>MailArchive.Statistics]]__ is also available in Mail archive application homepage. | ||
| 140 | |||
| 141 | The statistics page show various information about the managed mailing-lists. | ||
| 142 | |||
| 143 | View can be filtered to show only information related to one of the mailing-lists, or, as by default, all mailing-lists. | ||
| 144 | |||
| 145 | (% class="figure" %) | ||
| 146 | [[image:MA_User_Stats_Default.png]] | ||
| 147 | **Figure 11 - Statistics linked to specific DL** | ||
| 148 | |||
| 149 | Mail Distribution gives repartition of topics depending on mails types and mailing-lists: | ||
| 150 | |||
| 151 | (% class="figure" %) | ||
| 152 | [[image:MA_User_Stats_Distrib.png]] | ||
| 153 | **Figure 12 - Statistics - Mails distribution** | ||
| 154 | |||
| 155 | |||
| 156 | Lastly, Posters localization gives an idea of from where people send mails to the mailing-lists ;): | ||
| 157 | |||
| 158 | (% class="figure" %) | ||
| 159 | [[image:MA_User_Stats_Localize.png]] | ||
| 160 | **Figure 13 - Statistics - Posters localization** | ||
| 161 | |||
| 162 | //Note: this information might not be accurate if proper information is not available from wiki profiles, or from a bound LDAP.// | ||
| 163 | |||
| 164 | == User-Specific statistics == | ||
| 165 | |||
| 166 | When clicking on a user name link from homepage (table view) or from a Topic view (table view), you can bring some statistics about this user contribution to the Mail Archive : | ||
| 167 | |||
| 168 | (% class="figure" %) | ||
| 169 | [[image:MA_User_Stats_User.png]] | ||
| 170 | **Figure 14 - User Statistics** | ||
| 171 | |||
| 172 | You can also display lists of topics and emails from this user in the same page. | ||
| 173 | |||
| 174 | = Searching for mails and topics = | ||
| 175 | |||
| 176 | Using the xwiki search functionality, by default you will be able to search for all pages in wiki, including mails and topics. | ||
| 177 | |||
| 178 | To search only inside mails and topics, you can enter your search terms as follow : | ||
| 179 | |||
| 180 | {{code language="none"}} | ||
| 181 | "object:MailArchiveCode.MailClass AND <search terms>" | ||
| 182 | {{/code}} | ||
| 183 | |||
| 184 | For example, to search for all mails from the mailing-lists talking about XWIKI, you would indicate the following search terms : | ||
| 185 | |||
| 186 | {{code language="none"}} | ||
| 187 | "object:MailArchiveCode.MailClass AND XWIKI". | ||
| 188 | {{/code}} | ||
| 189 | |||
| 190 | To search only for topics, you can use this notation : | ||
| 191 | |||
| 192 | {{code language="none"}} | ||
| 193 | "object:MailArchiveCode.MailTopicClass AND <search terms>" | ||
| 194 | {{/code}} | ||
| 195 | |||
| 196 | For example, searching for all topics having Mail in their subject, you would indicate : | ||
| 197 | |||
| 198 | {{code language="none"}} | ||
| 199 | "object:MailArchiveCode.MailTopicClass AND Mail" | ||
| 200 | {{/code}} | ||
| 201 | |||
| 202 | |||
| 203 | = Feeding the archive = | ||
| 204 | |||
| 205 | This feature allows to easily integrate content from the Mail Archive in other tools or websites, including other wikis. | ||
| 206 | |||
| 207 | For this browse to the home page, then click on the "Feeds Generator" link. | ||
| 208 | |||
| 209 | A sort of wizard is displayed. | ||
| 210 | |||
| 211 | View is divided in two columns : | ||
| 212 | |||
| 213 | * first column lets you choose what items you want to be displayed, by selecting filters | ||
| 214 | * second view outputs the result to expect (and the content to copy/paste to obtain it) | ||
| 215 | * Click on "Generate" to preview the result | ||
| 216 | |||
| 217 | In the following example, we generate some HTML that, once copied in a web page, will output a list of filtered emails : | ||
| 218 | |||
| 219 | (% class="figure" %) | ||
| 220 | [[image:MA_User_Feeds_1.png]] | ||
| 221 | **Figure 16 - Feeds Generator - Sample 1** | ||
| 222 | |||
| 223 | In this second sample, we generate some RSS feed that can be integrated in another XWiki page : | ||
| 224 | |||
| 225 | (% class="figure" %) | ||
| 226 | [[image:MA_User_Feeds_2.png]] | ||
| 227 | **Figure 17 - Feeds Generator - Sample 2** | ||
| 228 | |||
| 229 | And this is what we obtain when pasting generated output in another XWiki page : | ||
| 230 | |||
| 231 | (% class="figure" %) | ||
| 232 | [[image:MA_User_Feeds_RSS.png]] | ||
| 233 | **Figure 18 - Sample XWiki RSS** | ||
| 234 | |||
| 235 | The possible output formats are : | ||
| 236 | |||
| 237 | * HTML | ||
| 238 | * RSS | ||
| 239 | * JSON | ||
| 240 | * XML | ||
| 241 | |||
| 242 | These formats allow you to integrate filtered information in virtually any other web-centric information system. With XML and a dedicated XSLT, you could produce any kind of formatting. | ||
| 243 | |||
| 244 | With RSS you have the opportunity to re-gain control over what items you want to follow. | ||
| 245 | |||
| 246 | Have fun ! |
