Content Developer
How to
Develop Content for OpenEI
Are you interested in adding, contributing, and editing content on OpenEI? Our Quickstart Guide provides an overview on how to get started. The following page details tips and tricks our developers have found helpful working in OpenEI. If you learn something new that's not on this page, please feel free to add it so that we may all continue to learn and grow from each other's hard work.
We have also summarized the most popular data types added to OpenEI. These include Organizations and subsets of Organizations, tools, utility rates, and more.
Tips and Tricks
Breakpoints
Debugging with OpenEI can be tricky, but Inspector breakpoints are your friend! If you haven't used breakpoints before spend some time researching how to use them with your favorite Inspector. I find that hot keys are best when stepping into and out of code because it enables you to use the cursor for hovering over variables to see their values more swiftly. Look up the hot keys for the browser you're using. For chrome:
- over:
cmd 'or f10 - into:
cmd ;or f11 - next breakpoint:
cmd \
Create
- Pages: Prod or Dev
- Widgets: Similar to creating a page, but be sure to append 'Widget:' to the name of the page and in the contents add the category
- For all others (Templates, Categories, Properties, Forms, etc) go to Semantic Forms at Prod or Dev
Dev Development
OpenEI is hosted on https://dev.openei.org and https://openei.org. Dev is wiped at the end of each week and replaced with Prod.
- Many links on Dev point to Prod and there is currently no check being done to adjust links based on the environment at the time this page was last updated. As a result, be careful when working on Dev that you don't accidentally start working on Prod after following a link!
- If you are working on a larger project on Dev that is not ready for Prod at the end of the week, you may choose to save your work locally on your computer so that you may commit your changes at a later time. When you copy and paste code, be sure additional indents are not added. This is easy enough when you copy and paste if you just press
cmd zwhen you notice your text editor introduce indents. I typically save my working files with .html extensions on my computer. If you prefer to work exclusively in OpenEI, just be mindful of introducing bugs to Prod before you are ready.
Development Tool Hub
Most anything you can do in the Wiki can be found at Special Pages located on the footer of most any OpenEI page if you have permission to see it. https://openei.org/wiki/Special:SpecialPages
Errors
- Saving Page: If a page throws an error while trying to save, press save again until it saves.
Extensions and Versioning
It can be helpful to know what extensions we are using to find documentation. A list of extensions/versions for the project are available here: https://openei.org/wiki/Special:Version
Finding References
- There is no built-in way to find out if a Widget's function or the Widget itself is being used in other places! The quickest way is to use Replace to search by string. When using Replace it is good practice to have the same string copied in the Original Text as the Replacement Text so that were you to accidentally select Replace on the Replace Results, no change is actually made. Use Replace here: https://openei.org/wiki/Special:ReplaceText
- Where Templates implement a category, it can be possible to use categories to find instance implementation. EX:
AWAKENInstrumentationPage defines category: AWAKENin https://openei.org/wiki/Special:Templates
Hot Keys
-
ctrl eon Mac or PC will open the edit screen for any OpenEI wikipage you are currently on
Parsers
- The Widget parser is completed server side and cannot parse templates inside of it. Further, Widgets cannot nest widgets.
- MediaWiki: server side parsing (as a result, MediaWiki variables and parameters cannot be used by JS in Widgets, they've already been parsed to HTML by then)
- JS (When using Widgets): runs client side (this is why mediawiki content cannot be injected via JS)
- Widget parameters CAN be passed to JS for client-side use (see Widgets)
Properties
In OpenEI, a Property is a feature of the Semantic MediaWiki that allows users to enter semantic data into the OpenEI Wiki. A Property describes a particular piece of information, and should be distinguished from a Category.
A Category is meant to represent membership in some group, while Properties are used for basically all other data in the Wiki. For example, you could have a category called Countries, and Brazil, India and the United States would all fall in that category. In OpenEI, a category relationship is comprised two things: a page and a category, e.g. the page about Brazil is in the category: Countries.
A Property relationship in OpenEI is comprised of three things: a page, a property and a value (the value might be piece of text, a number, or another page in the Wiki). An example of a Property might be has member Country, where an international organization such as the United Nations has member countries, and countries such as Argentina, Australia, and the United States would all be values of the Property has member Country. Add a Property
A note on Property Types: The default property type is page. If you would like a different type, it must be specified during declaration. There is a character limit for some types. If you need a long character limit, choose string/text.
Refreshing/ Seeing Changes (In Absence of Hot Reloading)
When work has been saved on a page, you must select Refresh to see it. This is in the same (top right) drop down menu as Edit. Usually I have to refresh once with OpenEI and then refresh the browser a couple times to see the change. It helps to have the Inspector open and pointing at the source code you changed. If you don't see it changed in the source code, refresh until you do.
If you would like to see a change before saving, sometimes 'Show Preview' will work. This is not always the case. On occasion it can be a little buggy and it will also not render changes that require you to refresh the page first because a change was made to another page, template, or widget.
Templates
- Can reference any number of widgets
- Help to reduce code redundancy and create repeatable components.
- Limitations:
- Cannot use
<script> - Cannot use
<style></style>. To avoid Inline styling, you can use Widgets if styles will be repeated often.
- Cannot use
Testing Semantic Queries
Use the Semantic Search to get an idea of the results you should be receiving and how to ask them. Ex:
Widgets
Our Current Widget list can be found here: https://openei.org/wiki/Category:Widgets
- Enable the use of
<style>and<script type="text/javascript">tags - Offer some potential to reduce code redundancy, but keep in mind that Widgets can NOT embed widgets
- Widget's have parameters like templates. These parameters can be used in JS, HTML, or other using the syntax
<!--{$param2|escape:'html'}--> - Widgets can use the JS functions of other Widgets
Frequently Added Information
Some content can easily be added to OpenEI using forms, which means users can easily contribute information without necessarily learning to use the wiki markup format. Some of the most frequently added information is described below.
Organizations
Within OpenEI, there are numerous types of Organizations. Some are very broadly defined, such as Companies, and others are more specific, such as Utility Companies and Policy Organizations. The types of organizations are described below.
What is a Company?
In OpenEI, almost any business can be considered a Company. Entities that are NOT Companies include universities and other academic institutions (these are Research Institutions) and government agencies. Companies are a type of Organization. Add a Company
What is a Financial Organization
Financial Organizations include (but are not limited to) financial advisors, lending agencies, and venture capitalists. Financial Organizations are a type of Organization, and may also be Companies. Add a Financial Organization
What is a Networking Organization?
Networking Organizations are those organizations created specifically to provide networking opportunities for professions, but may also include some professional and trade associations (which may also be considered Policy Organizations). Networking Organizations are a type of Organization. Add a Networking Organization
What is a Policy Organization?
Policy Organizations include trade associations, policy-focused Research Institutions, advocacy organizations, and organizations that lobby for a particular energy-related issue. Policy Organizations include both Non-Governmental Organizations (NGOs) and Political Action Committees (PACs). Policy Organizations are a type of Organization. Add a Policy Organization
What is a Research Institution?
Research Institutions include universities and other organizations dedicated to research and knowledge sharing, in areas including, but not limited to: science, policy, and economics. Some Research Institutions may also be categorized as Policy Organizations and, in some cases, Companies. Research Institutions are a type of Organization. Add a Research Institution
What is a Utility Company?
- Utility Companies are electric cooperatives, transmission, generation, and/or distribution service providers, municipal utilities, and any power-providing organization. Utility Companies are a type of Company and a type of Organization.
What is an Oil and Gas Company?
- Oil and Gas Companies explore for, process, distribute and/or sell oil, natural gas, or other petroleum products. Oil and Gas Companies are a type of Company and a type of Organization. Add a Oil and Gas Company
Events
An Event must have a name (or title) plus a date and time. For an Event to be added to OpenEI, the user must also provide a description. Providing the location, name of the organizer, event website, and related tags (or keywords) is optional. Events may be displayed within OpenEI on a calendar, a timeline, or a chronological list. Add an Event
Tools
In OpenEI, Tools include a variety of resources that might be helpful for making energy-related decisions. Tools may include: datasets, maps, software/modeling tools, podcasts, videos, presentations, webinars, workshops, publications, online calculators, templates, training materials, guides/manuals, best practices, and case studies. Tools may be accessible via a Website, a desktop application, a spreadsheet, or another medium. Some tools have a global focus, others a local focus. Add a Tool
Utility Rates
OpenEI collects data on Utility Rates via a crowd-sourced approach. OpenEI created a special form to allow users to easily add data on electricity rates, tariffs, or other information on the sale or purchase of electricity, demand charges for electricity service, time-of-use-rates, and tiered rates. Utility Rates are collected from rate structures that apply to residential, commercial, and industrial sectors. Add a Utility Rate