regify documentations

Documentation and help portal

Redirect to /docs/provider/5.3/provider_customizing/ (click this link if it does not do automatically)...

customizing the regify provider software

Introduction

This document shall help you customize the look and feel of your regify provider instance. Please follow the instructions and you will be sure that your customizations will continue to work in future releases of the regify provider software.

There are many possibilities to customize the look and feel of your regify provider-software. But the good customization features on the one side are having negative aspects on the other side. If you manipulate source-code files, the changes may get overwritten on the next update. To prevent this, please accept the limits of the customisation options described in this document.

The following things can get customized:

Corporate color
header area
footer area
CSS style-sheet and images
e-mail templates
meta-information
authentication page
terms and conditions
pricing information
list of blocked e-mail addresses and domains

The following things are not customizable:

the content of the pages (like login-screen, main-menu or online reading etc.)
the available place-holders in language sentences
the way the URLs are presented
layout div containers and their order

provider website layout

The above screenshot is showing you the default layout of your regify provider. The layout parts are identified by numbers:

Optional header area
This area is hidden by default. If you like to place an extra header, use the customization file _customize.css to make the header visible. The class to update is .TopNavigation { display: block; }. You can also use this to set the height, a background-image and other properties.
The code from the file codeHeader.php is executed inside of this container. If you need to place interactive content, please use PHP in this customization file.
Navigation bar
To change the logo, set the background-image for the .NavLogo div.
Content section
It displays the current content and dialogues.
Footer area
You can change the content by editing codeFooter.php.

editing php code

Do not edit any code in the appliance directly. If you like to edit PHP code in customization, please always use the built-in editor. If you are not comfortable with this, please use Copy&Paste to extract to an editor you like; and use Copy&Paste to paste back your results.

The synchronization functionality will overwrite any changes every 5 minutes. Only the built-in editors ensure that the content is also stored in the database.

The code in all *.php files (like codeHeader.php, codeFooter.php or report.php) is having full access to the complete appliance. Upon this, regify is not responsible for any damage or security leak you may cause by editing those files.
Please take care, especially if you are accessing the file system or database.

Also, the files located in the STYLE folders are accessible from the outside.

Please respect the following security rules:

Check validity of every given parameter before using on the database or filesystem. Do never ever trust data potentially entered by users!
Allways use intval() or floatval() for numeric values.
Use CheckHEX() to validate hexadecimal values.
Use prepared statements with PDO or at least CleanI() to escape strings used for database or SDK usage.
Use so() for secure html output (will encode all entities).

Website appearance

In order to customize a regify-provider, you have to login into the administration of the affected (sub)provider. You also need to have the Master or Subprovider Admin role to see these options.

You have top choose Change provider appearance and templates to enter the dialogue.

There are two tabs in this dialogue:

Edit e-mail templates
This tab offers you access to the email templates of your (sub)provider. The upper area are the language related templates. The Related Resources contain language independent template parts.
Customize provider optics
Here, all templates and files for customizing the appearance of your regify (sub)provider are managed.

To edit a file, simply click on the blue language link. The editor cares about the file and it’s location. Files without a green checkmark are in the default version (like delivered by regify). Files with a green checkmark have been changed and saved by you. A red exclamation mark points you to the fact that this file may be important to be edited by you.

Text editor

The text editor allows you to edit templates. If applicable, it will offer syntax highlighting to guide you.

If the text editor is showing the green information You are looking at the default document!, the content is not customized and you are looking at the default content.

The syntax highlighting feature is only available if the file is one of the following types: PHP, HTML, JavaScript.

Other files are simply black text.

If you have problems with the editor, please use the most recent Google Chrome or Firefox Browser.

Preview function

Some files offer a preview. In this case, simply click on the Preview tab to see a preview of your current changes. You do not need to save the file to see the preview. It is updated each time you click on the preview tab.

Logo and favicon

