Templates

From SOWNWiki

Jump to: navigation, search

logo-yellow.png

Update Needed
This page needs to be updated

This page is highly out of date. Not only does this page need updating the actual PHP template pages it is trying to document need updating as well.

In order that the SOWN website be more manageable and easily updated much of its functionality is done by standard functions. Where possible new web pages should make use of these pre-written functions and if code is likely to be re-used that too should be added to the standard templates. David Tarrant is the current maintainer for the php include files. The latest copies of the files should be found in the SVN repository.

When logged in the user will have the templates header2.inc.php and footer2.inc.php. If the page has no access restrictions header.inc.php and footer.inc.php are used.

Contents

header2.inc.php

Variables Sent to header2.inc.php

This file is included at the top of every page. The following variables need to be set before including it:

  • $required_level
  • $no_menus
  • $banner_file
  • $page_title

required_level

This is the minimum access level required to access the page. If more fine grained access control is required this can be done later using the $level variable provided by the script. If a user's access level does not meet or exceed the value in this variable the user will receive an access denied page. This variable must be set or the user will always get accesses denied regardless or their level. For more information on user levels see user_levels.

no_menus

Set this variable to boolean true to disable the left hand menus. This is handy if you need to do something in full screen such as a photo album. If the variable is not set it is assumed to be false.

banner_file

This is the path to the file containing the variable to add to the banner that appears under the title of the page and above the page's actual content. This bar is used to provide quick links to pages/functions relevant to the page the user is currently viewing. If this variable is not set no banner will be displayed.

page_title

This variable should contain the title of the page to appear in the browser title bar and in the banner at the top of the page. If this variable is not set the page will have no title.


Headers Obtained from header2.inc.php

After header2.inc.php has executed you will be in the main body of the html page and can begin outputting html. You will also have a database connection and the following variables:

  • $sid
  • $susername
  • $slevel

sid

This is the id from the database of the user accessing the page and can be used to link things in the database to a particular user.

susername

This is the user name of the user accessing the page.

slevel

This is the access level of the user accessing the page. This is useful if you need to display a different version of the page depending an the access level of a user.

Functions Obtained from header2.inc.php

To help standardise the appearance of the website header2.inc.php provides several built in functions for displaying things on the page. Where possible these functions should be used rather than writing the function again yourself. If you find yourself re-using a function repeatedly you should consider adding it to header2.inc.php.

Database Connection

You will have a connection to the SOWN database. Queries can be performed in the following way:

$query = "SELECT * FROM table_name";
$result = mysql_query($query);

The database connection will be closed when you include footer2.inc.php

Date Functions

get_days_since_epoc

This function takes no arguments and returns an integer value.

get_datetime($date)

This function takes the single variable date which should be a valid date and time and returns the date formatted in the form YYYY-MM-DD HH:MM:SS.

get_unix_from_datetime($date)

This function takes a single variable which should be a valid date and time and returns a UNIX time stamp.

Form Functions

These form functions help draw forms quickly by removing the need to individually write all forms in html. Based on the values given to it it will create the correct input type and fill it with any required values.

draw_item($data,$key)

This function takes the array $data which is an array of all the data you which to draw a form using. It also takes $key which is a number relating to the line in the array you want to create the form component for. To create a form component for all the data in an array the following can be used:

