DirectAdmin Skins Tutorial
The Basics
Welcome to DirectAdmin Skins 101. This tutorial is designed to get you started on your way to implementing your first DirectAdmin skin. The skins system is quite simple in design but can be very powerful when used correctly. The main points that you will be required to understand are as follows:
Please refer to the skins documentation for details on default tokens, tokens for commands, and packaging skins.
Once these main points are fully understood, creating skins of your own will be limited only by your imagination.
Definition: A token is a name representing a value stored in memory. When this name is used in between pipes | (shift+backslash), the DirectAdmin token system (tokenizer) will replace the name and the pipes with its assigned value. Example:
Token values can be any type of string and can hold newline characters. Tokens are used quite often in DirectAdmin to display complete tables (<table> to </table>) to show information to a user. DirectAdmin preloads many tokens that can be used on any page. These are called "Default Tokens" which can be found in the tokens document.
The more priveledeges your DirectAdmin account has, the more Default Tokens you will have. For example an Administrator has a default token which can view the total bandwidth usage for the entire server, whereas a User cannot see this token. It's important to note that since an Administrator is an extention of a User, any values a User can see, an Administrator can see too.
As with all skins, there are many web pages that are used to create the skin. There might be one page for e-mail accounts, another for databases, the list is quite long. But between all of those web pages, there are generally similarities that are consistent throughout all of them. These generally include the header and the footer of the page, and a few other things such as style sheets and javascript documents. The most basic way to create all of these pages would be to copy and paste the header and footer into each page manually, and then fill in the content in between them. Although this may work, if you find a typo, in the header for example, you would have to go through each of the web pages manually and change that typo countless times.
Eureka! There is a better way!
Wouldn't it make more sense to only write the header and footer ONCE, store them in their own files and have them inserted into the top and bottom of every page that we want? Of course it would! Guess what, you can!
DirectAdmin supports embedded webpages such that you can do just that, insert other documents into your webpage, anywhere you wish. Lets have a look at a simple example:
Now, we need a way to call the header and footer so that they will be inserted into our webpage. The method used is quite similar to the token system, except that the files will start with HTM_. The way these tokens will be linked to the files will be described later on in the tutorial. Lets call the header HTM_HEADER and the footer HTM_FOOTER. Our webpage will look like:
The results of this webpage will yield:
The HTM_HEADER and HTM_FOOTER parts will be all that you need to insert into each of your many web pages in order to insert the full header and footer into all of them. Now, normally you would be using html syntax to do this and not just plain text. You would generally open the <html> tag in the header, and close the </html> tag in the footer. This way, you don't have to repeat yourself over and over, saving you a lot of time. It quite important to note that you don't have to name the header and footer tokens HTM_HEADER and HTM_FOOTER, you can name them whatever you wish, as long as they are properly linked to their files in the conf files, discussed later on.
Quite often, you will need to move some piece(s), of data around, between pages. The main reson to do this is to keep the same piece of data, and have it inserted onto each page dynamically. For example, a User can have more than one domain, so if he/she is create an email account, we will want to know which domain the email account will be created for. To do this we will pass the domain around between all the web pages from the place where we chose our domain, until the web page we create the email. The way we do this is to use a "GET" request. This is done by adding the token name and value after the name of the file we want to show.
You can pass multiple tokens using this method by simply using the & character. Example:
There are a few instances where we have some data that will be different on each page, but we to show up in the header or footer. Because the header and footer are only stored in one file each, how are we supposed put all the different possible values of that data into these files, without making that many copies of them? For example, the title of a web page is set in the header, but we want the title to change from page to page. To do this we will create a title token in the header file:
header.html: (HTM_HEADER)
Now in each web page, we would set the title before we insert the header:
As you can see, by using a ? before the token name, and a = after the token name, the value to the right of the equals sign will be inserted into the token, which will be stored into memory. Any requests for |TITLE| would then insert the text "This is the DirectAdmin Title!", in this case into the title of the web page. There are a few notes about setting tokens:
This introduction to skins tutorial mainly uses only HTM_ to access data in the conf files. The reality is, DirectAdmin uses many more commands than just HTM_ because a plain text skins would be too exciting. The list of commands is as follows:
Here is the breakdown of each type:
HTM_ is used for basic text html files. It does not execute anything, meaning nothing is changed on the server when it's done.
IMG_ is used for images of any type.
Usage: <img src="IMG_LOGO">
conf file: IMG_LOGO=images/logo.gif
CSS_ is used for style sheets. The functionality of this is exactly the same as HTM_ and is parsed for tokens. It can be inserted into a page using |CSS_NAME| or can imported using <style src="CSS_NAME">
CMD_ is probably the most important of the bunch. It functions exactly the same as HTM_ except that DirectAdmin will do some work to get some non-default information, or will do something to change the server when its done. (eg. create email account). These will quite often create non-default tokens that can only be acccessed after the command is run.
DYN_ are dynamic tokens. What they do is allow you do to insert a token name into a spot in a file at the time the file is called. For example:
the file HTM_FILE is called using /HTM_FILE?DYN_NAME=HTM_USER
What this will do is insert HTM_USER into the token DYN_NAME in the file. HTM_USER is then treated as a token and the contents of HTM_USER will be inserted. So basically, you can chose which file to insert into the token at the time you call it. The feature is not used at all in any of DirectAdmin's included skins, but might be usefull to some skin designers.
As noted earlier, HTM_ tokens have to be linked to a certain file somehow. The conf files are how this is done. The format of a conf file is quite simple, we'll use the header and footer as an example conf file:
The value on the left of the equals sign is the name we use to access the file which is stored on the right of the equals sign. As you may have noticed, you can use HTM_ files either as tokens, or as webpages. IE: you can type domain.com:2222/HTM_HEADER into your location bar to see the contents of that file, or use |HTM_HEADER| inside another file to have it inserted.
Now that we have established what the files are for, now we'll discuss why there are three of them.
There are 3 types of accounts on a DirectAdmin system, and Admin, a Reseller, and a User. Each type of account has different access privileges and can do different things. A User is the lowest type of account of the three. A Reseller account is built off of the User account, but has more features and tools. This is because a Reseller IS a User, but is a more complete set of commands wrapped around the already existing User ones. The same goes for Admins who are just extention of Resellers. This implies that an Admin is a Reseller and a User, so he can do anything at any access level.
"How does this apply to the skins?", you ask. With the different commands for the different account types, there will be web pages that Resellers should see that Users can't, as well as pages that Admins can see that Resellers can't. This is why we have the three files, one conf file for each account type.
Does this mean all of the User files that an Admin will use will be stored in the Admin conf file? No. Since the Admin IS an extention of a Reseller, who is an extention of a User, Admins will be able to read all the data from all three files. This allows a skin creator to only have to define a user file once in one conf file for all three users types
Ok, now I'm confused... How does this work? When an Admin wants to access a User file, lets say HTM_EMAIL, first, DirectAdmin tries to find that name inside the admin conf file. If it finds it there, it will use the file associated with it and send it to the client. If it fails to find that name, it then bumps down to the Reseller conf file to search, then the User conf file, stopping at whichever conf file it finds HTM_EMAIL in. In this example, HTM_EMAIL is a User web page, so the admin will find it in the user conf file. The flow is as follows: It starts in the conf file associated with the access level of the account, searching for the name. If it finds the name, it returns the path to the file, else it repeats these steps with the next lower access level conf file.
Why not just store all names and file paths in one big conf file? Well the answer to that is where some of the power shows itself. Lets say you want to have a space containing some data that shows up for all accounts of all types. The only catch is, you want the data that shows up to be different for each account type. To solve this problem, all you need to do is to create the HTM_ name in all three conf files, and have them point to different files in each one. This will allow the SAME token to be used for everyone while filling it with differnt data. This is because DirectAdmin will start looking in conf file of the the current access level and stop when the name is found.
An example of this is shown in the power_user skin. An Admin will see three tabs linking him/her to the Admin, Reseller or User page. A reseller with the same token will only see 2 tabs showing him/her links to their Reseller or User page. Finally, a User with that token will not see any tabs, as there would only be one anyway link them to their main page.
Using this technique, you can easily change the look of the skins for the different account levels, while only using one token to do it.