After you have installed Jamroom, you might have noticed a section in the Admin Menu for “Buttons”, and wondered what it was for. The “Custom Buttons” feature allows you to create new “menu” entries on the Artist or Admin Menu, and those “menu buttons” can be linked to external web pages, and even other web applications. This is a convenient way for you to add links to external sources directly into your Jamroom.

The first thing you will want to decide before placing your first Custom Button, is whether you want your button to appear directly in the “Extras” section of the Artist (or Admin) menu, or if you want the Button to be a choice withing a separate Menu. If you would like to have the button show up directly within the Artist or Admin Menu, skip to the Creating or Modifying a Custom Button section, since there is no need to create a Custom Menu for your button.

Now that you have decided you want to create a separate “sub” menu that will hold your Custom Button (or more likely - buttons), you’ll want to first create your Custom Menu. Click on the “Create Menu” link in the Admin Menu, and you will be presented with a form interface with the following choices on it:

• Menu Label - The “Menu Label” is the text the User will see on the button in the menu.
• Menu Text - This is the text that will appear in the upper right corner of the Button Menu.
• Menu Quota - You can define this Menu to be available only to Artists with a specific Jamroom Quota. If you would like it to be available to all Artists regardless of their Jamroom Quota, choose “(shown to all quotas)” as your choice.
• Menu Parent - If you would like this Custom Menu to be located on a Sub-Menu, then choose the Sub-Menu from this list, or leave on “no parent” to create a standard Custom Menu that is located in the “Extras” section of the Artist or Admin Menu.
• Hide Menu - Check here if you would like to keep this button menu from showing on the User Menu. NOTE: Hiding a Sub-Menu will make ALL the Custom Buttons located on that Sub Menu to become unavailable.

1. Choose what you want your Menu to be called and type it into the Menu Label field. This will be the actual text that shows up in the “extras” section of the Artist or Admin menu.
2. Next, choose some descriptive “text” that will appear in the Sub Menu header section, and type it into the Menu Text input field. It is recommended that this be a description of the type of buttons that are going to be located on this Custom Menu.
3. Next choose the Quota you want this menu to be available for, or choose “Master Admin only” to make this button show up on the Admin Menu only.
4. Next you can (optionally) choose a “parent” menu for this menu to become a child of. Using this option you can build menu “trees” - i.e. menus with links to other sub menus. Leave this at the (no parent) default for this menu to be linked directly off the Artist or Admin menu.
5. Finally you can choose to make this menu item “hidden” if you are not ready for it be viewable on the menus yet.

That’s it - you have now created a Custom Menu, and this new menu will be available for you to add Custom Buttons (or other Custom Menus) to.

Creating a new Custom Button (or modifying an existing button) is very easy to do:

• To CREATE a new button, click on the “Create Button” option from the Admin Menu.
• To MODIFY an existing button, click on the “Modify Button” option from the Admin Menu. ¹⁾

Once you have chosen the appropriate button, you will be presented with the same form interface (except in modifying a button the fields will be filled in). In the form interface, there are some simple text fields that need to be filled in to reflect what you would like the button to say:

One thing that makes the Custom Buttons powerful is the ability to place “variables” in the URL that will be expanded when hyperlinked to the Button Label. The following URL variables are available for use in Button URL‘s:

Using these variables in your URL will allow you to “pass” Jamroom information to another application, and is the method used to enable the Jamroom Lofi Creator in the Artist Menu. For example - let’s say you had another application that you wanted to be able to pass the user_id. When you were creating the Custom Button, you can do something like:

http://example.com/your_application.php?id={USER_ID}

And when the User (or Admin) clicked on the URL link, their user-id would be substituted where the {USER_ID} variable is located in the URL string.

One of the questions that gets asked a lot is “How can I open the Custom Button link in a New window, instead of having it open in the right-hand frame of the Jamroom Window? The “trick” here is to add the “target” option in to the URL so it gets passed correctly in to Jamroom. So for example, if you wanted to create a Custom Button that links directly to Google, you would enter the Button URL like this:

http://www.google.com

However, if you wanted to have the window for Google open in a new window, you would do it like this:

http://www.google.com" target="_blank

Note that there are no quotes at the beginning and end of the URL string - that is because Jamroom will automatically put them there for you.

The Custom Buttons aren’t only for the Artist Menu though - you can also create a Custom Button in the Admin Menu - just make sure and specify the button as being “Admin Only” in the Button Quota selection box. This comes in handy for linking to web stats programs, email list managers, web control panel, etc.

Occasionally you may come across an instance where you would like to protect one of the pages you would like to link to the Custom Button from outside visitors, or Artists that belong to other Jamroom Quotas. While the Custom Button interface for modifying and creating buttons will allow you to show the button(s) to only those quotas you want to, there’s no guarantee that the page you are linking to cannot be “browsed” outside of Jamroom. The solution to this problem is to use a small “helper” script (called loader.php), which will do 2 things:

1. First, it will ensure that the user is logged in to your Jamroom before being able to view the page.
2. Second, it will allow you to only show pages to the specific quota you want the page shown too - no chance that a visitor can “browse” your files from outside of Jamroom.

First, you’ll want to create a new directory in your jamroom/templates directory called “loader” - i.e.

jamroom/templates/loader

Next, Within this directory you want to create a file called “.htaccess” (web site access control file). ²⁾ Within the file, place the following, single line:

Deny from ALL

This will prevent anyone from being able to “surf” into that directory and view the files within.

Now it is time to place the template files you want to use within the jamroom/templates/loader directory - make sure they have a “.tpl” extension on them or they won’t work! the loader.php script will use the Smarty template engine to parse the files that are shown to your Jamroom users. What you’ll want to do is name the template files so they end with the Jamroom Quota ID that you want them shown to - i.e.:

jamroom/templates/loader/page_for_quota_5.tpl

This is the template that will only be shown to users logged in who are part of the Jamroom Quota ID “5”., for example.

Your last step is to now create the “loader” Custom Button with the correct call to loader.php. Using our example above, the “Button URL’ you would use is:

loader.php?template=page_for_quota_{QUOTA_ID}.tpl

What will happen is that Jamroom will “expand” the {QUOTA_ID} Custom Button variable to the actual ID number of the Jamroom Quota the artist’s account belongs to - so if they were part of Jamroom Quota ID “5”, they would be able to view the contents of the “page_for_quota_5.tpl”.

That’s all there is to it. Once you see how this works the first time, it’s very easy to add additional “locked” pages for your Custom Buttons.

1) note that you will not see the modify button option unless a button has already been created.
2) note: you may need to contact your hosting provider if you are unable to use .htaccess files - by default most web hosts allow this and you should have no problems