fxhash documentation
fxhash documentation
The Boilerplate

The Boilerplate

The Boilerplate

An introduction to the fx(hash) boilerplate, a starting template to kickstart new projects.

The boilerplate is essentially a minimal, self-contained starting template that serves as a simple starting point for creating an fx(hash) project. It comes out of the box with all of the required files, and you|d just have to fill in the blanks to create an fx(hash) compatible generative artwork. You can download the starting template from this Github repository:

icon
What's a Boilerplate?

In the context of software development the term "boilerplate" often refers to a template or starting point for a project that includes a set of standardised code or files. These templates are designed to provide a foundation for building software applications quickly and efficiently.

Boilerplates help developers avoid starting from scratch and ensure that best practices and common functionality are already in place. For instance, a web development boilerplate might include a basic HTML structure, CSS styles, and JavaScript libraries to kickstart the development of a website. In the case of the fx(hash) boilerplate, it additionally includes the fxhash.js script file.

In the early days of fx(hash), artists needed to include a short snippet of code in their projects for them to be compatible with fx(hash) and function properly once uploaded. This snippet could be found on the fx(hash) site and had to be manually copy-pasted into the artist's project.

With fx(hash) evolving as a platform, and new features being added on a regular basis, this snippet quickly grew in size and had to be frequently updated to account for these changes. For the convenience of the artist, fx(hash) made a boilerplate available - a starter kit that already included this code snippet, becoming the go to method for kickstarting new projects.

Contents of the Boilerplate

Cloning the boilerplate from Github will download a zip file onto your machine - unzipping it will produce a folder with the following content:

image

This directory essentially contains the necessary files for creating a simple web page, just as we described in the previous section. It contains:

  • An index.html file that will act as the project entry point.
  • An index.js file that will contain the artist’s code that powers the generative artwork.
  • An additional javascript file titled fxhash.js that contains the helper functions provided by fxhash.
  • A styles.css file for styling purposes.
  • A LICENSE file in which you should declare usage rights of your code.
  • A README.MD file, which can safely be ignored. It's simply the file that provides the description of the boilerplate on its Github page.

You can actually go ahead and open the index.html in your browser now - although it won't much sense at this point, the page shown below is an indication that the boilerplate is working correctly:

image

Now let's have a closer look at the content of the different files in the boilerplate.

The index.html file

For the sake of completeness, let's talk just a little bit about HTML - opening the index.html file in a code editor will reveal the following:

<!DOCTYPE html>
<html>
	<head>
		<title>simple</title>
		<meta charset="utf-8" />
		<script src="./fxhash.js"></script>
		<link rel="stylesheet" href="./styles.css" />
	</head>
	<body>
		<script src="./index.js"></script>
	</body>
</html>

HTML primarily functions on a basis of tags that define and structure the content of the web page. These tags come in the form of specific keywords that are enclosed in angle brackets <> . Tags usually come in pairs: an opening tag and a closing tag containing some text, or other tags in between. The opening tag indicates the beginning of an element, and the closing tag indicates the end of that element. These tags are then used as instructions by the web browser to structure the content between these tags.

In the case of fx(hash) projects we're usually not going to write much HTML code, usually none at all - except maybe in a scenario in which the artist is creating a generative artwork with HTML and CSS. The index.html that comes with the boilerplate is a very simple web page that references the two js files, the fxhash.js file and index.js file, that are also found in the boilerplate folder.

Why is the fxhash.js script referenced in the head tag, whereas the artist's index.js script is included in the body tag?

It is common practice to include important scripts required for the proper execution of a web page in the head tag - scripts referenced in the head tag are loaded in before the page is actually run by the browser - this makes sure the fx(hash) functions are available when the time comes to execute the artist script. If you include third party libraries in your project, you should also reference them in this head tag.

A few other tags that also exist in the index’s head are:

  • title: the title tag is the title of the webpage, and should contain the name of your project. When your artwork is opened in live view, this title will appear as the title of the tab it is open in.
  • meta: some metadata information about the document, this is a standard tag that is included in every webpage. Usually it is left as is.
  • stylesheet: a reference to the css stylesheet that takes care of formatting the html document. This will simply bring in the styling instructions, if any.

Additionally, you can include a special tag in the head of your project in case you'd like the page to display a favicon when it is opened in live view - you'd simply drop the favicon file (a PNG or SVG file) in the project directory alongside the other files and link it as such:

<link rel="icon" type="image/x-icon" href="/favicon.ico">

A good example for this are loackme's projects - that always include a custom favicon:

image

The styles.css file

The styles.css in the boilerplate is empty - meaning that it applies no styling to the HTML. This file isn’t necessary, but often used for the purpose of displaying tokens correctly within the browser window, we address this in more detail in the

page.

The fxhash.js script

icon
This file should not be edited.

A standalone script provided by fx(hash) that exposes several functions required for creating platform compatible projects. The contents of this script file and its purpose are discussed in more detail in the

section.

The index.js script

This file should be completed by you, the artist, and should contain the code that creates the generative artwork displayed by the index.html. Right now, the boilerplate contains a bunch of code that produces the screen that we've shown above, you don't have to worry about what this information is at this point - it’ll make more sense after reading the Artist Tools section.

icon
But make sure to read the rest of the Artist Tools chapter first before you start building your generative token - there are actually a couple of different types of generative tokens for which it is recommended to use some of the more advanced artist tools instead of the simple boilerplate.

The LICENSE.txt file

This file should contain the License that you wish to apply to your project. Because files that are uplaoded to IPFS or OCNCHFS can be viewed an accessed by anyone, it is important to include a legal document that can help protect your intellectual property.

A License is essentially a document that details the usage rights for the code and the generated artworks; whether the code can be used and modified by others or not, and the specifics of it. You can read more about it and find suggestion for some common licenses in the Licensing page of the docs.