-
Notifications
You must be signed in to change notification settings - Fork 0
Developer Documentation
IssuePress is a single-page app WordPress plugin that allows development teams to support private Github repositories using the Github Issues API. This approach allows teams to create a dedicated support page for customers without giving them access to private Github repositories.
The goal of IssuePress is to remove the need for hosted helpdesk software like ZenDesk or HelpSpot.
IssuePress is made up of two main parts:
- The Client side Single Page Application that is powered by Angular.js
- The Server side API bindings
IssuePress looks for the page that is set to be the support page via the IP admin panel. If this page is requested, IssuePress jumps into action and overrides the served template file. (IP_template.php)
We bootstrap the Angular.js app in the IP_template.php file.
This is still largely in flux, and should change throughout the beta build process...
The IssuePress takes advantage of Angular.js' dependacy mangement system. As such, this let's us structure our application in an intelligible manner instead of being forced into a structure that doesn't quite fit out application..
There is the main app, that lives in /src/app/:
Most modules are given their own directory that typically holds a .js file & a .tpl.html file.
The .js file registers the directive/service/controller with the IP angular app and is related to the sibling .tpl.html file. The .tpl.html file is the template file should the .js (or part of the .js) require a fully fleshed template.
The main app can be split into two parts:
- Main App Functionalty
- App Components
Main App Functionality
The code not in /src/app/compononents/ is considered main app functionality. These are typically controllers/templates for pages or main page sections (e.g. the header) or main app services (e.g. app-state).
App Components
The code in /src/app/components/ are typically directives (chunks of html that serve a single purpose - i.e. breadcrumbs) that can be used through the app.
The Structure of /src/app/ is as follows:
|--app-state
| |--app-state.js
|--create-issue
| |--create-issue.js
| |--create-issue.tpl.html
|--dashboard
| |--dashboard.js
| |--dashboard.tpl.html
|--fourohfour
| |--fourohfour.js
| |--fourohfour.tpl.html
|--header
| |--header.js
| |--header.tpl.html
|--issue
| |--issue.js
| |--issue.tpl.html
|--issuepress.js
|--repo
| |--repo.js
| |--repo.tpl.html
|--sections
| |--sections.js
| |--sections.tpl.html
|--user
| |--user.js
|--components
| |--breadcrumbs
| | |--breadcrumbs.js
| | |--breadcrumbs.tpl.html
| |--issue-thread
| | |--issue-comment.tpl.html
| | |--issue-form.tpl.html
| | |--issue-thread.js
| |--message.js
| |--recent-activity
| | |--recent-activity-item.tpl.html
| | |--recent-activity.js
| | |--recent-activity.tpl.html
| |--release
| | |--release.js
| | |--release.tpl.html
| |--search
| | |--search.js
| | |--search.tpl.html
| |--sections
| | |--sections.js
| | |--sections.tpl.html
| |--ticket-list
| | |--ticket-list-item.tpl.html
| | |--ticket-list.js
| | |--ticket-list.tpl.html
There are utility services that live in /src/util/:
|--breadcrumbs.js (Custom Angular service that powers the breadcrumbs in a DRY manner)
|--gravatar
| |--gravatar.js (Custom Angular service & directive which will render gravtar image based on email - md5 service is dep)
|--marked
| |--markdown.js (Custom angular directive which provides a custom element to render markdown)
| |--marked.js (Custom angular service that wraps the marked.js script)
|--md5
| |--md5.js (Custom angular server for md5)
|--timeago.js (Custom Angular filter that provided formating dates in a time ago format)
IssuePress registers some custom API endpoints that are used to fetch, cache and server data from the GitHub API. The IP API is outlined in the IP_api.php file.
IssuePress also creates a caching layer to help save on request load by leveraging WordPress transients.
- Node.JS, NPM & Grunt - We use GruntJS as an automation & build tool, if you plan on customizing IP at all, you'll need these installed...
- AngularJS - powers IssuePress as a single-page app.
- Sass - we use sass for our css abstraction
*** It is currently NOT recommended to make local changes to your IssuePress installation. ***
We've got automatic downloads which will break if you make local changes to any of the plugin files..
We will be building out a system to handle IssuePress Customizations.. But, if you must edit IP in the mean time. It depends on what you are trying to do.. In most cases you'll need to start grunt, if you're unfamiliar with this tool, then please read up - also be sure and look at our Gruntfile.js.
If you would like to customize your IP styles, you will need to launch grunt in the plugin root directory $ grunt then edit any of the sass files in the /assets/scss/ directory.
If you are planning on customizing any part of the Angular app then you will need to launch grunt in the plugin root directory $ grunt then edit any of the js or html files inside the /src/ directory.
If you want to extend the IssuePress API then you'll need to edit the IP_API class that is found in the IP_api.php file.