You have to change the Logo.png image (currently used for all client customizing)! Please upload it using the IMAGE-FOLDER functions on the lower right. It will recognize the filename Logo.png and copy it to the correct locations.

The Logo must be a PNG file with transparent background (true colour with alpha channel). The size should not exceed 240 pixels to 120 pixels. It will be scaled automatically but try to fit them as possible.

If you like to change the favicon.png of your provider, please simply upload a PNG image with the filename favicon.png using the IMAGE-FOLDER functions on the left. The image size must be 16x16 or 32x32 pixels. It will recognize the filename and copy it to the correct STYLE folder.

changing css design

In general, please use the Administration → Provider settings → contact option to set a generic color.

In addition, you can customize the appearance using the file _customized.css. Please note that we use the BULMA CSS framework. Maybe you need to check this before doing any changes.

This is to give you additional information about this file, its usage and its contents:

We strongly recommend you a tool like Firebug (for Firefox Browser) or similar to find the classes and values to manipulate on the page.
For example, if you like to change the logo in the header, please change CSS class .NavLogo. You can paste this class into _customized.css and change the values. This will overwrite the defaults and allows you to change any settings.
Some of the default CSS styles refer to images in /IMAGES. The images you can upload in the customization dialogues are copied to STYLE/MYIMAGES folder. The correct path to use your uploaded images is shown in the second column of the IMAGES-FOLDER list.

Example:

.NavLogo {
  background-image: URL('MYIMAGES/myLogo.jpg');
}

Blocking mailaddresses and domains

In order to block given mail-addresses or domains for registering at your regify-provider, you can add a file _mail_blacklist.txt. If you do not create this file, the default file mail_blacklist.txt is used to block registering of well known fake and throw-away mail-accounts.

If you like to set/change this list by yourself, create/edit the mail_blacklist.txt file and enter using this rules:

one entry per line
three variations of entry’s:
1. local@domain.ext
  → block complete mailaddress
2. domain.ext
  → block all addresses of this domain
3. .domain.ext
  → all addresses of this domain and subdomains

Templates

portal e-mail templates (notifications)

The templates are a combination of several place-holders to allow you very flexible and quick customization of all aspects of such notification e-mails.

The final e-mail body is defined by the file layout.html. This file defines the overall layout and structure of the body. The place-holders in this file are replaced by the defined values from globals_LL.html and the individual template file.

A place-holder defined in globals_LL.html is used in all templates. This is useful to define sentences and elements that are used in many templates (like signature or footer text). You can overwrite such global place-holders by simply re-defining them inside of the individual message template.

Every template contains individual place-holders filled by the regify provider. They are looking like <TAG> or [TAG]. The ones like <TAG> are using secured and escaped HTML values. The ones with [TAG] are containing links or other information which is replaced as it is. Normally you do not need to care about. Simply make sure that you use them exactly like written here in the documentation.

If any notifier template was not customized by the regify provider administrator, the default templates are used. They are designed to be as neutral as possible to allow you a quick start.

The following notification templates and their individual place-holders are used:

Notifier-Template

Usage

Aviable Place-holders

mail_registered

Registration notification for regimail, regibill premium and regipay messages.

<TID> = transaction id
<REC> = recipient e-mail address
<SUBJECT> = subject
<DAYS> = pick-up days
<TIME> = time (yyyy-mm-dd HH:MM:SS)

mail_delivered

Delivery notification for regimail, regibill premium and regipay messages.

<TID> = transaction id
<REC> = recipient e-mail address
<SUBJECT> = subject
<TIME> = delivery time (yyyy-mm-dd HH:MM:SS)
<SENT> = time the regimail was sent

mail_reminder

Reminder duration exceed notification for regimail, regibill premium and regipay messages.

<TID> = transaction id
<REC> = recipient e-mail address
<SUBJECT> = subject
<TIME> = time the reminder exceeded
<SENT> = time the regimail was sent

mail_expire

Inform the member about his expiring regimail professional membership.

