forked from buzcarter/UkeGeeks
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathreadme.htm
More file actions
222 lines (222 loc) · 10.8 KB
/
readme.htm
File metadata and controls
222 lines (222 loc) · 10.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Getting Started UkeGeek's Scriptasaurus</title>
<!--[if IE]>
<script src="http://html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<style>
header,
section{
border-bottom:1px solid #CCC;
margin-bottom:1.5em;
padding-bottom:1.5em;
}
.topOfPage{
font-size:.85em;
text-align:right;
}
</style>
</head>
<body>
<article>
<header>
<hgroup>
<h1>UkeGeek's Scriptasaurus "Getting Started" Installation Guide</h1>
<h2>Revision: 1.155</h2>
</hgroup>
<p>For the most up to information please visit <a href="http://ukegeeks.com">ukegeeks.com</a>.</p>
<nav>
<h3>Contents of this file</h3>
<ol>
<li><a href="#demos">Demo Links</a></li>
<li><a href="#overview">Overview</a></li>
<li><a href="#contents">Contents of the zip package</a></li>
<li><a href="#static">Static Site Info</a></li>
<li><a href="#mvc">Using the PHP "Lite" MVC Pages</a></li>
<li><a href="#mod_rewrite">Using mod_rewrite For Pretty URL's</a></li>
<li><a href="#trouble">Trouble Shooting</a></li>
<li><a href="#license">License</a></li>
</ol>
</nav>
</header>
<section id="demos">
<h2>Demos</h2>
<p>Here's two versions of "My Little Grass Shack in Kealakekua":</p>
<ul>
<li><a href="songs/my-little-grass-shack-in-kealakekua.htm">Static HTML</a></li>
<li><a href="song.php?song=my-little-grass-shack-in-kealakekua.cpm.txt">"Smart" dynamic PHP</a></li>
</ul>
<p>If the dynamic PHP script won't work check the <a href="#trouble">Trouble Shooting</a> installation notes below</p>
<p class="topOfPage"><a href="#">Top</a></p>
</section>
<section id="overview">
<h2>Overview</h2>
<p>Scriptasaurus does two things: 1. formats HTML and 2. generates chord diagrams. </p>
<p>It does this by reading a text block and rewrites it with additional HTML tags (<code>) wrapping any chords it detects (a chord is any text within square brackets, i.e. [Fmaj7])</p>
<p>It recognizes several ChordPro tags (for the most detailed info visit the <a href="http://www.ukegeeks.com/users-guide.htm">Uke Geek's User's Guide</a>)</p>
<table>
<thead>
<tr>
<th>Command</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>{title:X}</code> or <code>{t:X}</code></td>
<td>Sets the title of the song.</td>
</tr>
<tr>
<td><code>{subtitle:X}</code> or <code>{st:X}</code></td>
<td>Sets the "subtitle" and is usually used for the artist or composer of the song.</td>
</tr>
<tr>
<td><code>{album:X}</code></td>
<td>Sets the album (or movie) name. <em>Not a "standard" CPM tag.</em></td>
</tr>
<tr>
<td><code>{artist:X}</code></td>
<td>Sets the artist (composer, performer, lyricist, or just 'artist'). <em>Not a "standard" CPM tag.</em></td>
</tr>
<tr>
<td><code>{comment:X}</code> or <code>{c:X}</code></td>
<td>Used to add a visible comment to the song. For example, specifying that the song should be played with a capo, or an alternative tuning.</td>
</tr>
<tr>
<td><code>{start_of_chorus}</code> or <code>{soc}</code> <br />
<code>{end_of_chorus}</code> or <code>{eoc}</code></td>
<td>Marks the chorus in the song</td>
</tr>
<tr>
<td><code>{start_of_tab}</code> or <code>{sot}</code> <br />
<code>{end_of_tab}</code> or <code>{eot}</code></td>
<td>Marks a part of the file which should be interpret as plain-text. Used mainly to add parts containing text tablature.</td>
</tr>
<tr>
<td><code>{define: CHORD frets 0 0 0 0 fingers 0 0 0 0}</code></td>
<td>Define how to play a certain chord, either an alternate finger to the one in Scriptasaurus's library or one not defined.
<ul>
<li>CHORD is the name of the chord;</li>
<li>"fret" followed by the four fret positions, beginning with "G" string. Indicate a "muted" string by using an "X" instead of a fret number.</li>
<li>"fingers" (optional) followed by the corresponding fingers to use on above fret positions</li>
</ul>
</tr>
<tr>
<td><code>{column_break}</code> or <code>{colb}</code></td>
<td>Marks the beginning of a new column. Supports up to four columns. Columns are automatically evenly divided (if two each is half the width, three columns of one third available width, etc). </td>
</tr>
<tr>
<td><code>{ukeGeeks-meta: ANYTEXT}</code></td>
<td>Additional info such as source, a video link, original perfomer etc. <em>Not a "standard" CPM tag.</em></td>
</tr>
</tbody>
</table>
<p class="topOfPage"><a href="#">Top</a></p>
</section>
<section id="contents">
<h2>Contents of the zip package</h2>
<p>This zip file contains all of the required JavaScript and CSS to run Scriptasaurus. It also has two examples of how you might run it: static HTML and dynamic PHP.</p>
<img src="img/documentation/file-folders.png" />
<ul>
<li>CSS & Javascript required by all setups</li>
<li>light green folders required by static HTML instatllation</li>
<li>light blue folders used by dynamic PHP installation</li>
<li>I've not included the image directory since it's only here to show the above image and not part of running the scripts.</li>
</ul>
<p>When first testing begin with the static setup before attempting the PHP setup.</p>
<p class="topOfPage"><a href="#">Top</a></p>
</section>
<section id="static">
<h2>Static Site Info</h2>
<p>If you'll be hand building your HTML (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.</p>
<p class="topOfPage"><a href="#">Top</a></p>
</section>
<section id="mvc">
<h2>Using the PHP "Lite" MVC Pages</h2>
<p>I've implemented a modified, "lite" Model-View-Controller architecture for this release. Why? This hopefully allows you to modify the page where the song actually appears (the "View") without need to worry about breaking any of the inner workings (hint: there aren't many inner workings either).</p>
<p>In a nutshell, here's a file/class overview:</p>
<ul>
<li><h4>The Controller & Config</h4>
<dl>
<dt><code>Ugs.php</code></dt>
<dd>…in this modified MVC design the Views instantiate an Ugs object and call the <code>GetBuilder</code> method that returns the appropriate View Model to be displayed.</dd>
<dt><code>Config.php</code></dt>
<dd>…as the name implies settings describing where files are and various options (such as "<code>UseModRewrite</code>" that changes URLs to work when Apache's mod_rewrite is enabled)</dd>
</dl>
</li>
<li><h4>The Views</h4>
<p>Pages that only echo values they are passed (these values are bundled into View Model classes). All your modifications will likely take place here -- layout, content, etc.</p>
<dl>
<dt><code>song-list.php</code></dt>
<dd>…lists all the songs found in your music library.</dd>
<dt><code>song.php</code></dt>
<dd>…renders a single song. This is the page that calls Scriptasaurus.</dd>
<dt><code>song-source.php</code></dt>
<dd>…just displays the unformatted original song source (CPM/text) file.</dd>
</dl>
</li>
<li><h4>The View Models</h4>
<p>The fully populated objects passed to the view. All View Model classes inherit from <code> _base_Vm.php</code>.</p>
<dl>
<dt><code>SongList_Vm.php</code></dt>
<dd>…data entity passed to <code>song-list.php</code>.</dd>
<dt><code>Song_Vm.php</code></dt>
<dd>…data entity passed to <code>song.php</code>.</dd>
<dt><code>Source_Vm.php</code></dt>
<dd>…data entity passed to <code>song-source.php</code>.</dd>
</dl>
</li>
<li><h4>The View Model Builders</h4>
<p>Instantiate appropriate View Model and does whatever's required to populate it.</p>
<dl>
<dt><code>SongList_Vmb.php</code></dt>
<dd>…populates the <code>SongList_Vmb</code> data entity.</dd>
<dt><code>Song_Vmb.php</code></dt>
<dd>…populates the <code>Song_Vm</code> data entity.</dd>
<dt><code>Source_Vmb.php</code></dt>
<dd>…populates the <code>Source_Vm</code> data entity.</dd>
</dl>
</li>
</ul>
<p>There is a one-to-one mapping of View to View Model to View Model Builder.</p>
<p class="topOfPage"><a href="#">Top</a></p>
</section>
<section id="mod_rewrite">
<h2>Using <code>mod_rewrite</code> For Pretty URL's</h2>
<p>Without <code>mod_rewrite</code> your PHP site will work fine, you'll just see page requests like this:</p>
<pre>song.php?song=filename</pre>
<p>This URL's "query param" named "song" tells the Builder class which song file to read and prep for easy rendering via Scriptasaurus.</p>
<p>However, instead of surfacing rather klunky URLs make use of Apache's <code>mod_rewrite</code> engine to convert a doopey URL such as:</p>
<pre>http://mysite.com/song.php?song=my-favorite-martian.cpm</pre>
<p>To the more friendly:</p>
<pre>http://mysite.com/songbook/my-favorite-martian.htm</pre>
<p>The included <code>.htacces.txt</code> 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).</p>
<p class="topOfPage"><a href="#">Top</a></p>
</section>
<section id="trouble">
<h2>Trouble Shooting</h2>
<dl>
<dt>Nothing's happening on sample songs</dt>
<dd>Make sure the page is finding the CSS and JavaScript files. You might need to…
<ul>
<li>adjust your web server "root" directory (did you install this in default directories?)</li>
<li>edit the page's script source and stylesheet link tags</li>
</ul>
</dd>
<dt>Server says "<em>File Not Found</em>" (404)</dt>
<dd>Check file locations.</dd>
<dt>PHP Error says "<em>Warning: include_once(ugsphp/Ugs.php) [function.include-once]: failed to open stream</em>"</dt>
<dd>Check where you've installed the MVC files used by the views. You may move them, but be sure that the config and the Views are able to locate the required files.</dd>
</dl>
<p class="topOfPage"><a href="#">Top</a></p>
</section>
<section id="license">
<h2>License</h2>
<p>This script is released for you to use as you see fit under a <a href="http://www.gnu.org/licenses/gpl.html">GNU General Public License</a>.</p>
<p class="topOfPage"><a href="#">Top</a></p>
</section>
</article>
</body>
</html>