HTML Athlete SDK

Quick overview

Welcome to HTML Athlete SDK and thanks for downloading it. This article serves quick starter for developers who intend to embed HTML Athlete's compress routines into their applications. The content of this article is as follows:

So let's get started.

HTML Athlete instances

Let say at the beginning, that the break down structure of this SDK was motivated by the object oriented programming. If you are familiar with it, you are advantaged. For those that are not I recommend the book Object-Oriented Programming (Textbook Binding) written by Peter Coad and Jill Nicola. But don't worry if you don't manage to get it. As you will see in turn, working with this "just-a-few-functions" SDK is indeed quite simple and you will not need to exploit any advanced knowledges. Really, I swear!

Before using any of HTML Athlete functions in your programs you must first create an instance of it. An instance is an internal descriptor which maintains information about compression characteristic set. You don't need to know more about internal structure. SDK function which serves for instances creation is called ATHCreateInstance.

Note that the prefix "ATH" is involved in every function name of HTML Athlete SDK. It serves for distinguishing them from other functions, maybe from other SDK's.

If the creation goes successfuly, the ATHCreateInstance function returns the ATH_RESULT_OK constant (see the "ATH" prefix again). Otherwise it returns another constant representing the reason of failure. Once you have created at least one instance, you can use any other SDK's function putting the instance as one of its parameters. If you have been object-oriented programming before maybe you can feel (without seeing any line of code), that what is presented here is no pure object oriented programming, but something that is sometimes refered to as pseudo-object-oriented programming or object-oriented programming substitute, because we are still moving in procedural programming.

Example. In this example we create an instance, change one of its properties and immediatelly we destroy it, just in order you see what is going on. For the code not to be too inflated we omit all switches which test whether everything is going right or not.

First for Delphi/Pascal users:

// remember, that you must include the athsdk.pas in the USES clause
uses athsdk;
// a variable for storing the instance
var myInstance:ATHInstance;
// first we create an instance; recall that we don't test any error codes and hope that everything is going right
ATHCreateInstance(myInstance);
// now we have myInstance containing an instance of HTML Athlete; we change the one of its properties
ATHSetProperty(myInstance, ATH_PROPERTY_BEEP_WHEN_FINISHED, false);
// finally we destroy our instance
ATHDestroyInstance(myInstance);

And now the same once again but for C/C++ programmers:

// remember, that you must include the header file in order to get accessed HTML Athlete's functions
#include athsdk.h
// the essential difference between this code and the one above is in calling the following macro
// in order to get initalized the HTML Athlete SDK's dynamic library
ATH_LOAD_LIBRARY("athsdk.dll")
// a variable for storing the instance
ATHInstance myInstance;
// first we create an instance; recall that we don't test any error codes and quiet hope that everything is going right
ATHCreateInstance(&myInstance);
// now we have myInstance containing an instance of HTML Athlete; we change the one of its properties
ATHSetProperty(myInstance, ATH_PROPERTY_BEEP_WHEN_FINISHED, false);
// finally we destroy our instance
ATHDestroyInstance(myInstance);
// don't forget to properly disconnect from SDK's shared library!
ATH_FREE_LIBRARY

End of example

As you can see it is indeed quite simple to use HTML Athlete SDK. Maybe you are asking yourself what is all the flam around instances good for. This approach was chosen because of its hidden future potential like enabling the parallel processing on multiprocessor machines or adding such a natural think like HTML Athlete setting dialogue. even by now you can exploit them for example by creating multiple compression profiles (see also a note in the following paragraph).

If you have cought the thoughts about instances, you are ready for your first complete run of HTML Athlete compression routine.

First complete example

In this paragraph you will create step by step your first complete and hopefully successfully running HTML Athlete instance. You can continue writting the example from the end of the previous paragraph or starting once again with a blank document. Note, that in this example we consider you are using Bloodsheet DevC++ and creating a command line program.

In our example we will compress a file containing a HTML document we have already seen in paragraph "Whom is HTML Athlete targeted to?". This document is stored in bin folder of your SDK under the name example.html. Taking a look at the content you can see, that the document includes beyond a lot of HTML also in-line Cascade Style Sheets (CSS) and in-line JavaScript (JS). We want both CSS and JS compress. View the file in your web browser. A quite curt gray page appears, but for demonstration purposes it is sufficient.

Now let start our work. The above all first think you need to do is to include the header file into your project. You can do this by writting the line:

#include "athsdk.h"

Now all constants and types were set available to you. Everything is ready but the functions. But this can get right very simply by calling the following macro.

ATH_LOAD_LOBRARY("athsdk.dll")

