Home

Awesome

UkeGeeks Scriptasaurus

When added to your webpage this JavaScript library creates ukulele chord fingering diagrams and nicely formated songsheets by reading songs from directly within HTML <pre> tags.

The optional PHP mini-website let's you start publishing your own songbooks.

Visit the UkeGeeks website for more information.

Follow @ukegeeks

Ongoing discussions and "How To" videos posted at blog.ukegeeks.com. Also read the User Guide and Chord Pro mark-up reference for more demos and examples.

Lastly, the blog includes a technical discussion and tips section

Authors

What's New...

V1.4.4

V1.4.3

V1.14

V1.13

V1.12

What's Old

What's Missing

What's In This Project/Download

The UkeGeeks GitHub repostitory contains:

Demos

To illustrate the similarities of the static HTML and PHP-driven versions we have two presentations of "My Little Grass Shack in Kealakekua" (note: links point to UkeGeeks.com but will run on your web server):

Overview

Scriptasaurus does two things:

  1. formats HTML;
  2. generates chord diagrams.

It does these by reading a text block and rewriting it with additional HTML tags (<code>) wrapping any chords it detects (a chord is any text enclosed within square brackets, i.e. [Fmaj7])

It recognizes several ChordPro tags (for the most detailed info on supported tags visit Uke Geek's User's Guide: ChordPro Markup Reference)

About Names and Scope

Many files and CSS class names are prefaced with "UGS": Uke Geeks Scriptasaurus. "Uke Geeks" is the whole schmeer, the collection of projects. "Scriptasuarus" (or "Core Library") refers to the single JavaScript library that does the heavy lifting.

Thus Scriptasuarus forms the heart of all Uke Geeks projects.

So the Editor uses Scritasaurus PLUS an additional class library ("ugsEditorPlus.merged.js"), but to merely render a song one only needs Scriptasaurus (ukeGeeks.Scriptasaurus.merged.js). (see note on "Merged versus Min" below)

This raises an important point:

Scriptasuaus does NOT use any jQuery. The editor, however, is completely dependent upon jQuery.

More Files Than You Need

In the JavaScript and CSS directories you'll find "merged" and "min" (minified) versions of the libraries. These are all you need to start using the applications. However, if you want to tinker or see under the hood then you'll find the individual JS class libraries (or stylesheets) under the subdirectories helpful.

Merged versus Min

To better organize and maintain the JavaScript classes I've tried to follow strict "one class per file" and "one purpose, one class" policies. Thus, as you'll notice, there are a LOT of files which would clearly be a perfomance issue if they were linked individually. Fortunately PHP minify allows us to smush them all into a single file. In addition, minify allows us to further compact our merged files, removing comments and unneeded white-space.

Thus you'll find the individual class files as well as single merged and minified files. For a true production environment use the min version. To reverse engineer the project try the merged or single class files.

Static Site Info

If you'll be hand building your HTML or adding it to your exising site pages I'll refer you to the sample songs under the "songs" directory.

Note: If you are serving static pages (no server application language such as PHP) I recommend using Dreamweaver's Templating system -- though this is entirely up to you. It's consistent, fast, and prevents you from accidentally editing a critical part of your file. This download includes sample templates used by the static HTML song page (located in the "templates" directory).

Getting Started With PHP Songbook

The Songbook implements a rudamentary Model-View-Controller architecture. Why? This approach allows you to modify Views (pages made mostly of HTML with a few PHP tags for emitting dynamic content) without need to worry about breaking any of the inner workings (hint: there aren't many inner workings either).

A Poorboy's "Lite" MVC Architecture

All access to the application goes through a single file, "music.php" -- the only PHP file that lives outside of the ugsphp directory. Music.php instantiates the program's core class, Ugs, which bootstraps the system -- it's the Controller.

Ugs loads all class files, including Config.php, and chooses which action is required.

The Config class is where you enable various options and customize your installation.

Here's the ugsphp directory breakdown:

Using mod_rewrite For Pretty URL's

Without mod_rewrite your PHP Songbook will work fine, you'll just see page requests like this:

music.php?action=song&amp;song=filename

This URL's "query param" named "song" tells the Builder class which song file to read and prep for easy rendering via Scriptasaurus.

However, instead of surfacing rather klunky URLs make use of Apache's mod_rewrite engine to convert a doopey URL such as:

http://mysite.com/music.php?action=song&amp;song=my-favorite-martian

To the more friendly:

http://mysite.com/songbook/my-favorite-martian

The included .htacces.txt file has an easy rule for doing just this. If you already have an .htacces file just merge in the contents, otherwise remove the ".txt" portion. Make sure you've enabled MOD_REWRITE in your apache config (if you're just now enabling it remember to restart Apache).