<NAME> = full name of the user
<DAYS> = the number of days the membership expires
<DATE> = the date the membership expires (normally shortly before midnight)

mail_collision

Inform the member about account deletion because of a collision with other providers (rare case).

<NAME> = full name of the user
<MAIL> = e-mail address

auth_success_mobile

Send positive notification about successful authentication with return information (mobile number).

<NAME> = full name
<TIME> = date/time of authentication
<LEVEL> = level of authentication
<RET> = AuthReturnInformation (mobile number)

auth_success_standard

Send positive notification about successful authentication without specific return information.

<NAME> = full name
<TIME> = date/time of authentication
<LEVEL> = level of authentication

auth_failure

Failed authentication notifier

<INFO> = authentication information
<COMMENT> = comment / reason
<NAME> = full name of user

activation_standard

Membership activation after self registration

<NAME> = full name
<LOGIN> = e-mail address
[LINK] = URL (without <a … )

activation_mobile

Membership activation after self registration. Uses mobile phone verification.

<NAME> = full name
<LOGIN> = e-mail address
[LINK] = URL (without <a … )

invitation

Membership activation after invitation. User needs to accept the invite to get the password.

<NAME> = full name
<LOGIN> = user name
[LINK] = URL (without <a … )
<INVNAME> = name of person who invited
<INVCOMPANY> = name of company of that person
[MESSAGE] = Individual Message of the user ^[1]

invitation_pay

Membership activation after invitation into a regipay group. User needs to accept the invite to get the password.

invitation_failed

Failed invitation (duration exceed)

<INVNAME> = name of person who invited
<MAIL> = e-mail address of invited user
<NAME> = full name of invited user

confirm_mailaddress

Confirm new account e-mail address

<NAME> = full name
<MAIL> = e-mail address
[LINK] = URL (without <a … )

new_device

Inform user about a new registered device for his account

<NAME> = full name
<DEVICE> = device name
<LOCATION> = location the device came from
<DATE> = Time and date of registration
<MAIL> = Mailaddress of regify account
<OS> = Device Operating-System name

admin_auth_info

Authentication notifier used for provider stuff.

<INFO> = authentication information
<NAME> = name / description
<TIME> = date/time of the request

You do not need to change this, as no customer will ever see this template.

admin_order_info

New order to provider staff.

<NAME> = full buyer name
[TEXT] = buy text (HTML without header)
<DAYS> = days after the status is set to cancelled

You do not need to change this, as no customer will ever see this template.

pwd_reset_standard

Deliver a new password to member. (Password reset with and without mobile phone usage)

<NAME> = full name of recipient
[LINK] = URL (without <a … )

pwd_reset_mobile

Password reset request confirmation.

<NAME> = full name
[LINK] = URL (without <a … )

group_info

Inform the member about group membership

<NAME> = full name of recipient
<GROUP> = group name
<ADMIN> = full name of group administrator
<DATE> = date of regimail professional (group)

group_exclusion

Inform the member about group exclusion

<NAME> = full name of recipient
<GROUP> = group name
<ADMIN> = full name of group administrator

group_admin_info

Inform the group-administrator about his group values.

<ADMIN> = full name of group administrator
<GROUP> = group name
<CODE> = group code
<ACCOUNTS> = max. number of accounts in the group
<DATE> = sending allowed until (group)

box_invit_registered

regibox registration notification

<TID> = transaction id
<REC> = recipient e-mail address
<SUBJECT> = subject
<DAYS> = pick-up days
<TIME> = time (yyyy-mm-dd HH:MM:SS)

box_invit_success

regibox acceptance notification

<TID> = transaction id
<REC> = recipient e-mail address
<SUBJECT> = subject
<TIME> = time (yyyy-mm-dd HH:MM:SS)
<SENT> = time the invitation was sent

box_invit_reminder

regibox invitation duration exceed notification

<TID> = transaction id
<REC> = recipient e-mail address
<SUBJECT> = subject
<TIME> = time the reminder exceeded
<SENT> = time the invitation was sent

