Customization

There are several ways to customize ComicControl based on your level of comfort with coding and manipulating the files and database for your site.  Though we are continuously working to make customizing your site more accessible to newbies, there are some elements that are inherently limited to those with coding skill.  Below, we’ve listed various avenues of customizing your ComicControl site, as well as the skills necessary to use that avenue, from no coding skills to advanced coding skills.

Site and Module Options

For every installation of ComicControl, there are two levels of options available for changing the functionality of your site: site options and module options.  The site options are available on the main menu in the ComicControl backend.  There are different module options available for each module, which can be found on the module’s main page listed as “Module Options”.  Below are descriptions of each site and module option and what they change on your site.

Site Options

Site title

This is the title for your ComicControl site.  This is displayed in the ComicControl backend, and in the default template, it is displayed at the top of the tab in your browser.

Home page

This option is a dropdown that allows you to choose the default module that is shown when a user visits the site’s root.  For example, if you have the module “News blog” selected for your site www.example.com, the “News blog” module will be displayed when the user visits www.example.com.

Admin language

This is the language that the backend will be displayed in.  By default, only English is available.  To install languages, please see the section below about adding languages to ComicControl.

Time zone

This is the time zone that your site will operate in.  This dropdown contains all possible time zones within PHP, so please refer to the PHP manual if you need more clarification on this list.

Date format

This is the format in which dates will be displayed on your site.  The list contains possible ways to display the date February 1st, 2016, so please select the format that you prefer based on this.

Time format

This is the format in which times will be displayed on your site.

Disqus shortname

This is the “shortname” associated with the disqus forum you’d like to use for your site’s comments.  If this is blank or does not refer to a valid disqus forum, comments will not work properly on your site.

Meta description

This is the default description that will be listed for your site on any modules where you have not set a description in that module’s options.  This description will be displayed in search engines and sometimes it will be used by social media that are indexing your site.

.htaccess prepend code

This text area contains any extra .htaccess directives that you would like added to the beginning of your site’s root .htaccess file.  IF YOU ARE NOT VERY CONFIDENT IN YOUR ABILITY TO MODIFY .HTACCESS FILES, DO NOT EDIT THIS.  You can break your site in such a way that you will need to manually edit files on the server and information in the database if you do not know what you’re doing!

.htaccess append code

This text area contains any extra .htaccess directives that you would like added to the end of your site’s root .htaccess file.  IF YOU ARE NOT VERY CONFIDENT IN YOUR ABILITY TO MODIFY .HTACCESS FILES, DO NOT EDIT THIS.  You can break your site in such a way that you will need to manually edit files on the server and information in the database if you do not know what you’re doing!

Module options - all modules

These are the options available for all modules:

Page title

This is the title that will be displayed for this module if it is being shown on its own page.  In the default template, this title will be displayed next to the site title in the page’s tab in the browser.  This is sometimes also displayed on the page itself if certain options are selected for galleries and pages.  This page title will also determine the “slug” that will identify the module’s direct URL.  For example, if you name a module “Example Module”, the slug will be “example-module”; if your site is at example.com, the URL for the module will be “example.com/example-module”.  The module URL is displayed with the module options once the module has been created.

Display language

This is the language that any default text for the module will be displayed in.  This cannot magically translate your site, but certain default pieces of text, such as “Previous” and “Next” when navigating through pages of results, will be displayed in the language selected here.  By default, only English is available.  To install languages, please see the section below about adding languages to ComicControl.

Page template

This is the template that will be used to display this module when it is displayed by itself.  These files are pulled from the templates/ folder in the main site directory.  This template is not used if the module is displayed as a single element in a template or other page.

Meta description

This is the meta data description that will be used for this module when it is displayed by itself.  If nothing is listed here, the default description for the site will be used. This description will be displayed in search engines and sometimes it will be used by social media that are indexing your site.

Module options - comic modules

These options are only available for comics.  

Comic display options: The below options determine how your comic’s pages and news posts will be displayed.

Max comic width

