Tinker

Devolopers

Getting Started

Whether you're starting from scratch or just want to add quick and easy editing to an already existing site, getting Tinker up and running on your site takes just a few minutes.

Installing Tinker
Installing Tinker is a generally straight-forward process. There's no database to set up and the installer will guide you step-by-step. If you are installing on a remote web server, you will need FTP access to the server to upload files. 
  1. Backup your site if you already have content that you don't want to lose forever in the unlikely case that things go terribly wrong
  2. Download Tinker and upload the 'tinker' folder to the root folder of your site
  3. Navigate to the 'tinker' folder on your site (eg. http://yoursite.com/tinker/)
  4. Tinker will guide you through the installation process, including creating a user account, setting up files, etc.
  5. If you are working on an already existing site, you'll need to modify your files to be editable (see below).
  6. Start editing!
Working from Built-in Page Templates
(Very easy, requires no coding knowledge)

If you don't have any pages built or if you just don't want to mess with code, Tinker allows you to build a site completely from built-in page templates. To use these templates, enable the template package you want to use in the Templates section of Tinker's admin panel and all of the templates in that package will be available the next time you create a new page.

More pre-made templates will be available for Tinker soon, and if you're interested in making your own template package, check out the template packages section below.

Installing Tinker on AN existing HTML site
(still easy, requires a little code)

Tinker works great with already built HTML sites, and making a page tinkerable typically takes just a couple minutes.

During the installation process, Tinker will automatically detect any pages it thinks you might want to make tinkerable. Clicking the 'install tinker' button next to that file will insert a small script on the page and add the page to the list of pages in Tinker's config file. Don't worry if you miss a file or skipped this step, you can install Tinker to any web page by going to the 'Files' page in Tinker's admin panel.

After Tinker has been installed on a file, you will still need to add the tinkerable attribute to any elements you want to edit in your HTML. Read our templates documentation to learn more about this and other Tinker attributes.

Using Tinker

Most of Tinker's features can be used without ever opening up the admin panel, but getting the most out of Tinker may take a bit of familiarity with it. 

Site Files

The 'Files' page in the admin panel allows you to control which pages are tinkerable and set default paths for things like where media files are uploaded for your site. 

Making Pages Tinkerable

Before you can edit an already existing page in Tinker, Tinker has to insert a link to a small script into the HTML. On the 'Files' admin page, any HTML files that don't have the script installed will show up as grayed out. Click the 'Install Tinker' button on a file to register that file in Tinker's settings and to add the script link.

Creating New Pages

The easiest way to create a new page in Tinker is to create a link to a page that doesn't exist and then double-click that link to navigate to the new page. 

When Tinker detects that a page doesn't exist, it brings up a special page to either duplicate an existing page or use a template (if you have a template package enabled). Click the file you want to use to create your new page and, voila!, your page is created!

You can also create new pages from the 'Files' admin page by clicking the 'Add Page' button and following the same steps as listed above.

User Accounts

Different people involved in running a site need access to different parts of that site. Tinker offers three different user types to help site owners control access, and to keep the interface as simple and uncluttered as possible for everyone.

Admin

In a nutshell, Admin accounts have access to everything, including files, site settings, and even controlling other user's accounts. It feels good to be in charge!

Author

Authors can create new pages, edit page info (eg. page titles and descriptions, etc.) and edit all content. Their access in the admin panel is pretty much limited to editing their own account information.

Editor

Editors are restricted to editing only page content.

Updating Tinker

Tinker has an automatic update system, which allows you to keep Tinker current with a simple click of the mouse. If there's a new version available, you'll see an 'Update Available' link in the bottom-right corner of the Tinker admin panel.

If you are having troubles with this process, or if you want to go back to a previous version of Tinker, it's also possible to upgrade Tinker manually as well. Just download the version of Tinker you want and replace the 'core' folder inside the 'tinker' folder with the version you want to change to. 


Dev & Production Deployment

Tinker was built with a multi-environment development process in mind. The Tinker admin page will automatically detect when the URL on your site changes and ask you if you want to update your settings accordingly. 


You can also dictate different settings for each environment separately by setting the differing settings in your config.local.json file.

config.local.json

The config.local.json file sits alongside the standard config.json file, and any settings inside it will overwrite the standard setting when Tinker is loaded. This setup allows you to make changes to your site content and settings that will persist across environments but still have some settings that are "hard coded" to each location.

Note: You'll want to add config.local.json to your .gitignore file if you are using git to manage your site over different locations. 

Here's an example of how you might overwrite some of the basic site settings in your config.local.json file:


{
   "site_name": "Site Name DEV",
   "root_url": "http:\/\/localhost\/",
   "root_path": "\/path\/to\/site\/files\/"
}

HTML & Templates

Tinker works with plain ol' HTML to control and store the content on your site. You can add Tinker's features directly to the HTML pages in your site by adding some of the attributes below, or you can package your templates to share or re-use between sites.

HTML Attributes

Controlling which elements can be edited, and how they respond to different events, is handled almost exclusively through HTML attributes. 

tinkerable

The 'tinkerable' attribute is the key component for making an HTML Adding this attribute will make that element and all of its children elements editable.

<p tinkerable>Lorem ipsum</p>

<p tinkerable="content_only">Lorem ipsum</p>
Options:
tinkerable or tinkerable="all" (default)

All content inside this element—including images and backgrounds—will be editable by the user. If no value is given for 'tinkerable', 'all' is assumed.

tinkerable="content_only"

Only text content can be edited in this and child elements

tinkerable="background_image_only"

Only the background image on this element (not children) is editable. 

tinkerable="none"

"none" is used when you want to disable editing on a certain element when it's inside of an a parent element that is editable.

tk-[attribute]="[value]"

This attribute will let you dynamically set an attribute on an element, using info from Tinker such as site URL, site name, etc. The attribute will be updated the next time a page is saved or Tinker settings are updated.

<a href="http://yoursite.com/" tk-href="{site_url}">

<img src="http://yoursite.com/img/friendly_puppy.png"... tk-src="{site_url}/img/friendly_puppy.png">
tk_preserve

Automatically bring element back after Tinker has loaded. This may be necessary if a section of your page is modified by javascript after the page has loaded.

<div tk_preserve="restore_after_page_load"></div> 
tk_dontsave

Elements with this attribute will be removed from your HTML before being saved back to the server. This is especially useful when you need to prevent content generated by javascript from being saved to the server.

Global Blocks

Global blocks allow you to re-use the same block of HTML in multiple files. Changing a global block on any page will alter that same block on all of the rest of the pages. 

To have any two blocks of HTML be linked, simply give them the 'global_block' attribute with the same value, like so:

<header global_block="block_name">

Content Blocks

Content Blocks are pre-defined sections of a page that can be added, deleted and re-arranged on your web page easily. If your template includes Content Blocks, you can add them to your page by opening the Content Blocks tab on the right-hand side of the page editor and dragging them into your site content. You can re-arrange them or delete a Content Block by using the buttons located on the left side of the block in your page content.

To add Content to your blocks, simply add a file named 'content-blocks.html' to the root folder of your site (or template package folder), fill it with Content Blocks (making sure that each block has a 'content_block' attribute) and Tinker will add them to the Content Blocks panel in the editor the next time you load your site.

content-blocks.html

Below is an example of what a content-blocks.html might look like. Note: you will probably want to include a link to your site's stylesheet in your content-blocks.html because it gets loaded as an iframe and does not inherit styles from your site.

<link rel="stylesheet" href="style.css" type="text/css">

<div class="block_example1" content_block>
  <h3>Lorem Ipsum</h3>
  <p>Lorem ipsum dolor set...</p>
</div>

<div class="block_example2" content_block>
  <h3>Lorem Ipsum</h3>
  <p>Lorem ipsum dolor set...</p>
</div>
content_blocks & content_block

Content Blocks can only be added to container elements with a 'content_blocks' attribute on them, and every child element of a content_blocks container should have the ' content_block' attribute. The content_block attribute applies important styling as well as makes it sortable with the other blocks around it, so it's important to include it.

<div content_blocks>
  <div content_block>Lorem ipsum...</div>
  <div content_block>Lorem ipsum...</div>
</div>

Repeater Blocks

Repeater Blocks are page sections that contain a list of similarly formatted content, like image galleries, blog post lists, etc. They are similar to Content Blocks in that they can be easily added, sorted and deleted by clicking or dragging the blocks on the page. What makes Repeater Blocks different is that instead of adding new blocks from a list of pre-made blocks that are available to all lists, new content follows an HTML template that is specific to that Repeater section. 

repeater_blocks & repeater_block 

All elements with a 'repeater_block' attribute will have buttons for sorting and removing itself added to it when the page is loaded. They can only be moved inside their parent element (marked with the 'repeater_blocks' attribute).

<div repeater_blocks>
  <div repeater_block>
    <h3>Block 1</h3>
    <p>Lorem Ipsum...</p>
  </div>
  <div repeater_block>
    <h3>Block 2</h3>
    <p>Lorem Ipsum...</p>
  </div>
</div>
repeater_template

Adding a 'repeater_template' element to your Repeater Blocks container will allow you to define what a new block looks like when added to your Repeater section. If no repeater_template is given, the last repeater_block is used instead. Of course, that won't work if you've accidentally deleted all of your blocks, so creating a template is definitely recommended!

<div repeater_blocks>
  <div repeater_block>
    <h3>Block 1</h3>
    <p>Lorem Ipsum...</p>
  </div>
  <div block_template>
    <h3>New Block</h3>
    <p>This will appear when a "Add Block" is clicked.</p>
  </div>
</div>

Template Packages

Page templates come in "template packages" that contain HTML and CSS files with outlines for as many page types as you want. These files act as starting points when creating a new page on your site, and they are grouped together in packages so that all of the pages in that package have a cohesive design.

Files
style.css

This file holds all of the page templates' styles, as well as the template package name and description information. This information is stored at the top of style.css in a comment like so:

/*
Name: Template Package Name
Description: A brief description of the package
Author: Your Name
Version: 1.0
*/
template-[name].html

Each template you want to include your template package needs to be created as a separate HTML file with a filename starting 'template-'. You can give the template a name and a brief description in a comment at the top of the HTML file like this:

<!--
Name: Template Name
Description: A brief description of this template
-->
content-blocks.html

If the template was built to use Content Blocks, creating a file called content-blocks.html and adding your content blocks to it will cause Tinker to load them in the Content Blocks panel of the page editor when your template pack is enabled.

Plugins


Coming Soon!

UI Themes


Coming Soon

API


Coming Soon!