Caching

If you've enabled the "detailed" song lists the system automatically switches to using a cached list of the songs. Therefore, the cache must be rebuilt each time a song file is manually added (cache is automatically rebuilt after each Add or Update if editing is enabled)

To manually reindex your songs use this url (second is available if you've enabled mod_rewrite):

your-song-site.com/music.php?action=reindex
your-song-site.com/reindex

You'll need to make sure that the Apache/PHP group has the correct write permission on the cache directory.

chgrp -R _www /httpdocs/ukegeeks/ugsphp/cache
chmod -R u+r+w+x,g+r+w+x,o+r-w+x /httpdocs/ukegeeks/ugsphp/cache

You probably will need to "sudo" to have these commands work (run -- or "do" -- the command as "super user", thus "sudo"):

$ sudo chgrp -R _www /httpdocs/ukegeeks/ugsphp/cache
$ sudo chmod -R u+r+w+x,g+r+w+x,o+r-w+x /httpdocs/ukegeeks/ugsphp/cache

And, of course, restart apache

$ sudo /usr/sbin/apachectl restart
Overriding Song-A-Matic's Default Settings

There's a good chance that your prefered editor appearance differs from mine -- perhaps you'd like the initial font size much bigger, or you need baritone tuning, or you'd just like a different theme applied. You can easily change all these by creating a settings file that includes whichever values you want.

In the "ugsphp" folder you'll find a file named "settings.json_example" copy this file as "settings.json" and open it in your editor of choice. This file contains a small bit of JSON (JavaScript Object Notation) and a lot of comments. In here you'll see all of the available settings you're able to change along with their default and allowed values. Uncomment the ones you want by removing the double-slashes (line comment marker) at the beginning of the line:

{
/* If true the Edit Song box is shown when the page loads; false hides it.
 * Allowed values (number): 6, 6.5, 7, 7.5, 8, 8.5, 9, 10, 11, 12, 13, 14
 */
"fontSize": 9
}

Back in your web browser reload your song to see your settings applied. If they are not then the odds are that you have a minor typo -- a misplaced comma, an extra semicolon, or a missing closing quote. The app (tries) to display an alert box if there's a problem. If you get this error and cannot quickly resolve the issue then look online for a "JSON validator".

You may safely delete any unused options and comment blocks from your JSON settings, however, retain the original, unedited settings.json_example for future reference.

Installing In A Different Directory

The Songbook assumes that it's installed in your web server's root directory, but you might want it in a subdirectory. Perhaps you want the URLs to be "mysite.com/hobbies/ukulele/music.php", for example. Excellent! To do this we just need to open config.php and change the subdirectory.

By default this is set to the root:

    const Subdirectory = '/';

You can just modify it to whatever you wish (include leading and trailing last forward slashes "/")

    const Subdirectory = '/hobbies/ukulele/';

If you're using caching (and by default the Songbook does) then the only remaining task is to reindex your ChordPro songs (the song URLs are stored along with the song meta-info). Type this into your browser's location bar:

http://mysite.com/hobbies/ukulele/music.php?action=reindex
Moving Uke Geek Asset Directories

You may also move the JavaScript, Stylesheet, and Image "static" directories, however, they all should live in the same directory in order for the styles to work correctly.

For example, you may change the StaticsPrefix option from the root '/' to:

const StaticsPrefix = '/uke-static/';

The Editor, for example, will now link to:

http://mysite.com/uke-static/js/ukeGeeks.scriptasaurus.merged.js'

Actions

Whether running mod_rewrite or using query params ("mysite.com/songbook" versus "mysite.com/music.php?action=songbook") there are a set of supported actions (verbs):

Trouble Shooting

License

This library is licensed under GNU General Public License.

Use it, change it, fork it, but please leave the author attribution.