How To Incorporate "Role Sensitive" "Include" Files Into 20/20 DataShed's Pages

Step 1: Create a new .asp page that 20/20 DataShed (or any other ASP page/product) can execute. The new script will output a simple button.

1. Open a text editor such as NotePad. You may also use an HTML editor and select the option to edit the "HTML source" directly.
2. Save the new document as "myAdminButton.asp" to your hard drive. (You may wish to save it to a specific folder if you keep a local copy of your web site on your own computer.) Note, if you save the file using Notepad, then Microsoft Windows might append the .TXT extension to your file. Please ensure that the file is called "myAdminButton.asp" and not "myAdminButton.asp.txt" -- to do this you might need to alter the "Folder Options" in Windows Explorer so that the file extensions are not hidden.
3. With NotePad still open, copy-n-paste the following code into the new document. Alter the blue text as necessary.

   <%@ Language="VBScript" ENABLESESSIONSTATE="False" %>
<%
Option Explicit
response.buffer = true
dim booleanIsParentFolder
    booleanIsParentFolder = False
%>
<!--#include file="_locals.asp"-->

     <% IF CheckRoles(optionStr("permitManageItems_Write"),arrRoles) THEN %>
     <ul class="adminVerticalMenuList" id="adminCustomMenuList">
     <li><a href="MyLink.html">My Button Text</a></li>
     </ul>
     <% END IF %>

4. Save the file.
5. Upload it to your web site and place it into the subfolder of 20/20 DataShed. (The folder which contains the _locals.asp file.)
6. The script is now complete but should be tested. Open your web browser and visit this new page by typing the URL into your web browser's address bar. If you are currently logged in, then you see a simple hyperlink. If you are not currently logged in, then you'll be redirected to 20/20 DataShed's login page. If you see an error message, then please restart this tutorial and pay close attention to the instructions.
7. If the script does not produce an error message, then move on to the next section: Step 2.

Step 2: Explanation of the code in this basic example.

<%@ Language="VBScript" ENABLESESSIONSTATE="False" %>

This line contains the language declaration (Language="VBScript") and identifies the file as an ASP document (<% %>).

This line also instructs the web server to disable "sessions": (ENABLESESSIONSTATE="False"). This instruction is optional. We have chosen to disable sessions throughout 20/20 DataShed because doing so saves a considerable amount of overhead on the web server and DataShed doesn't require sessions for any internal features.

If your purposes require sessions, then you could rewrite this line as follows: <%@ Language="VBScript" %>

Option Explicit
response.buffer = true

We have used the option explicit declaration throughout 20/20 DataShed. We recommend that you use this option in your own scripting as well.

The response.buffer is set to "true" throughout 20/20 DataShed. Unless you have good reason to alter this property, then we suggest you leave this line as it is.

Note that you might be tempted to write additional headers to the file, such as the following:

• response.expiresAbsolute
• response.CacheControl

We recommend that you do not use these headers in an .asp document such as this (i.e. one that will be executed using the Server.Execute() method) unless you know exactly what you're doing and have good reason for including these options. In our experience, we have found that these properties of the "Response" object can cause runtime errors if they conflict with the processing of the "calling" page (i.e. the page/script which is executing this external code.)

dim booleanIsParentFolder
booleanIsParentFolder = False