This option determines how wide, in pixels, the comic will be saved as. If you upload a high resolution version of your comic, it will be resized down to this for display on your website. If you have the option selected to display an enlarged version of the comic when the page is clicked, the higher resolution, non-resized version of your comic will be displayed.

News display mode

This option determines what news will be displayed with your comic. If you select Each Post, the news post you enter for each comic will be displayed, even if it is empty. If you select Latest News, the latest non-empty news post will be displayed with your comic post.

Display tags

This option determines whether or not tags will be displayed in the news post for your comic. Tags are displayed as a list above the comments section (or at the bottom of the post if comments are disabled). Clicking a tag allows a user to search for comics with the same tag.  If this option is set to no, the line to edit tags when adding or editing a comic will not be displayed.

Use transcripts

This option determines whether or not a comic transcript will be displayed in the news post for your comic. If this option is selected, you will be able to input a transcript for your comic pages, and that transcript will be displayed. If this option is set to no, the area to edit the transcript when adding or editing a comic will not be displayed.

Click to view transcript

This option determines whether or not the comic transcript will be hidden in a collapsed section in the news post. If this option is selected, then the comic transcript will be hidden until the user clicks a button to display the transcript. This option is ignored if the display transcript option is off.

Use content warnings

This option allows you to use content warnings on your pages. This will allow you to add content warnings to a page if that page has sensitive content that you wish to hide until the user agrees to view it. If a content warning is added to a page, that page is blurred until the user clicks away the content warning.   If this option is set to no, the line to edit the content warning when adding or editing a comic will not be displayed.

Display comments

This option determines whether or not comments are displayed with the news post of a comic page. Comment systems are run and moderated through Disqus, and you must set up a Disqus account in order to use comments.

Comic navigation options: These options determine the functionality and display of your comic’s navigation elements.

Navigation buttons

These options dictate the order in which navigation buttons will be displayed for your comic. First advances to the first comic in the section; previous goes back to the previous comic in sequence; next goes to the next comic in sequence; last goes to the latest published comic. Auxiliary means that an auxiliary button will displayed, leading to either an RSS feed or the comic archive based on your choice. None means that no navigation button will be displayed in this slot.

Auxiliary button destination

This option determines where the user will be directed upon clicking the auxiliary navigation button, if you choose to use that. RSS will direct the user to an RSS feed for your comic; Comic Archive will direct the user to the comic's archive page.

Action on clicking comic

This option determines what action will be performed when the comic page is clicked. If the Advance to Next Comic option is selected, the user will be directed to the next comic in sequence if they click on the comic page. If the Enlarge Comic option is selected, a lightbox with the higher resolution version of the comic page will be displayed in the browser when the page is clicked.  If the Enlarge comic when oversized option is selected, the comic will only be enlarged if the high resolution version is higher than the “Max comic width” option above.

First button text

This option determines what text will be displayed for the first navigation button. This can be left blank or can include an image tag as well if you prefer to use graphical buttons.

Previous button text

This option determines what text will be displayed for the previous navigation button. This can be left blank or can include an image tag as well if you prefer to use graphical buttons.

Next button text

This option determines what text will be displayed for the next navigation button. This can be left blank or can include an image tag as well if you prefer to use graphical buttons.

Last button text

This option determines what text will be displayed for the last navigation button. This can be left blank or can include an image tag as well if you prefer to use graphical buttons.

Auxiliary button text

This option determines what text will be displayed for the auxiliary navigation button. This can be left blank or can include an image tag as well if you prefer to use graphical buttons.

Mobile navigation options: the options below only apply to comic module when your site is being accessed on a mobile device.

Action on tapping comic

This option determines what action will be performed when the comic page is tapped on mobile devices. If View Hovertext is selected, the hovertext for the comic (if there is any) will be displayed over the page. If Advance to Next Comic is selected, the user will be directed to the next comic in sequence.

Action on swiping

This option determines what will happen when the user swipes the comic on a mobile device. If Navigate comic is selected, they will be able to navigate to the next and previous pages with swipes. If Do nothing is selected, nothing will happen on swipes.

Archive options: The below options apply to your comic module’s default archive, which can be accessed at example.com/example-comic/archive.

Maximum thumbnail width

