Letter module Written Communications [Admidio-Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Letter module Written Communications ======

This[[https://github.com/thomas-rcv/admidio-written_communications|Plugin]] allows you to create letters and form letters. Based on a *.docx template with placeholders (template) this plugin generates a complete * .docx document and start downloading the file you created. The resulting document can be processed with corresponding software on the PC. MS Office, OpenOffice and LibreOffice are supported. 
 

===== Requirements =====

Admidio Version 2.4.4 or higher


==== Downloads ====
<WRAP download 60%>
[[https://www.admidio.org/intern/modules/documents-files.php?mode=download&file_uuid=4863010d-97b1-4d2f-b561-e5834a83e1a1|written communications_4.0.0.zip]] - **(Admidio 5.0 or newer)**\\ 
</WRAP>

Older versions:\\
[[https://www.admidio.org/intern/modules/documents-files.php?mode=download&file_uuid=618d32bd-06f9-4cd8-8e69-bd990676e3c1|written communications_3.4.2.zip]] - (Admidio 4.2 - Admidio 4.3)\\ 
[[https://www.admidio.org/intern/modules/documents-files.php?mode=download&file_uuid=bb55db15-8da1-4433-a8fe-70ae94d66669|written communications_3.4.1.zip]] - (Admidio 4.1)\\ 
[[https://www.admidio.org/intern/modules/documents-files.php?mode=download&file_uuid=12a26b12-5218-4740-9812-d18f076aecee|written communications_3.3.3.zip]] - (Admidio 4.0)\\ 
[[https://www.admidio.org/intern/modules/documents-files.php?mode=download&file_uuid=6cb36c7a-dd3e-4331-80f5-4a83fc59e838|written communications_3.2.2.zip]] - (Admidio 3.3)\\ 
[[https://www.admidio.org/intern/modules/documents-files.php?mode=download&file_uuid=57fd56e8-98b4-412f-83f6-07ab72f04a19|written communications_3.1.zip]] - (Admidio 3.2)\\ 
[[https://www.admidio.org/intern/modules/documents-files.php?mode=download&file_uuid=ff234feb-a9a8-4e1a-bbe7-ba50675f222e|written communications_3.0.zip]] - (Admidio 3.1)\\ 
[[https://www.admidio.org/intern/modules/documents-files.php?mode=download&file_uuid=ba98822b-e603-4fbd-95b6-fecd61a4f40c|written communications_2.0.1.zip]] - (Admidio 3.0)\\ 
[[https://www.admidio.org/intern/modules/documents-files.php?mode=download&file_uuid=bc5ca653-ff99-4fc2-890a-07c8f32d8654|written communications_1.1.zip]] - (min. Admidio 2.4.4)

==== Information ====
Supported by: **Thomas-RCV**\\ 

Plugin-Version:     **3.4.1**\\ 

Required Admidio-Version:  **at least version 2.4.4**\\ 

Supported Databases:  **MySQL, PostgreSQL**\\ 

Supported Languages: **German, German(polite), Englisch**

License: **GPL 2**

Sourcecode: [[https://github.com/thomas-rcv/admidio-written_communications|Github]]


==== Screenshots ====
{{ :de:2.0:plg_wc_img1.jpg |}}

{{ :de:2.0:plg_wc_img2.jpg |}}


===== Install the Plugin =====

An installation is not nescessary. Just unpack the downloaded files an copy them into **adm_plugins**. Add a link to the Admidio menu in your used theme and also in the overview page.

== Example: ==

In file **my_body_bottom.php** add at the end of the menu the follwing link:
   
<code php>
$moduleMenu->addItem('written_communications', '/adm_plugins/written_communications/written_communications.php','Letters', '/icons/page_white_word.png');
</code>



===== Restrict access to roles =====

Access rights can be linked to roles. The limitation on roles can be configured in the config.php file of the plugin. To this end, the role of monitoring must match the parameter **$plg_wc_roleAccess** = 1; be activated. If this parameter is set (default: 0 for all members of the organization) then the access is limited to the roles that were defined in the config.php in the array **$plg_wc_roleArray**. Please use the Admidio function hasRole ()  to make the link only visible for defined roles.
                                            

== Link is only visible for the Webmaster and the Executive Board: ==

<code php>if(hasRole('Webmaster') || hasRole('Executive Board'))
{
   $moduleMenu->addItem('written_communications','/adm_plugins/written_communications/written_communications.php','Letters', '/icons/page_white_word.png');
}</code>
  

===== Web interface of the plugin =====


The plugin provides the option on the surface to create individual letters to a manual receiver, or  a form letter to a role within the organization. By default, the address of the creator is automatically used. But also a sender can optionally be created manually. About the CKEditor additional styles of text content can be formatted. Likewise, tables and lists are supported. It does not support the insertion of images, as well as the use of hyperlinks.

{{ :de:2.0:plg_wc_img1.jpg |}}



===== Plugin output =====

The plugin generates from a template file, which must have the format * .docx, an edited file in which all the placeholders are replaced with the user input. The plugin will start an automatic download of the created *.docx file with all sites. This makes it possible to create custom templates and letterheads.


{{ :de:2.0:plg_wc_img2.jpg |}}


===== Updates =====

If a new release is available all files and folders are replaced by newer version scripts.

===== Update to Admidio 3.2 =====

  * Since Admidio 3.2 the role "Webmaster" changed to "Administrator" and will be removed in future.
  * Add this changes to your config.php to avoid troubleshooting:

<code php>
$plg_wc_roleArray = array('Administrator');
</code> 


===== Register more profile fields in the plugin =====

Starting with version 1.1 custom profile fields can be additionally registered as desired, then they can be used automatically in a template as wildcard. If you need to provide additional profile fields they are needed to be registered in the config.php of the plugin in the array **$plg_wc_arrCustomProfileFields**. Please purpose defining the profile field, which is to be used, with the desired placeholder in the template, as a key / value pair. Note that the database fields must be written in capital letters!

== Example: ==

To define a placeholder **${userEmail}** it must be assigned to the profile field "EMAIL":
   
<code php>
$plg_wc_arrCustomProfileFields = array('userEmail' => 'EMAIL');
</code>



===== Register fixed text nodes in the Plugin =====

Since version 1.1 it is possible to define recurring text passages and texts, such as a complimentary close as fixed text nodes in the form as placeholder. These texts are recorded in the array **$plg_wc_arrCustomText** in config.php. To register your own texts please have a look at: Register more profile fields in the Plugin.



===== Create your own templates and letterheads =====

To create your own templates the plugin is linked to the Download module of Admidio. Own letter templates should not be created in the example folder "Templates" of the Plugin, because this folder is possibly replaced with updates. In the download module you should create a folder "MSWord_Templates". Such a directory once exists, this folder is to be choosen automatically and templates are loaded only from this directory. Now your own templates can be easily provided on the upload. The templates must have the format *.docx!

The old *.doc format and presentation formats are not permitted!

To be used, all placeholders are included in the demo templates **demo_de.docx** and **demo_en.docx** in the folder "templates" of the Plugin. The placeholders are all optional and can be removed at any time if a detail, eg, the date "${LetterDate}" is not required in the template.

If you have created a nice template and you want to share like a demo just contact the Admidio Team


==== History ====
//4.0.0 (06.11.2025)//
  * Compatibility with Admidio 5.0

//3.4.2 (02.11.2024)//
  * [Bug] Only show roles where the user has the right to view the membership

//3.4.1 (13.01.2024)//
  * Compatibility with Admidio 4.3

//3.4.0 (05.12.2021)//
  * Compatibility with Admidio 4.1

//3.3.3 (24.01.2021)//
  * [Bug] Output of street was not possible because of a rename of the internal field name

//3.3.2 & 3.2.2 (15.11.2020)//
  * PHP 7.4 compatibility
  * Update SimpleHtmlDom library to version 1.9.1

//3.3.1 (07.11.2020)//
  * Compatibility with Admidio 4.0

//3.2.1 (16.11.2018)//
  * Compatibility with Admidio 3.3

//3.1 (08.01.2017)//
  * Compatibility with Admidio 3.2
  * Changed folder path of the user tamplates to new organization folder names in the Download module.
  * Renamed "Webmaster" to "Administrator" in the config file ( $plg_wc_roleArray = array('Administrator'); ).

//3.0 (12.10.2016)//
  * Compatibility with Admidio 3.1
  * PHP7 ready
  * Language "de_sie" added
  * rework of Color style assignment

//2.0.1 (28.09.2015)//
  * Bugfix loading Admidio classes
  * Bugfix root path for template files
  * Internal name convention of variables and arrays

//2.0 (24.09.2015)//
  * Ready for Admidio 3.0
  * Common enhancements

//1.1 (18.08.2014)//
  * NEW FEATURES
  - Access to roles configurable in config file now
  - Customs profile fields can be registered in config file
  - Customs text fields can be registred in config file

//1.0.2 (29.06.2014)//
  * Bugfix openbase_dir settings causes errors
  * Bugfix Prefix of temporary file changed to "zip"

//1.0.1 (22.04.2014)//
  * Bugfix Wrong spelling of role class

//1.0 (13.04.2014)//
  * Modul Written Communications released