This variable must exist (because it's required by the _locals.asp file) -- but it doesn't effect this exercise.

Just leave these two lines alone and forget about them.

<!--#include file="_locals.asp"-->

This line is very important. It includes the _locals.asp in this new script so that we can make use of the features and functions within it.

The first and very important feature which this inclusion provides us is username/password authentication. If the current user is not logged in, then mechanisms within this file will bounce that user to the login page. Hence, the contents of this page are protected from unauthenticated users.

And secondly, this file contains a very useful function which we will use later in this code to check the current user's credentials: CheckRoles().

<% IF CheckRoles(optionStr("permitManageItems_Write"),arrRoles) THEN %>
...
<% END IF %>

This is the logic which checks the current user's credentials against a set of required permissions.

optionStr("permitManageItems_Write") is a function which returns a list. That is a list of numbers (roleIDs) which have been assigned this particular permit: permitManageItems_Write.

arrRoles is an array which contains all the roles to which the current user belongs.

Here the logic in plain language:

1. Which roles can "Manage Items"? optionStr() is a function which finds this information.

   Example answer: "1,3"

2. Which roles does the current user belong to?

   Example answer: "1,2"

3. So...if this user is in a role which can manage items then carry on. If not, then do nothing.

The tricky part here may be to choose the appropriate permit to test. In this example, we are testing for permission to manage items; but this could be altered like this:

optionStr("permitManageUsers_Write")

The above code would produce a list of roles which have permission to manage users. Typically this would be an administrator.

optionStr("permitSQLReports_Write")

The above code would produce a list of roles which have permission to create SQL reports. Typically this would be a webmaster or administrator.

optionStr("permitDatabaseUtilities_Write") &","& optionStr("permitManageCategories_Write")

The above code would produce a list of roles which have permission to both perform database backups and add/delete/rename categories. Typically this would be a webmaster.

optionStr("permitChangePassword_Write")

The above code would produce a list of roles which have permission to change their own account password. Typically this would be any registered user.

Example:

<% IF CheckRoles(optionStr("permitDatabaseUtilities_Write") &","& optionStr("permitManageCategories_Write"),arrRoles) THEN %>
If this is true, then this user is a webmaster or privelaged administrator.
<% ELSE %>
Otherwise, this user is not authorized.
< END IF %>

More information about permissions can be found in the article called Role Based Security in 20/20 DataShed.

<ul class="adminVerticalMenuList" id="adminCustomMenuList">
<li><a href="MyLink.html">My Button Text</a></li>
</ul>

This HTML code simply places a hyperlink on the page.

Interesting to note though, that this hyperlink is contained by a list with the classname "adminVerticalMenuList". This is the classname of 20/20 DataShed's menu (the menu in the left sidebar on the admin pages). By using this markup and classname, this button will automatically be formatted to look exactly like the other buttons in 20/20 DataShed's menu.

The blue text above is customizable. We suggest you name the button to whatever you wish, and alter the hyperlink so that it points to any web page or script that you wish.

Step 3: Edit the admin_template.html to instruct 20/20 DataShed when/where to execute the new ASP script.

In the previous sections we created an ASP file -- a "stand-alone" script with a very simple purpose to produce a button (only for users with some administrative privelage who can manage items in the database). Now we will show you how 20/20 DataShed's skinning engine can execute ("include") that file within your admin template.

1. Access your web site with an FTP application such as CuteFTP, FTP Explorer, or Windows "My Network Places".
2. Download admin_template.html from the templates folder of this application to your local computer.
3. Open the file in a text editor such as Notepad or a WYSIWYG editor. (If you choose to use an editor, then please ensure that you select the option to edit the "source" directly.)
4. In that file, find the area in which you want to "include" the button. (Look below in our example to place this new button immediately underneath 20/20 DataShed's admin menu -- but the button could be located anywhere you choose.)
5. Place the following token in your template where you want the button to appear:

   [2020Execute_myAdminButton.asp]

   In the example code below, you can see that we'll include the button under the other menu buttons.

   <html>
<head>
<title></title>
</head>
<body>

<!-- HEADER STUFF -->
    <h1>Welcome to the Admin Pages!</h1>
<!-- END OF HEADER STUFF -->


<!-- MENU STUFF -->
<div style="float:left;width:200px;">
[2020Inject_ApplicationToolsOptions]
[2020Inject_AccountMenuOptions]
[2020Inject_AdminMenuOptions]
[2020Inject_ContextMenuOptions]
[2020Inject_QuickFindForm]
[2020Execute_myAdminButton.asp]
</div>
<!-- END OF MENU STUFF -->

<!-- BODY (Main Content) STUFF -->
<div style="margin-left:215px;">
[2020Inject_2020Applications_AdminBody]
</div>
<!-- END OF BODY STUFF -->


</body>
</html>

6. Save the file.
7. Upload the file to your web site using the FTP application and overwrite the existing "admin_template.html" file.
8. Reload the admin.asp, listings.asp, newuser.asp, or login.asp page and include the "?objApplication=RemoveAll" querystring in your URL to force 20/20 DataShed to flush out the old template from the server's cache (and reload this new one).

   Example: http://www.your_domain.com/login.asp?objApplication=RemoveAll

   You should see your new button within your template. (And anybody without permission to manage items will not see the new button.

Step 4: Update the CSS (An optional step).

In 20/20 DataShed versions prior to v1.1.1(Beta), the "2020applications_adminstylesheet.css" defined the menus by their ID attributes instead of by their classname.

This was done to provide greater flexibility for each of the individual menu sections. However, it has since become apparent that the classname would be more efficient.

As well, the information in the tutorial above (the comments about the button's style and CSS inheritance assumes that the "2020applications_adminstylesheet.css" file contains the most up-to-date revisions.

Follow these instructions to update your stylesheet if you'd like this new button to be styled similar to the other menu buttons:

1. Open "2020applications_adminstylesheet.css" in a text editor like Notepad.
2. Locate this code and make the changes outlined below. (This is the default style; your own file may differ.) The line-through indicates that you should delete the line; the green text indicates you should add the new lines:

   /* MAIN MENU styles */
.adminVerticalMenuList #adminAppToolsSubMenuList,
#adminAccountMenuList,
#adminAdminMenuList,
#adminContextMenuList {
     text-align:left;
     width:170px;
     margin:0px;
     padding:0px;
     border-style:solid;
     border-color:#a0a9bc;
     border-width:1px;
     border-top-width:0px;
     border-bottom-width:0px;
     line-height:22px;
     }

#adminAppToolsSubMenuList {
     border-top-width:1px;
     }

.adminVerticalMenuList li #adminAppToolsSubMenuList li,
#adminAccountMenuList li,
#adminAdminMenuList li,
#adminContextMenuList li {
     display:inline;
     }

.adminVerticalMenuList li a,
.adminVerticalMenuList li a:link,
.adminVerticalMenuList li a:active,
.adminVerticalMenuList li a:visited #adminAppToolsSubMenuList li a,
#adminAccountMenuList li a,
#adminAdminMenuList li a,
#adminAppToolsSubMenuList li a:link,
#adminAccountMenuList li a:link,
#adminAdminMenuList li a:link,
#adminAppToolsSubMenuList li a:active,
#adminAccountMenuList li a:active,
#adminAdminMenuList li a:active,
#adminAppToolsSubMenuList li a:visited,
#adminAccountMenuList li a:visited,
#adminAdminMenuList li a:visited,
#adminContextMenuList li a,
#adminContextMenuList li a:link,
#adminContextMenuList li a:active,
#adminContextMenuList li a:visited {
     margin:0px;
     width:99.99%;
     display:block;
     background-color:#ded4b4;
     border-style:solid;
     border-color:#a0a9bc;
     border-width:0px;
     border-bottom-width:1px;
     text-decoration:none;
     font-family:Tahoma,Arial,serif;
     font-weight:bold;
     font-size:10px;
     }