This option determines the maximum width that page thumbnails in your comic archive and comic searches will be.

Maximum thumbnail height

This option determines the maximum height that page thumbnails in your comic archive and comic searches will be.

Display chapter thumbnails

If this option is selected, the thumbnail of the first page of the storyline will appear next to the storyline title in your comic's archive.

Display page thumbnails

If this option is selected, thumbnails for every page will be displayed below their respective storyline titles in your comic's archive.

Display page titles

If this option is selected, the titles of every page will be displayed below their respective  storyline titles in your comic's archive.

Results per page

This option determines how many results will be displayed per page when you search for comics by tag.

Module options - blog modules

These options are only available for blogs.

Post options: These options determine how each blog post is displayed.

Display comments

This option determines whether or not comments are displayed with your blog post.  Comment systems are run and moderated through Disqus, and you must set up a Disqus account in order to use comments.

Display tags

This option determines whether or not tags will be displayed with your blog post.  Tags are displayed as a list below the blog post content.  Clicking a tag allows a user to search for posts with the same tag.  If this option is set to “No”, the line to edit tags when adding or editing a blog post will not be displayed.

Archive options: These options determine how the blog archive will be displayed, accessed at example.com/example-blog/archive.

Posts per page

This option determines how many posts will be displayed per page in the blog archive.

Archive order

This option determines the chronological order in which posts in the blog archive will be displayed.

Module options - gallery modules

Text display options: These options determine whether to display the text elements of the gallery module.

Display title

This option determines whether or not the title of the gallery module will be displayed at the top of the gallery module content.

Display description

This option determines whether or not the description of the gallery will be shown when it is displayed.

Thumbnail options: These options determine the size of thumbnails generated for the gallery images.

Thumbnail width

This option determines the maximum width of gallery thumbnails.

Thumbnail height

This option determines the maximum height of gallery thumbnails.

Module options - text modules

Display title

This option determines whether or not the title of the text module will be displayed at the top of the text module content. 

The Basic Template

There is one basic template included in new installations of ComicControl, which is contained in "templates/basic/" within the main files of the site.

The basic template contains these files:

• includes/header.php - This file contains the header code for the template.  It performs these basic functions:
  • Displays the site title and module title for each page in the browser tab’s header
  • Displays the site name at the top of the page, which links to the site homepage
  • Displays a basic menu with a button for the home page, an about page, and a contact page.  You must create an “About” and a “Contact” module for the latter two links to work.
• includes/footer.php - This file contains the footer code for the template. By default it displays a link to the ComicControl website.  
• comicpage.php - This file is the main template file for displaying comic modules.  It displays the header, followed by an area to display the comic page and navigation, followed by an area to display the news post and comments, followed by the footer.
• page.php - This file is the main template file for displaying all other modules. It displays the header, a blank space that will be filled by the module content, and the footer.

There are also other basic templates available on the download page.  To use the templates, simply download the template, unzip it into the "templates/" folder, and choose the appropriate template file when creating your modules.  When using these basic templates, it is recommended that you choose “comicpage.php” for comic modules and “page.php” for all other modules. 

Customizing Templates

If you wish to customize the basic templates, or create your own, there are a few fundamental pieces of information that will help you understand how the templates work:

• Each module uses only one template file.  These files, however, can include other files, which you may wish to use if you are using the same template segments, such as a header and footer, on multiple template files.
• If you wish to have small segments of code, such as a header or footer, which you won’t be using as actual template files, it is recommended you put these in an includes/ folder within the template folder.  This will hide these files when you are selecting templates.  For example, the basic template has a header.php and footer.php file in the includes/ folder; these are hidden when you are selecting a template file for your module. 
• All templates are basic PHP files, and they are not compiled from any other source.  The only thing special about these PHP files is that ComicControl’s main code base is loaded before the template is, which gives you access to various special functions that can be used to display your site content in a useful way.
• The specific “ComicControl” parts of your site are generated by using these special functions preloaded by ComicControl before your template is implemented.  To see specifically which functions are available, please see the “Available functions” section below.
• Some modules use pre-written CSS, which is contained in comiccontrol/defaultstyles.css.  This file is overwritten whenever ComicControl updates, so if you wish to override these styles, please use your own CSS file in the root directory of your site or the templates/ folder.