$x = 0;
while($data[$x]{
    draw_item($data, $x);
    $x++;
}

draw_item2($data,$key,$name,$value)

This is a more advanced form of the above function.

get_groups()

Gets all the groups in the database and returns them as an array.

Multicast Commands

send_message_multicast($message)

This function takes the variable $message which is a command to send to all nodes in SOWN. This function is used to update all the nodes at once. The variables for the multicast address and port are statically set to:

$mcgroup = "239.122.0.1"; //The multicast group to send the message to
$mcport = "5032"; //The port to send the message to
$mc_src_addr = "10.13.0.252"; //The source address of the multicast stream

E-mail Operations

The [[Auth | auth server] is configured to allow e-mails to be sent

get_verification_data($id)

This function takes an integer which is the user's ID in the database and returns an array containing the user's user name, e-mail address and a hash of their user name name email and the date they joined.

send_new_password($id)

This function takes an integer which is the user's ID and sends them an e-mail which allows them to change their password. It returns the e-mail it just sent as something strange an array perhaps?

send_verification_email($id)

This function takes an integer which is the user's ID in the database and sends them an e-mail asking them to confirm their e-mail address. It returns the e-mail sent as the same weird thing that send_new_password($id) returns. I never did get what -> does. The only time you need to call this function is when the user changes their password. That process may get documented some time but we may release the source code to this system for free in which case good documentation is definitely a no no :-).

User Management

add_sown_user($username,$password,$id)

delete_sown_user($username)

change_username($old_username,$new_username)

write_password($id,$password)


The latest copy of header2.inc.php can be found in the svn respository.

ip.inc.php

These functions are enabled by including ip.inc.php. They are used to determine things about the SOWN network given an IP address and a subnet mask.

IPv4 Subnet Functions

These functions deal with the IPv4 protocol. They were initially written by Paul Dart on 31-08-2007. For those of you wanting to to know the maths behind it see Templates#Maths_Behind_IPv4_Subnets

get_netmask($subnet)

This function gets the netmask ie "255.255.0.0" from a subnet specification ie "/16". It takes a single variable which is the subnet as an integer and returns the subnet as a string with each octet separated by a period (.).

calc_netmask($value, $netmask)

This is called by the get_netmask function and determines where the subnet mask lies if it is not exactly on an octet boundary.

get_gateway($ip, $subnet)

This function takes an IP address as a string as its first argument and a subnet identifier as an integer as its second argument and returns the default gateway for that network. It should be pointed out that whilst many networks have the gateway as one plus the network idenfifier SOWN uses 1 minus the broadcast address for the network. For example for the network 192.168.0.0/24 the default gateway would be 192.168.0.254. In this example you would call the function as follows:

$gateway = get_gateway(192.168.0.12, 24);

$gateway would then have the string value of "192.168.0.254"

get_no_addresses($ip,$subnet)

This function returns the number of IP addresses in a particular subnet. Whilst it takes the argument $ip it is not used because the number of IP addresses in a subnet depends only on the subnet identifier not on the ip addresses in the subnet. None the less you have to call it as follows

$number_of_addresses = get_no_addresses("anything you like",24);


$number_of_addresses will then have the integer value 254.

get_start_ip_part($pow,$ip_bit)

get_end_ip_part($pow,$ip_bit)

get_net($ip, $subnet)

This takes an IP address as a string and a subnet identifier as an integer and returns the network identifier of the network as a string.

$network_identifier = get_net("192.168.0.12, 24);

$network_identifier will now have the value of "192.168.0.0"

get_broadcast($ip, $subnet)

This function takes an IP address as a string and a subnet identifier as an integer and returns the broadcast IP of the subnet.

$broadcast_ip = get_broadcast("192.168.0.12, 24);

$broadcast_ip will now have the value of "192.168.0.255"

Maths_Behind_IPv4_Subnets

Let us take an IP address 10.13.160.43 with a subnet of 17. We want to find out what the network identifier of the network is.

We need to first work out what octet the IP address is in.

17 is less than 24 but more than 16 so it is in the second from last octet so we subtract 17 from 24

24-17=7

we then work out what 2 to the power 7 is.

2^7=128

128 is the network identifier, we already know it is in the second to last octet thus the last octet is 0, the first octet can be taken from the original IP address so it is 10 as can the second octet giving 13 so the entire network identifier is 10.13.128.0. Next we need to work out the broadcast address. To do this we work out what fraction of the octet we are using.

256/128=2

We are using half the of the address space so we need to add one over the fraction multiplied by 256 to get the value to add to the network identifier.

1/2*256=128

We can now add 128 to our network identifier so we get

128+128=256

We can now set the octet below our subnet to 255 and keep any octets above us the same thus we get a broadcast address of 10.13.255.255.

There are other websites which cover this subject a little better...