After having the header file included and DLL function initialized you must create a variable maintaining an instance. Put the following line immediately after main function header:

ATHInstance myInstance;

You have declared a variable by which you will refer your instance. Let create one but now with all the flam about result constants:

// if it happens to fail to create an instance, it is no longer worth to run the program and we exit with return code 1
if (ATHCreateInstance(&myInstance) == ATH_RESULT_ERROR_CREATING_AN_INSTANCE){
	return 1;
}

If everything goes right, the myInstance variable will contain an identifier to your instance. Without setting up your instance, it will always contain a default properties values. Please refer to the ATHCreateInstantion function description to see which value is every property set up. Once you do so, you will discover that in-line compression of both JS and CSS is disabled. Therefore the next steps are to enable it. To enabling or disabling instance properties serves the function ATHSetProperty:

// first we enable the JS
ATHSetProperty(myInstance, ATH_PROPERTY_JS_COMPRESSION_ENABLED, true);
// than the CSS
ATHSetProperty(myInstance, ATH_PROPERTY_CSS_COMPRESSION_ENABLED, true);

Taking a look at the instance's defaults you can also see that events like onload or onmousemove are protected. That means that HTML Athlete keeps commas around values of these parameters. When you look back at the document we are preparing to compress, you will see that the only event is onload in the body tag and that these commas are meaningless. In most cases you can always put the following line in your code.

// we disable the events protection in order to lower the outgoing document size
ATHSetProperty(myInstance, ATH_PROPERTY_PROTECT_EVENTS, false);

Of course, exceptions of rule can arise, which means HTML Athlete can wrong recognize meaningless commas forcing the page to fail while viewing in browser. You have two options you can take. First, you can omit the above line. Second, you can create another instance having this property set to default value (recall, that it is true, enabled) and compressing the page by the second instance.

Finally, in our document appear some comments, which we also want to get lost, so we set up one more property:

// we enable deleting the HTML comments in our document
ATHSetProperty(myInstance, ATH_PROPERTY_DELETE_HTML_COMMENTS, true);

You can set also other properties, please refer to ATHSetProperty function documentation.

You have just set HTML Athlete's instance so the above seen file content to be best compressed. Now you are ready to start the process of compression:

// start the given file compression
switch (ATHCompressFile(myInstance, ATH_CONTENT_TYPE_HTML, "example.html")) {
	case ATH_RESULT_OK:break;
	case ATH_RESULT_CAN_NOT_READ_FILE:
		// actions taken when document could not be read
		break;
	case ATH_RESULT_CAN_NOT_WRITE_FILE:
		// actions taken when document could not be written to
		break;
	default:
		// unknown error arose, maybe the content is incorrect
}

Note, that an unknown error can occure when the incoming document is incorrect - for example unfinished multiline comment in JS or CSS and so on.

When the input is incorrent, you can not expect a correct output!

Let's make another note, that there exists another compression function called ATHCompressRawData, however, its description overlaps the scope of this example and you are refered to documentation for complete information about it.

When your program flow comes at this point, the document is already compressed as well as saved and there is no longer need to keep the HTML Athlete instance in the memory, so including the following line we simply destroy it:

// we destroy the no longer needed instance
ATHDestroyInstance(myInstance);

Don't forget to call the following macro when your application no longer exploits the HTML Athlete's compression routines (which is certainly when it is ending).

ATH_FREE_LIBRARY

Copy the athsdk.dll into your project directory. Do the same with the bin\example.html file and then build and run your application. If nothing went wrong the HTML file should take only 477 bytes on the disk! When this is not the case, set some actions in place of comments in switch of ATHCompressFile in order to see where is the bug (put some printf).

Note that during execution an warning window box appears informing you about unauthorized use of HTML Athlete SDK. You can get it off using the ATHAuthorizeInstance function, please refer its documentation.

However, that's it! You have created an instance, set its properties, compressed by it your file and finally destroyed it.

Contact me!

Thanks for using HTML Athlete compression routine. However, when you get in trouble while using it, send me an e-mail and try to describe your found bug as closely as possible.

If you become a glad user of HTML Athlete, I would be also thankful if you could forth propagate this program by laying its icon somewhere on at least one of your compressed pages. Here you can see the whole HTML code so just copy it:

<a target=_blank href=http://nestorovic.hyperlink.cz/html/en/athlete.html alt="Page compressed by HTML Athlete">
	<img src=http://nestorovic.hyperlink.cz/download/athletfree/icon.gif>
</a>

My e-mail: thom dot as at centrum dot cz [ thom.as@centrum.cz ]

EOF