This is basically all you need to know for building and editing your templates.  Beyond these pieces of information, you can do whatever you wish with HTML, CSS, JS, and PHP to build your site.  

Making Your Own Template

In order to make your own template, all you need to do is create a PHP file containing your template and upload it to the templates/ folder.  That file will then be selectable as a template for your modules.

Here are some other recommended standards to follow when building your template:

• Give each group of associated template files its own subfolder in the templates/ folder.  For example, all necessary files for the basic template are contained within the templates/basic/ folder.
• Any files that do not end with .php will be ignored when you are selecting a template for a module, as well as any files in an includes/ folder.  Therefore, any CSS files, JavaScript files, and images will not be selectable as modules, and can be safely uploaded to your template folder.
• If you include CSS and JavaScript files in your template folder, these files will be editable in the “Templates” section of your backend, along with all PHP files in your template folder. Images and other filetypes will not be editable.  If you wish any files to be editable, please ensure they are using a .php, .js, or .css extension.
• You are free to use the basic template as a starting point for your template. However, please note that the actual "basic" folder is overwritten during updates, so if you wish to start customizing, please copy these files to a folder with a different name.

Available Functions

There are various functions that are available to be used within templates.  To see every function available, please refer to the classes & functions section in the documentation. Below are some useful PHP code snippets that you may find yourself using when building your template.

Italicized portions are code that will be changed based on your site.

$examplemodule = $ccpage->buildModule(“slug”);
This code builds the module with the slug slug and stores it in the variable $examplemodule.  This can be used to access a module’s content at any point in a template.  

$ccpage->displayTitle();
This code outputs the title of the current page.

$ccpage->displayMeta();

This code outputs the meta tags for the current page.  Currently, this only displays the “description” meta tag.  This should only be used in the tag of the template.

Functions for all modules

The below examples use $examplemodule as a stand-in for any module, but note that the main module in any page can be accessed with $ccpage->module.  For example, to use display() for the current page's main module, you can write $ccpage->module->display(); You can see examples of this in the basic template.

$examplemodule->display();

This code displays the content of the module.  For a comic, this only displays the current comic page.  For all other pages, the whole module is displayed.  For a blog, the content displayed depends on the URL, and either the archive, a single blog post, or a tag search can be displayed.

Functions for comic modules

$examplemodule->navDisplay();

Displays the comic navigation based on CC_Page’s URL information.

$examplemodule->displayAll();

Displays the news post for the comic and, if enabled in the module options, the comic’s transcript, tags, and comments.

$examplemodule->displayNews();

Displays the news post for the comic post.

$examplemodule->displayTags();

Displays the tags for the comic post.

$examplemodule->displayTranscript();

Displays the transcript for the comic post.

$examplemodule->displayComments();

Displays the comments for the comic post.  Currently only allows Disqus comments.

$examplemodule->displayDropdown();

Displays a dropdown with all the comic pages which navigates to the selected page on change.

$examplemodule->displayChapters()

Displays the storylines of the comic in archive format, dependent on the archive options set in the comic’s module options.

$examplemodule->search()

Searches the module for tagged comics based on CC_Page’s URL parameters.

$examplecomic = $examplemodule->getComic();

Retrieves the information for the comic currently selected in the URL; if a comic is not found for that information, then this function returns the latest comic.

$examplecomic = $examplemodule->getPost(“slug”);

Retrieves the information for a specific comic post with the slug slug.

$examplecomic = $examplemodule->getSeq(“direction”);

Retrieves the information for the first, previous, next, or last comic.  direction can be either first, prev, next, or last.

Functions for blog modules

$examplemodule->recentPosts(num)

Displays num number of recent blog posts.

$examplemodule->displayTags(postid)

Displays the tags for the blog post with ID postid.

$examplemodule->displayComments($post)

Display the comments for the given blog post item $post.

$examplemodyke->displayPosts($posts)

Format and display the given array of posts $posts.

$examplepost = $examplemodule->getPost("slug")

