Cortex Snippets Client
This is the Ruby Client of the Snippets Library for Cortex. The purpose of this gem is to create a simplified way of accessing the content of snippets that are modifiable in the Cortex IPE and rendering them as useable markup, as well as the various other attributes of Webpages.
Installation
To Install simply run
gem install cortex-snippets-client
Or if you're installing from a Gemfile include it as
gem 'cortex-snippets-client`, '~> 1.0.4'
And then run
bundle install
Setup
In order to get started using the Cortex Snippets Client you're going to need to initialize a Cortex Client object that you will be using to interact with Cortex. You will need a separate client for each tenant you have active.
The following is a basic setup for a Cortex Client:
$cortex = Cortex::Client.new(
key: 1234567,
secret: ABCDEFG,
base_url: http://localhost:3000,
scopes: view:webpages)
Once you have your Cortex Client object you can simply initialize and store a Cortex Snippet Client object by creating it like so:
@cortex_snippet_client = Cortex::Snippets::Client.new($cortex)
Usage
Use of this gem is generally split into two categories: Snippets and Webpages
Snippets refers to blocks of markup that are editable in Cortex IPE and, through the use of this gem, persist into the tenant application. This allows the copy changes made in IPE to replace default blocks on the page and your changes to be shown.
Webpages refer to the created webpages themselves, which have several bits of relevant metadata including, but not limited to: title, keywords, and indexing information.
Snippets
Basic Usage
To be properly used, snippets must have both a reference in the Markup:
# A view in your application
= snippet :id => 'a_snippet_name' do
%h1.heavy
This is my awesome title
And a call to the Snippets Client:
# app/helpers/application_helper.rb
def snippet(options = {}, &block)
@cortex_snippet_client.snippet(request, options, capture(&block))
end
This will take the given id of the snippet, search the relevant Cortex Tenant for any matches, and return a block of content - if it does not find a match it will simply return the default block of Markup.
Additional Usage
Any additional metadata you pass into the options
hash will extend to the final, rendered snippet. For example:
# A view in your application
= snippet :id => 'a_snippet_name', :class => 'some_test_class' do
%h1.heavy
This is my awesome title
Will result in the following markup being rendered:
<snippet id="a_snippet_name" class="some_test_class">
<h1 class="heavy">
This is my awesome title
</h1>
</snippet>
Webpages
The webpage system of this gem is used quite differently, in order to properly reference it you will need to do the following:
webpage = @cortex_snippet_client.current_webpage(request)
This will give you a webpage object from your current Cortex Tenant with all of the given metadata for that page as attributes. Here is a comprehensive list of accessible information for any Webpage:
Attribute | Description |
---|---|
seo_title | The title for the current Webpage. |
seo_description | The description of the current Webpage. |
seo_keywords | An array of search keywords for the current Webpage.1 |
seo_robots | An array of indexing robot information for the current Webpage.2 |
noindex | The noindex information for the Webpage. Included in seo_robots
|
nofollow | The nofollow information for the Webpage. Included in seo_robots
|
noodp | The noodp information for the Webpage. Included in seo_robots
|
nosnippet | The nosnippet information for the Webpage. Included in seo_robots
|
noarchive | The noarchive information for the Webpage. Included in seo_robots
|
noimageindex | The noimageindex information for the Webpage. Included in seo_robots
|
dynamic_yield | A hash of Dynamic Yield information from the current Webpage. |
tables_widget_data | A hash containing Tables Widget configuration data. |
tables_widget_data_for | An array (usually) containing table data for a single section. |
snippets | An array of the associated snippets with the current Webpage. |
1:
The resulting array from seo_keywords
can be entered into a single keyword meta tag like so:
%meta{name: 'keywords', content: webpage.seo_keywords.join(',') }
2:
The resulting array from seo_robots
can be entered into a single robots meta tag like so:
%meta{name: 'robots', content: webpage.seo_robots.join(',') }
Changelog
See CHANGELOG.md for a comprehensive and updated history of changes to this gem. Additionally this gem uses GitHub version, so you can go there and see any general release notes.
Contributing
The following is in addition to the usual GitHub flow (fork the repo, pull it down locally, etc...)
- If you would like to contribute to this gem please create a branch entitled
issue/#{GitHub Issue Number}-#{Issue Name}
. If you are submitting a new feature without an attached issue then name your branchfeature/#{Descriptive Feature Name}
- Make your changes locally and write tests for all created changes
- For any added commits please follow the patterns of Semantic Git Commits
- Create a Pull Request in which you detail what you changed, why you changed it, and every other relevant detail to your PR. If your PR is for an open issue please link to that.
- Correspond with us! (We're really very nice)
- When it's accepted and approved we will merge in your code!!
License
Apache License, Version 2.0