PGVWiki - User contributions [en]

PGVWiki:Contributing

2010-06-08T02:24:43Z

GhostInTheMachine: /* Skills Required To Help */

[[image:Nuvola_apps_korganizer.png|right|100px]]The [[wiktionary:ethos|ethos]] of a wiki means that the whole community can contribute, irrespective of beliefs or opinions. The result is a wiki that meets the consensus and needs of the community, leading to a more useful and long lived article.

==Skills Required To Help==

You ''don't'' need:

* Previous Wiki experience - you add the content, we'll format it nicely!
* Programming skills
* Experience with PhpGedView - but helpful

However, you ''do'' need:

* Enthusiasm

==What Needs To Be Done==

Here are some generally useful pages to visit if you want to know what needs to be done on the PGVWiki.

; Stub Articles
: You should see the [[:Category:stubs|list of stub articles]] - these are short "stubby" articles that need content adding to make them more useful. Selecting an item from the category list will take you to the relevant page which needs attention.
; To-do Lists
: You should see the [[:Category:To do|list of articles]] containing To-do lists. Selecting an item from this category list will take you to the relevant '''talk''' page for the article that needs attention. The actions required will be listed.
; PGVWiki Page translations
: Please see the [[PGVWiki:Translations|PGVWiki Translations]] page for details of what to do and how to do it.

A new [[:Template:todo|todo template]] has been created which allows PGVWiki users to add todo items to a list for ''ANY'' page in the PGVWiki. Information on how this template can be used is available [[:Template:todo|here]].

The rest of this article (below) remains in place for the time being until these tasks are added to the appropriate articles in the form of a to-do list.

----
'''Tasks''' ([[PGVWiki:Tasks|Full list .....]])
* Place answered FAQs from Sourceforge into FAQ section
* Translation of PGVWiki pages. See the list of [[Special:Withoutinterwiki|pages without language links]].
* Move PhpGedView help text to User Guide
* How to integrate PhpGedView with a Content Management System

[[PGVWiki:Tasks|Full list .....]]

[[Category:PGVWiki|Contributing to PGVWiki]]

[[da:PGVWiki:TODOlist]]

Database import/export/conversion utility

2010-06-08T02:22:38Z

GhostInTheMachine: /* Upgrading */

The capability to backup the PhpGedView database tables is an important feature for security of your data The utility described here is still in development (as of January 2009) and is not yet part of an official release. If you are cautious, however, you can protect your data using this tool, and also improve handling of non-latin character searches and sorting by converting database to UtF-8.

==Overview==
The utility has 3 simple functions:
* Export (individual database tables, or all of them). The table data are stored as SQL files in the index directory, and can be used to restore a corrupt database (but with table structure intact). During export, a conversion is made to arrive at readable, UTF-8 encoded text.
* Import. The saved files are used to re-populate the database tables.
* Conversion. The actual database (works for MySQL only ) tables are converted from default (8 bit latin) to UTF-8 encoding.