Get the post information for the blog post with the given slug slug.

Using the page’s main module

By default, the page builds the main module that the page will display with the given page slug and saves it in the variable $ccpage->module.  This means that if you wish to manipulate the current module being displayed in the template, you must simply use this module.  For example, if you are building a template for a comic module, and you wanted to display the current comic navigation at a certain portion in the page, you would simply use this code:

$ccpage->module->navDisplay();

Similarly, you would use this code to display the entire news post area, along with tags, transcript, and comments for the current comic page:

$ccpage->module->displayAll();

Using specific modules in a template

Conversely, if you wanted to have part of the template be editable within ComicControl, or you wanted to include the content from a certain module within a template, you can build that module, save it to a variable, and then display it.  For example, if I had a sidebar with a list of links in it, and I had a text module “Links” with the slug "links" that held this information, I could display that information like so:

$linksmodule = $ccpage->buildModule(“links”);
$linksmodule->display();

This can also be used, for example, to display the most recent blog post for the blog “News” with slug "news" below the comic in my comic template.  I could do this like so:

$blogmodule = $ccpage->buildModule(“news”);
$blogmodule = $news->recentPosts(1);

You can see examples of some of these in the basic template.

Custom Pages

In order to create completely custom pages, you will still have to make use of ComicControl if you wish for the page to be at an easy-to-reach URL, such as example.com/custom-page.  In order to do this, you must simply upload a specific template file that contains the code for your custom page to your template folder.  Then, create a text module with the name of your custom page and select that template file that you just uploaded.  This text module will then effectively display your custom page.  

Adding Languages to ComicControl

In order to add languages beyond English to your installation of ComicControl, you must follow a few simple steps:

1. Download the language file from the downloads page.
2. Upload the file to your server in the comiccontrol/languages.

And that’s it!

NOTE: This method will only work with languages that we support and link here on the site.  For custom language files, you will also have to manually add them to the database.  For more information on this, please check the database information on the documentation page.

Licensing notes

The languages included on the downloads page are distributed with the permission of the translators, and by being included there they have agreed that their translations may be used in valid ComicControl installations.  The translations are the property of the translators, not ComicControl, LLC.

Don’t see the language you need?

Unfortunately, if you don’t see the language you need on the downloads page, that most likely means that translation has not been made yet.  However, if you think you can offer your help in translating ComicControl, please check out our translation guide!

Custom Functions

If you are very confident in your PHP skills, you can also write custom functions, along with any other custom PHP you wish to use through your site, and add them to your site.  Since the templates are basic PHP files, any PHP you wish to write can be included in them.  However, if you want certain functions to be available on every template, you can place this PHP in the “custom.php” file in the root directory of your site.  ComicControl will load any code placed here.  This file is not overwritten when ComicControl updates, so any code placed here will be safe on updates.

To add functionality to the backend, please use the built-in plugins feature of ComicControl.

Customizing ComicControl with Plugins

A basic plugin system is currently available for testing in ComicControl.  In order to write plugins to ComicControl, please follow these steps:

1. Read the detailed guide to ComicControl classes and functions.  The ComicControl backend makes use of the same class and function structure, especially in regards to interpreting URLs.
2. Create a folder locally to contain your plugin code.
3. Write your code in this folder; you can use the $ccpage->slugarr array to switch functionality based on the URL.  
4. When finished, upload your plugin file or files to the comiccontrol/plugin-files/ folder.
5. Insert a new row into the cc_yourdb_plugins table with the title of your plugin, the slug you will be using in ComicControl to navigate to it, a short description of the plugin, and the main file the plugin uses.  For example, if your entire plugin is in plugin-files/my-plugin.php, then you would input my-plugin.php.  If your plugin is in a folder called my-plugin/ and its main file is plugin-files/my-plugin/index.php, then you would put my-plugin/index.php.

If you follow these steps, your plugin will be accessible in ComicControl.  If you would like your plugin listed on our site, please contact us at feedback@comicctrl.com.

Once more plugins become available for ComicControl, a plugins page and guide for newbies will be added here to help add plugins to your ComicControl installation.