box_full_warning

regibox fill level warning to both user and owner

<NAME> = full name of the recipient
<OWNER> = full name of the box owner
<PERCENTAGE> = fill level incl. % sign like “90%”

¹	This message will come escaped, including a surrounding DIV container using the CSS-class “quote”. This class should be defined in layout.html.

There are a few standard place-holders available in all templates:
[PROVIDERURL] → Full URL to the regify provider portal including the last slash
[PROVIDERHP]→ Full URL to the provider homepage (eg company HP)
<PROVIDERNAME> → Name of the regify provider portal
<SUPPORTADDRESS> → E-mail address for support
<SUPPORTPHONE> → Phone number for support

They are replaced during sending by the corresponding values of the current (sub)provider settings (defined in the portal (sub)provider administration).

template language information

The notification template names in the table above are ending with a language identifier. Currently, the identifiers are:

DE German (Deutsch)
EN English
FR French
CN Chinese

regify mailing template (regify_default_message.html)

This template is used by the regify standalone client, the regify AddIns (like MS Outlook or Lotus Notes) and by the web interface for online creation of regify files and e-mails.

If a user creates a regify file, the body message will be taken from the file regify_default_message.html in the customization area. If the file does not exist, the default template will get used. We strongly recommend to, at least, save this file once to get done.

This file needs to start and end using <html> and </html> and needs to contain all style information. We recommend to use CSS styles and html, but no images.

Inside this template, there are two place holders:

@SENDERNAME@
This place holder will get replaced by the name of the sender.

@SENDERADDRESS@
This place holder will get replaced using the e-mail address of the sender.

regibox invitation template (regibox_invitation.html)

This template is transmitted to the regibox manager software and used for invitations. The regibox manager replaces the following placeholders by individual values during sending time with local values:

[PROVIDERURL]	Gets replaced by the URL of the inviting users regify provider.
[PROVIDERHOMEPAGE]	Is replaced by the homepage URL of the inviting users regify provider.
[MESSAGE]	This is replaced with the individual message the inviting user has entered during invitation.
[NAME]	This is replaced by the name of the invited user (entered by the inviting user).
[SENDER]	This is the name of the inviting user.
[TITLE]	The title of the regibox (name).
[LANGUAGE]	The language of the inviting user (currently DE, EN or FR).

[PROVIDERURL]

Gets replaced by the URL of the inviting users regify provider.

[PROVIDERHOMEPAGE]

Is replaced by the homepage URL of the inviting users regify provider.

[MESSAGE]

This is replaced with the individual message the inviting user has entered during invitation.

[NAME]

This is replaced by the name of the invited user (entered by the inviting user).

[SENDER]

This is the name of the inviting user.

[TITLE]

The title of the regibox (name).

[LANGUAGE]

The language of the inviting user (currently DE, EN or FR).

On provider side, the standard placeholders are applied described in chapter portal e-mail templates (notifications)).
For example <SUPPORTADDRESS>.

Best will be to use html entities as much as possible to avoid any problems with special characters! If you are offering your service in multiple languages, please take care that everyone is able to read your template. As in our example, you may even insert different languages into the same template.
Always trigger and test the changed messages to make sure they work.

Customizing authentication

The authentication-dialog can get adapted to your needs using a JSON file that describes the dialog and the available fields. If the dialog is confirmed, all the collected data is part of the authentication request.

The format of the JSON file follows the regiForm specification which is available only to regify staff. If you like to adapt your authentication form, please contact regify support for help.

To fill a field with a default value from tblusers, you can set the data attribute. On form loading, the values will become pre-filled with this data.

The following name attributes are mandatory or have special meaning for the authentication form:

FieldName Description

