The Erasmus Project

Resources for developers of Bible software

Resources for the Erasmus Project Prayer Journal (EPPJ) Initiative

If you are interested in developing an EPPJ client app, this page contains some useful resources.

click here to read the EPPJ specification.

If you have an EPPJ client that you would like to list on this site, contact us.

Sample Implementation Code

We have provided code that implements the parsing of EPPJ files which you can use as a start for you app. Note that this code does not provide:

  1. a user interface, since that is not part of the specification.
  2. processing to determine which prayer requests to display on a given day (date processing is platform-specific).
  3. obtaining the files from the internet, which is also platform-specific.

Implementations:

C++ eppj.hpp eppj.cpp

C# eppj.cs

Object Pascal (reference implementation): eppj.pas

Implementing a client using the above code

Because obtaining data from the internet is platform-dependent, that functionality is separate from the provided code. However, integrating the code with your own internet access code is easily done. Create a descendent class of TURL_Source, which overrides and implements the Get_URL method. This method takes a string containing a fully-qualifired web address (including HTTP: or HTTPS:) and returns the contents of the file in the URL. If there is an error (such as a 404 "not found", 500 "server error", connection timeout, etc.), return an empty string. Once this class is finished, write code to create an instance of this class and pass that instance to the Load_EPPJ function along with the URL for the eppj file (for instance, "https://mysite.com/eppj.txt"). Load_EPPJ is the main function to use - it handles redirection and load-balancing. Parse_File can also be called directly if the eppj.txt file has already been downloaded. Note that in the C# code, both of these functions are methods of the TEPPJ class.

Here is some pseudo-code that illustrates the process of using the supplied code to obtain and display a prayer list:


obtain url of prayer list
construct instance of descendant of TURL_Source
create list by passing TURL_Source descendant instance and url to Load_EPPJ
for i=0 to count - 1
    get item with index i from list
    if today's date is a match with item's Startdate and enddate, display the item information

The following is an example in C++ of the above pseudo-code. DateMatch is a function you must provide to compare the prayer item's start and end date with the current date. DisplayPrayer is a function you must provide to display the prayer information properly within your app's UI. TWebSource is your descendant of the TURL_Source class.


TWebSource* WebSource = new TWebSource();
bool Redirection = FALSE;
bool Load_Balance = FALSE;
TEPPJ_File* ef = Parse_File(url, WebSource, Redirection, Load_Balance);
if(ef->File_Type == FT_List)
{
    TPrayer_List* PL = (TPrayer_List*)ef;
    for (int i = 0; i < PL->Count(); i++)
    {
        TPrayer_Item* PI = PL->Get_Item(i);
	if(DateMatch(PI))
        {
            DisplayPrayer(PI);
        }
    }
}
delete WebSource;

Function Reference

Load_EPPJ
Format:

Result = Load_EPPJ( URL, Source, Redirection, Load_Balance )

Parameters:
URL
A string containing the fully-qualified web address of the eppj.txt file.
Source
An instance of a TURL_Source descendent that can be used to obtain a file from the internet.
Redirection
FALSE should be passed for this argument.
Load_Balance
FALSE should be passed for this argument.

Result:
Returns an instance of a descendent of the TEPPJ_File class, or NULL if there was an error (such as a null URL being passed).

Description:
This function will obtain the file specified in URL and process it. It handles redirection and load-balancing if the passed source operates correctly.

Parse_File
Format:

Result = Parse_File( Contents, Source, Redirection, Load_Balance )

Parameters:
Contents
A string containing the text of an eppj file.
Source
An instance of a TURL_Source descendent that can be used to obtain a file from the internet. This is required to handle redirection and load-balancing.
Redirection
FALSE should be passed for this argument.
Load_Balance
FALSE should be passed for this argument.

TPrayer_List class
This class is used to encapsulate an entire prayer list.

Methods:
Add( Value )
Parameters:
Value

A TPrayer_Item instance to add to the end of the list.
Result:
An integer index indicating what position the item is in the list.

Count()
Parameters: None
Result:
An integer result indicating the number of prayer items in the list.
Delete( Index )
Parameters:
Value
An integer value indicating which prayer item to delete from the list. The index is removed and the count is decremented.
Result: None

Get_Item( Index )
Parameters:
Index
The index of the prayer item to return.
Result:
An instance of the TPrayer_Item for the prayer item at the given index. If index is less than 0 or >= the total count, NULL is returned.
Set_Item( Index, Value )
Parameters:
Index
The index of the prayer item to set.
Value
A TPrayer_Item instance to replace the item at the given index.
Result: None

Serialize( Include_Password )
Parameters:
Include_Password
Pass true to indicate that the serialized result contains the password value. Note: This should always be false when creating a eppj.txt file for online distribution. Passwords should never be included in online eppj.txt files.
Result:
A string containing the contents of an eppj.txt file that defines the current prayer list.

Instance data:
File_Type
This data is the FT_List (a TFile_Type) for this class.

Password
A string consisting of the password for this prayer list. This is reserved for programmer usage.

URL
A string containing the URL this prayer list was obtained from.

TPrayer_Item class
This class is used to encapsulate a prayer item.

Instance data:
Answered
A string consisting of how/when this prayer was answered for this item.

enddate
An string indicating the ending date. See Startdate for more details.

ID
A string consisting of the unique ID for this prayer item.

Hidden
A boolean indicating whether or not this item is hidden. Intended for use by the client app.

Image
A string consisting of the URL for an image to include with this prayer item.

More
A string consisting of the URL for more detailed information for this prayer item.

Parent
The instance of the TPrayer_List that contains this prayer item.

Text
A string consisting of the text for this prayer item.

Title
A string consisting of the title for this prayer item.

_Set
A string consisting of the set that this prayer item belongs to.

Startdate
An string indicating the date (or start date for a date range).
The date specification is of one of the following formats:

YEAR/MM/DD
MM/DD/YEAR
DAY

where "YEAR" is a 4-digit year value (such as "2024"), "MM" is a 1 or 2 digit month value (from 1 to 12), "DD" is a 1 or 2 digit day value (1-31), and "DAY" is a day-of-the-week (0=Sunday, 1=Monday, ..., 7=Saturday). If a month, day, or month/day combination is invalid, the client will ignore this tag. Example:

12/25/*

This indicates Christmas Day of current year.
Likewise, a day specification serves as a wildcard meaning that day in the current week (eg, every Wednesday). Any form of wildcard implies both a start and end date for a single day.

Tag
An integer value entirely for developer use.

Urgent
An string indicating details of urgency associated with this prayer item.