SkinGraft
From MODx Wiki
This page is a work in progress.
Contents |
Introduction
SkinGraft is a MODx template management module. It allows you to install template packages (zip files) edit templates, set defaults, etc...
Downloads
Download the latest version of SkinGraft from MODx repository.
Requirements
The SkinGraft module uses the pclzip.lib.php library for working with zip files. In order for SkinGraft to work, your server must have PHP compiled with zip archive support (almost all web hosts do). The XAMPP package does not come with this by default, so if you are using XAMPP for your local testing server, your results with SkinGraft may be mixed.
SkinGraft also makes use of the litebox JavaScript package which requires JavaScript to be enabled, but the MODx Manager uses tons of JavaScript, so this really isn't an issue, just giving credit to the creators of litebox and moofx (mad4milk) for their tremendous library and the utilities created with it!
Description
SkinGraft is a MODx template management module. It allows you to install template packages (zip files) edit templates, set defaults, etc...
Version 1.0 introduces the ability for template designers to fill out a form and have the code to make their templates "SkinGraft Compatible" automatically generated.
1.0 also improves with the ability to install chunks and template variables!
Features
- Automatically upload and install/update skingraft packages (files end in .sg.zip)
- Easily edit template code and attributes including setting default template for pages.
- SkinGraft 1.0 can now install chunks and tvs with your template package.
- SkinGraft will help you package your custom MODx template for use with SkinGraft!
- It will help you create files for packaging tvs with your template.
Installation
Easy installation
(Requires the MODx Resource Wizard)
- Download the archive.
- Go to your manager and run the MODx Resource Wizard Module
- Select the file "skingraft.modxpkg.zip" that you downloaded.
- Click the "Install this package" button, follow the instructions for install/update, and you are done!
Manual Installation
- Download and extract the archive skingraft.modxpkg.zip.
- Create a directory: [MODx Directory]/assets/modules/skingraft
- Copy the files into [MODx Directory]/assets/modules/skingraft/
- In your manager, create a new module named "SkinGraft".
- Copy the contents of "sg.module.txt" into the "Module code (php)" Textarea.
- Click the "Configuration" tab.
- Put "&mod_lang=Language;string;english" (without quotes) into "Module configuration:".
- Save, and run the module.
Usage
Beginning
When you first run the SkinGraft module, you will see a list of existing templates in your assets/templates folder. They will be in a default state, since their data (such as a preview image) won't be in the database. You can edit quite a bit of a template's data by selecting its radio button, then at the bottom, clicking the "Edit Selected" link.
To run skingraft, go to Modules/Manage Modules, and then click on the "icon" box to the left of the skin graft entry.
Editing a template
When the "Edit Selected" window opens, you can now edit the template, and also edit its preview image location, name, description, and the name of the folder it resides in if it has not been set (for example in templates that were not installed by SkinGraft it says PLEASE_DEFINE). You can make changes to the HTML code here, as well as choose to use this template as the default, and to change documents to use this template.
Installing a new template
To install a new template, click the "Install New" button at the bottom of the main page. You will be presented with an upload form. Select the template.sg.zip file you want to install and press "Install" . The installer will give you updates as to what will be installed along with your template and what non-standard (not included in the default installation) resources may be reqired. It also lets you see a preview image of the template you are about to install.
Select a .sg.zip template file.
See what is getting installed.
The file will be uploaded, unzipped, and the appropriate files installed in the proper folders and the template itself inserted into the database.
Making a SkinGraftable Template
The main thing that makes a template Graftable is the existence of the skin.php file in the .zip archive. There are a very few other requirements to making a template Graftable.
The .zip archive must unzip to a folder with the same name as is used in the links to the CSS file and any images the template uses. It must have a plain-text file that contains the HTML that gets inserted into the database. This is the same file that would be opened in a text editor and copy/pasted into a new template in the Manager. The name of the file doesn't matter, since you will specify the template file's name in the skin.php file. The folder should also contain the CSS file and images, as indicated by the paths in the template head and in the css file itself as far as background images go. A copyright notice and license would also be appropriate here. Also any extra files, such as js files that the template needs.
You should also include an INSTALL.TXT file for instructions on a manual installation, as well as instructions for any extra chunks or TVs the template uses. And don't forget a screenshot to use for the preview image!
SkinGraft 1.0 now provides a form you can fill out to automatically generate your skin.php file. From the main page, click "Create New" and you will be brought to a form that takes all the required information and returns the skin.php code for you to copy and paste into your own "skin.php" file.
SkinGraft Chunks
- If your template requires additional chunks, create a plain text file with the chunk code in it an name it with the extension ".chunk". if your template calls for the chunk {{footer_links}} you should call the chunk file "footer_links.chunk". As a common courtesy to not overwrite existing chunks that the user has created, name your chunks with the prefix of your template. for example {{scottstemplate_footer}} and {{scottstemplate_validate}}. Using these examples, you could include both chunks in your skin.php file by putting 'scottstemplate_footer','scottstemplate_validate' in the form for chunks. the form field chunks must be in single quotes (and separated by commas if there is more than 1!), because it is a PHP array.
SkinGraft Template Variables
- SkinGraft can also install custom Template Variables. There is, however, a specific formatting for creating SkinGraft installable TV's. SkinGraft will look for TVs as files in your template folder with the extension ".tv" If you have a TV called [*scottstemplate_sidebar*] the file in your template folder would be "scottstemplate_sidebar.tv". It contains a list of PHP variables describing to SkinGraft how to install the TV. To create a SkinGraftable TV, from the main page press "Create New", then scroll to the bottom and press "Create TV". You will be presented with this form. Fill out the form with the attributes required for your TV (this form should look very similar to the form for creating a TV in the manager), then press "Create TV" again and you will be brought to this page where you can copy and paste the code into the yourtemplatevar.tv file (it even gives you the name you need to give your file in order for it to be installed correctly!).
Finishing Notes
Once all your files are in place in the folder, zip your folder and name it with the extension "sg.zip" and upload it to the MODx repository. Remember to give it an additional tag of "SkinGraft" to make it easy to find SkinGraft compatible templates.
Screen Shots
The main page |
The main page with preview |
The Language page. |
The new language. |
The Edit page. |
The Edit page with a preview. |
Set a new default template. |
Delete a template. |
Install a new template. |
Description of the new template. |
Preview the new template. |
Template installed! |
Create template form. |
The data you need. |
Create a template variable. |
The tv code. |
Tips & Tricks
--ScottyDelicious 12:07, 12 November 2006 (PST)