#adminContextMenuList li a,
#adminContextMenuList li a:visited,
#adminContextMenuList li a:link,
#adminContextMenuList li a:active {
     background-color:#183c63;
     color:#ebe9e3;
     filter:progid:DXImageTransform.Microsoft.Gradient(GradientType=0,StartColorStr='#FFebe9e3', EndColorStr='#FF183c63')
     }

.adminVerticalMenuList li a:hover #adminAppToolsSubMenuList li a:hover,
#adminAccountMenuList li a:hover,
#adminAdminMenuList li a:hover,
#adminContextMenuList li a:hover {
     background-color:#fbf6e5;
     border-style:outset;
     color:#a0a9bc;
     filter:progid:DXImageTransform.Microsoft.Gradient(GradientType=0,StartColorStr='#FFffffff', EndColorStr='#FFebe9e3')
     }

.adminVerticalMenuList .currentPageMenuItem a,
.adminVerticalMenuList .currentPageMenuItem a:link,
.adminVerticalMenuList .currentPageMenuItem a:active,
.adminVerticalMenuList .currentPageMenuItem a:visited #adminAppToolsSubMenuList .currentPageMenuItem a,
#adminAccountMenuList .currentPageMenuItem a,
#adminAdminMenuList .currentPageMenuItem a,
#adminAppToolsSubMenuList .currentPageMenuItem a:link,
#adminAccountMenuList .currentPageMenuItem a:link,
#adminAdminMenuList .currentPageMenuItem a:link,
#adminAppToolsSubMenuList .currentPageMenuItem a:active,
#adminAccountMenuList .currentPageMenuItem a:active,
#adminAdminMenuList .currentPageMenuItem a:active,
#adminAppToolsSubMenuList .currentPageMenuItem a:visited,
#adminAccountMenuList .currentPageMenuItem a:visited,
#adminAdminMenuList .currentPageMenuItem a:visited {
     background-color:#fbf6e5;
     border-style:outset;
     filter:progid:DXImageTransform.Microsoft.Gradient(GradientType=0,StartColorStr='#FFffffff', EndColorStr='#FFebe9e3')
     }

.adminVerticalMenuList .importantPageMenuItemOn a,
.adminVerticalMenuList .importantPageMenuItemOn a:link,
.adminVerticalMenuList .importantPageMenuItemOn a:active,
.adminVerticalMenuList .importantPageMenuItemOn a:visited #adminAppToolsSubMenuList .importantPageMenuItemOn a,
#adminAccountMenuList .importantPageMenuItemOn a,
#adminAdminMenuList .importantPageMenuItemOn a,
#adminAppToolsSubMenuList .importantPageMenuItemOn a:link,
#adminAccountMenuList .importantPageMenuItemOn a:link,
#adminAdminMenuList .importantPageMenuItemOn a:link,
#adminAppToolsSubMenuList .importantPageMenuItemOn a:active,
#adminAccountMenuList .importantPageMenuItemOn a:active,
#adminAdminMenuList .importantPageMenuItemOn a:active,
#adminAppToolsSubMenuList .importantPageMenuItemOn a:visited,
#adminAccountMenuList .importantPageMenuItemOn a:visited,
#adminAdminMenuList .importantPageMenuItemOn a:visited {
     background-color:#fbf6e5;
     border-style:outset;
     filter:progid:DXImageTransform.Microsoft.Gradient(GradientType=0,StartColorStr='#FFffffff', EndColorStr='#FFebe9e3')
     }

3. Save and upload the file.