FieldName	Description
OwnerType	Mandatory, must be person or organisation.
AuthCheckName	Optional name to check during validation (usually from database). If not set, it uses IdentityName.
AuthCheckPhone	Optional phone number to check during validation. If not set, it uses UnlockReturnInformation.
IdentityName	Mandatory, name used for display in identity-file (usually the full name).
IdentityOrganisation	Organisation name used for display in identity-file. Mandatory if OwnerType is organisation.
PhoneTime	Optional time to make a call (eg if provider has to call back). It is displayed to provider staff during validation. Format should be `HH:MM` in 24 hour format). Hint for validation with RegEx: `^(2[0-3]\|[01]?[0-9]):([0-5]?[0-9])$`
UnlockReturnInformation	Mandatory information for sending unlock-code to customer (usually the mobile number). Do not use an email address because sending unlock codes by email is forbidden!
SubmitData	This filed is optional but recommended. It must contain HTML text about what to do to get authentication (eg "send us id document"). If it is set it is displayed again after authentification has started and later helps the customer to finish his authentication request. It is meant to show the user the information about where to send his authentication data or what the next steps are.

OwnerType

Mandatory, must be person or organisation.

AuthCheckName

Optional name to check during validation (usually from database). If not set, it uses IdentityName.

AuthCheckPhone

Optional phone number to check during validation. If not set, it uses UnlockReturnInformation.

IdentityName

Mandatory, name used for display in identity-file (usually the full name).

IdentityOrganisation

Organisation name used for display in identity-file. Mandatory if OwnerType is organisation.

PhoneTime

Optional time to make a call (eg if provider has to call back). It is displayed to provider staff during validation. Format should be HH:MM in 24 hour format).

Hint for validation with RegEx:
^(2[0-3]|[01]?[0-9]):([0-5]?[0-9])$

UnlockReturnInformation

Mandatory information for sending unlock-code to customer (usually the mobile number). Do not use an email address because sending unlock codes by email is forbidden!

SubmitData

This filed is optional but recommended. It must contain HTML text about what to do to get authentication (eg "send us id document"). If it is set it is displayed again after authentification has started and later helps the customer to finish his authentication request.

It is meant to show the user the information about where to send his authentication data or what the next steps are.

Checklist

This list shall help you to ensure that you complete your customization properly. Please check the individual options:

Mandatory

Insert your adapted terms of use into agb_SS.html (SS is the language).
Update your pricing and payment options in conditions_SS.html (SS is the language).
Change your logo using the file _customized.css.
Upload your Logo.png for the client software.
Modify or change the regify default mail template.
regify_default_message.html
Modify or change the regibox invitation mail template.
regibox_invitation.htm
If shop is used, set or update your shop prices in (sub)provider administration (must by done by a main provider administrator).
Check all customizable files still marked with a red exclamation mark!

Optional

Select your corporate color in Provider settings.
Modify codeHeader.php, codeFooter.php, meta.php for your needs.
Modify or change the overall look of any portal mailing templates using layout.html.
If you like to offer authentication, adapt the auth_form.json to your needs by asking regify support for help.

Appendix

Manipulating language text blocks

All language blocks are defined internally using the $lang array. Here is an example:

<?php
$lang[0]["FR"] = "";
$lang[0]["DE"] = "";
$lang[0]["EN"] = "";
$lang[0]["CN"] = "";
?>

Upon every update or upgrade, this file will get updated very likely. Language blocks may get added and removed.

Upon these blocks are arrays, they can be overwritten later in code. This is the key for changing language blocks in your regify provider.

To change a language block, please go to the customizing dialogue of the web-administration and adapt the file codeHeader.php like in this example (changing ID 123):

<?php
  global $lang;
  $lang[123]["FR"] = "nouveau texte";
  $lang[123]["DE"] = "neuer Text";
  $lang[123]["EN"] = "new text";
  $lang[123]["CN"] = "新案文";
?>

In order to identify the ID you want to change, log-in using SSH and look into the file /opt/provider/REGIFY_INCLUDE/funcLanguage.php. Do not change anything in this file, it will get overwritten with the next update. Just identify the ID you need to change and use the above method in codeHeader.php.

