v0.1.0 JavaScript Object
v0.1.0
Below, all the customizable settings and their defaults are displayed:
new Showpony({
window:undefined //Will throw an error if unset
,path:"parts/"
,files:"get"
,start:"last"
,loadingClass:null
,scrubLoad:false
,query:"part"
,info:"[0pc] | [0pl]"
,data:{}
,defaultDuration:10
,admin:false
,dateFormat:{year:"numeric",month:"numeric",day:"numeric"}
,autoplay:true
});
Objects are the same for every medium, and with this option you can have multiple Showpony objects on your page, without their code colliding with other Showpony objects.
These can be set at the beginning, but can also be set or accessed from the Showpony object at any time (as long as you've assigned it to a variable).
The element the Showpony will display inside. You'll generally want to use a div with a set width and height, or maybe a fullscreen div. Defaults to null. If null passes, you will get an error and Showpony will not run.
The path to the files specified in parts. Defaults to "" (the current folder)
Either "get" (which automatically gets the filenames for you) or an array of the files you want your Showpony object to display in the specified path. Defaults to "get"
What file you start at. This can be "last" or a file number (0 being the first file). Defaults to "last"
A class applied to the Showpony window element (not the actual browser window) while it is loading. You'll want to set the class values in your own CSS. Defaults to null
Determines whether or not on scrubbing the timeline from the menu you will automatically load files as you scrub. This can result in a more dynamic experience that allows users to find exactly what they're looking for, but it can also be slow and take up a lot of your bandwidth unnecessarily. Defaults to false
Allows you to save the current part in the URL inside of a querystring, like example.com?part=1. This will also let you load parts by the URL (if you go to example.com?part=3 you'll start at part 3), and use the browser's back and forward buttons to return to previously read pages and proceed back. If set to false, none of the features previously mentioned go into effect. If set to a string, that string will determine the position; you can set the string to whatever you want (which also allows support for multiple Showpony querystrings on one page). Defaults to "part"
Sets the display of info in the menu. It has many special values:
- [n] passed the filename
- [d] passes the current date
- [0pc], [0pl], [0pt] passes the current part, parts left, and parts total, respectively
- [0hc], [0hl], [0ht] passes the current hour, hours left, and hours total, respectively
- [0mc], [0ml], [0mt] passes the current minute, minutes left, and minutes total, respectively
- [0sc], [0sl], [0st] passes the current second, seconds left, and seconds total, respectively
The 0 before certain values can be changed to a number between 1 and 9. Up to that many leading zeroes will then precede that number [2pc] would show 01, while [4pc] would show 0001. Defaults to "[0pc] | [0pl]"
is data used in the Multimedia Engine (used for Kinetic Novels, Visual Novels, and Interactive Fiction). It starts out empty by default, but you can also access this object to set default values or load in values from elsewhere.
The length assumed for a file if a length is not set in the filename. Defaults to 10
Allows you to access the administrator panel (if it's set up properly in PHP to be accessed). Defaults to false
Sets the format of dates in info. This object is passed directly to an Intl.DateTimeFormat object's options. Look under "Syntax", "Parameters", "options" at the link for more info. Defaults to {year:"numeric",month:"numeric",day:"numeric"}
Whether or not to start paused. This can be helpful for videos although it's probably better to just have Showpony activate on clicking the div at that point rather than start paused, because it can look kinda weird. Really, more like "autopause". Defaults to true
You can't set these on startup, but you can access them later.
Holds an integer value for the current file (starts at 0).
Saves the state of the original window, before Showpony started tweaking it. This object is saved so that if you want to close Showpony, you can set its window back to its original state. I recommend using the close() function rather than touching this though.
Adjusts the place inside of the story.
part starts at 0 (not 1) and can be set to a number, or adjusted with the values "first", "prev", "next", and "last". Defaults to currentFile (which you can see under Variables).
scrollToTop determined whether or not to scroll to the top of the file on loading. Defaults to true
refresh refreshes a file. Not recommended, there for internal code. Defaults to false
reload is there as a simple safety measure. Not recommended, there for internal code. Basically, if you're an admin and you are on the final file, and you delete it (or log out), you will effectively suddenly be at the end of the story. Reload can keep you from being considered at the end in this case and will just pull you back to the final file. Defaults to false
popstate is recommended to be left alone to the engine. It controls whether or not a history state is updated on going to a part (this is what allows using the "back" and "forward" buttons effectively in your browser). Defaults to false
Toggles the menu.
Updates the value of the menu overlay. You'll probably never want to use this.
percent is a percentage of progress for the scrub bar to be at. 0% means it's all the way left; 50% means it's in the middle; and 100% means it's all the way right. It can't be less than 0% or greater than 100%.
Closes the Showpony, resetting the window specified in settings to what it was before Showpony started.
Toggles fullscreen.
Imitates a click on the screen, regardless of the medium. input() acts differently for different media: for images it moves to the next one, for video and audio it pauses and opens the menu, and for stories in the Multimedia Engine it progresses (unless the user has to select an option).
All of these events run on the window, not the Showpony object. You can listen for them with addEventListener.
Updates whenever the time or file in use for Showpony changes. You can use this is to update values based on Showpony's current part number; for example, you can have a heading's value change from "Part 1" to "Part 2" when you progress to part 2 in your story, and so on.
Returns value current, which states the current file we're on. This is based on the reader-viewed part number, so it doesn't start at 0 like you would get if you directly read currentFile's value.
NOTE: this may be buggy right now. If it is, just access currentFile instead and add 1 to its value (you may have to parseInt(currentFile) to get it right).
Runs when we reach the end of a story and finish it up. By default, nothing happens, but you can have it close() the Showpony object or do whatever you like.
Runs when we toggle the menu.
Returns opened, which is true if the menu is now open and false if the menu is now closed.