==Where to get it?==
The utility db_export.php is currently in [https://sourceforge.net/tracker2/index.php?func=detail&aid=2318005&group_id=55456&atid=477081 SourceForge tracker]. After retrieving it from the tracker, copy it to main (root) directory of phpGedView.

== How to use it?==
The instructions below are from the tracker, written by Greg Roach, with minor adjustments based on email exchange.

This module allows you to export and import the contents of your database
to text files containing SQL scripts. This is not the most compact or
efficient format, but it simple, reliable and portable. If you want
efficient, there are much more appropriate tools available.

A separate file is generated for each table, and each can be
imported/exported separately. Although an "import all" option is provided,
you may find that your server time limits prevent this from completing.

Files are created in the index directory, so this can be useful for
creating backups of your system. They can also be useful for transferring
data between different databases, for example, between sqlite on your home
PC and MySQL on your webserver.

For MYSQL users only, there is also an option to convert your database
tables from latin (single byte) encoding to UTF8 (multibyte) encoding.
This change is necessary to allow the database to perform case-insensitive
searching of letters containing diacritics and non-latin character sets.

By default, PHP communicates with MySQL in latin text. When PGV sends UTF8
text to the database, MySQL treats multibyte characters as a number of
"extended ascii" characters, and converts these characters to UTF. This
incorrect encoding (and possible double-encoding) is what prevents the
database from searching data. Luckily, the reverse encodings take place
when we fetch the data back, so apart from the wasted conversion effort,
this process is transparent to PGV.

In order to use UTF8, we need to tell MySQL that we are using UTF8.
However, to do this on an existing database means that we will fetch
old/existing data using different conversions to those used to store it -
and our data will be corrupted.

We therefore need to convert our data before changing the way we talk to
MySQL. The steps to be taken are:

# Export all the tables
# Convert all the tables to utf8
# Update your configuration files as follows:
#* For version 4.2 (anything above 4.1.6) edit config.php to set $DB_UTF8_COLLATION=true;
#* For versions 4.1.6 and below, edit file includes/functions.php and uncomment the line(s) dbquery("SET NAMES 'UTF8'");
# import all the tables

==Notes==
NOTE: If your login name contains non-ascii characters, then you *may* get
logged out between steps 3 and 4. To prevent this, create an admin account
with an all-ascii username before starting.

#If you have the default MySQL configuration (latin tables and latin communication), then steps 1 and 4 are optional. However, we can't reliably detect this configuration, so unless you are certain, don't skip them. Also, running step 2 repeatedly may corrupt data, meaning you do need to run steps 1 and 4. In fact, unless you have a very good reason (e.g. you know exactly what you are doing and have large tables on a server with very low execution time limits), then don't skip these steps.
#If you have low server time limits, then it may not be possible to import some of your large tables before it times out. These tables are likely to be your gedcom-data tables. They can easily be reconstructed by reimporting the gedcom.
#This procedure can destroy your data and prevent you from logging in. Do not do it unless you understand what you are doing. Even if you know what you are doing, you should make a backup before you start.

==Upgrading==
If you upgrade phpGedView to new version after making the conversion to UTF-8, make sure that you make the changes to the configuration files as described above before you start using phpGedView, otherwise the data may get corrupted.

Place Maps

2010-06-08T02:18:39Z

GhostInTheMachine: /* Image File */

==Background==
Place maps are displayed in two places in the PhpGedView software package:
<ul>
<li>In the Place Hierarchy under the Lists menu.
: Place Map will be displayed here only if you are not using GoogleMaps functionality. GoogleMaps, if enabled, displays a region map in its place, depending on its coordinates in the GoogleMaps table.
<li>In an editing window, when adding a location to an event if the Gedcom has this option enabled.
: To enable this feature, Log in as the administrator, Click "Manage GEDCOMS and edit Privacy", Click "Edit" for the configuration file of the Gedcom you wish to change, Expand the "Edit Options", and set "Split places in Edit mode" to "Yes".
</ul>
Each full map should have three files.
* The image must be in gif format.
* A htm file should contain the html code for the image map to allow the counties/provinces to be selected with a mouse click.
* A txt file should contain the list of all sub-areas in the map to allow autocompletion in the events editor.

==Steps==
If you are creating a new top level (Country) image map, you will first have to find the three letter country code for the country. The letters are defined by the ISO in IS0 3166 alpha-3. The UN has an up-to-date copy in their [http://unstats.un.org/unsd/methods/m49/m49alpha.htm Statistics Department]. Create a new directory with these three letters as the name in the places directory of your PhpGedView installation.

If you are creating a map of a state or province of a country which has already been made, you will need to name all documents with the format COU_State.xxx where COU is the three letter country code, State is the name of your state or province and xxx is either htm, gif, or txt.
===Image File===
Find a good image of the country or state you wish to add, copyright free images are best to use if you can find them. Open the file in a good image editor and resize it to less than 400 pixels wide. Create a new raster layer and trace the countries borders and the borders of the counties within. After deleting the original layer, you should be left with a hand traced copy of the original. Now you can add some colors to the counties and text label the names if you like. The choice of colors when coloring a map is up to personal preference. Some color all counties the same color, and some color counties so no two adjacent counties have the same color. If attempting the latter, you'll need to select four complimentary colors. All maps can be colored with a minimum of 4 colors. Finally, select all areas outside of the country and set them to a transparent color. Save the image in gif format.

===Text File===
The text file is just a list of all the regions within this map. If you are creating a US state map, this will be a list of the counties within that state. Each county must be on a new line of the text file.

===HTM File===
The htm file should be in the following format with the proper county names inserted:

<map name="COUNTRY_State">
<area shape="poly" coords="" href="javascript:setPlaceState('County 1');" alt="County 1" title="County 1">
<area shape="poly" coords="" href="javascript:setPlaceState('County 2');" alt="County 2" title="County 2">
.
.
.
</map>

The easiest method to create this file is to use the text file you created above. If you have a UNIX or LINUX system, open the file in vim and type the following:

:%s/$.*$/<area shape="poly" coords="" href="javascript:setPlaceState('\1');" alt="\1" title="\1">/g

This regular expression will replace each line in the file with the county name inserted correctly in the area tag. Next, add the opening and closing <map> tag and save it as COU_State.htm

The last step is to match the coordinates of each county to the county name. Use your image editing software to get the coordinates of the corners of the counties. Type the pixel numbers into the coords attribute of each county in the following format:
coords="X1,Y1,X2,Y2,X3,Y3,..."

==Limitations and Code Modifications==
The events editor only displays country level maps. The place hierarchy will display two levels of maps, country and province, or country and state for example. To allow the place hierarchy to display a third level, add the following code to placelist.php for version 3.3.5:

Change line 132 to

if ($level==1 || $level==2 || $level==3) {

change the else block at line 158 to:
<code>
else {
if ($level==3) { // added to support county level
$level2 = str_replace("/ /","-", $parent[1]);
$level3 = str_replace("/ /","-", $parent[2]);
$mapfile = $maplang . "_" . $level2 . "_" . $level3 . ".htm";
if (!file_exists(filename_encode($mapfile))) $mapfile = $imgfile . "_" .$level2 . "_" . $level3 . ".htm";
if (!file_exists($mapfile)) $mapfile = $imgfile . ".htm";
$imgfile = $imgfile . "_" . $level2 . "_" . $level3 . ".gif";
$maplist = $country . "_" . $level2 . "_" . $level3;
$mapname = $parent[1];
}
else {
$level2 = str_replace("/ /","-", $parent[1]);
$mapfile = $maplang . "_" . $level2 . ".htm";
if (!file_exists(filename_encode($mapfile))) $mapfile = $imgfile . "_" . $level2 . ".htm";
if (!file_exists($mapfile)) $mapfile = $imgfile . ".htm";
$imgfile = $imgfile . "_" . $level2 . ".gif";
$maplist = $country . "_" . $level2;
$mapname = $parent[1];
}
}
</code>

To allow the event editor to display second level maps:

==Related Pages==

[[Users Guide:Place Hierarchy List|Hierachial Place List]], [[Administrators Guide:Configuration File#Split Places in Edit Mode|Administrators Guide]], [[Users Guide:Place data|Entering Place Data]]

[[Category:How To]]