The disadvantage of changing language defaults is that you have to check your language blocks every time the funcLanguage.php has been updated (every update of the provider software).

You may need to adapt your text settings to new functions or changes by regify. Therefore, regify strongly recommends to not change more than up to 10 sentences to keep the efforts for an update as less as possible.

If you think that more sentences need enhancement, please tell us your wishes or why there is a problem for you. Maybe all regify providers can profit by the changes and we update this for the next release?

Individual reports

It is possible to trigger individual reports. The regify-provider try’s to find a _report.php file in all subproviders STYLE folders every 5 minutes. If such a file is found, it will be executed using the PHP interpreter.

You can/must edit this file using the Change provider optics and templates dialogue of the web administration menu. Upon the first click on this report.php link, the system offers you an example of a working report script that is executed every last day of the month at about 12:00. This example may get adopted to your own needs. If you click on save, the file _report.php will automatically be saved at the correct place.

In case you do not have any programming experience, please ask regify for support or an offer.

The code in all *.php files (like codeHeader.php or report.php) is having full access to the complete appliance. Upon this, regify is not responsible for any damage or security issue you may cause by using those functions.

Public available PHP functions

There are a lot of appliance functions available for you in your own routines (if you require_once("init.php");. Here are the most helpful and important ones:

GetLanguage()

Returns the current language code (“DE”, “EN”, “FR” or “CN”).

GetFromHash(Hash, Key, Default)

Secure access to hash (array, maps etc) not triggering errors or notices in case the key does not exist.

$example = GetFromHash($_GET, "p", "default");

CleanI(Original)

Returns a clean and database-escaped version of the given Original.

FormatPrice(Value)

Returns the given value as a currency formatted price for the current session language. Eg, a value of 3.6 will be returned as “3,60 EUR”.

GenerateCode(Length)
GenerateNumericCode(Length)

Both functions returning a random code. GenerateCode() returns a code consisting of upper-case, lower-case and numbers with Length digits. GenerateNumericCode() returns only a numeric code with Length digits.

GetURL(URL)

Returns the content of a given URL (uses provider settings for proxy, gateway etc).

CheckHEX(Value)

Returns TRUE if the given Value is a valid hex encoded one.

so(text)

Is for “secure output” and can get used to output any values as secure HTML (entity encoding). Use this to prevent XSS attacks.

GetScriptName(withParams = false, withOutExtension = false)

Returns the name of the called script (eg pay.php). Set withParams = true to also get the parameters. Set withOutExtension = true to suppress the extension (.php).

Calling sign-up page with predefined values

You can use POST values, if you like to call the members sign-up page with some predefined values. The following example shows you how to pre-fill the coupon code field txtCoupon with the value 123456 on the regify demo portal:

http://portal.regify.com/signup.php?txtCoupon=1234

You simply need to change the URL and submitted values. To find the possible field names, please have a look into the source of the page or use tools like FireBug for Mozilla Firefox.

Special field for pre-defining Sales-ID value:

You can define a hidden POST value with the name hidSID. If you provide any information in here (string, max 250 characters), it is automatically stored into the tbluser.SalesID field of the customer that registers.

Customizing pay.php depending on url parameter

Normally, the pay.php gets it’s configuration from the (sub)providers configuration and _customize.css. If you need to have a more sophisticated customisation you can use an additional parameter like in this example:

https://provider/pay.php?p=1

In order to use such an extra parameter, please use customization of your regify provider to add the following code to meta.php:

<?php
$scriptName = GetScriptName(false, false);
if ($scriptName == "pay.php" && GetFromHash($_GET, "p") == 1) {
    echo "<style type=\"text/css\">";
    echo "#pay-navigation { background-image: url('MYIMAGES/someImage.jpg') !important; }";
    echo "</style>";
}
?>

This example shows you how to set the background image in case of p=1. This can get used to change the image or change colors depending on the customers need.