Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/instructure/canvas_cc


https://github.com/instructure/canvas_cc

Last synced: 7 days ago
JSON representation

Awesome Lists containing this project

README 

        
# CanvasCc



This Gem allows for converting content to Canvas Common Cartridge format.  The Gem allows building up Canvas objects(Courses, Assignments, Quizzes, Terms, etc.), without having to think about the xml format, and then will correctly build the .imscc file.  The xsd for the CanvasCC format can be found [here](https://github.com/instructure/canvas-lms/blob/stable/lib/cc/xsd/cccv1p0.xsd).  **NOTE: not all settings are currently supported by the gem, supported settings are documented**



## Installation



Add this line to your application's Gemfile:



    gem 'canvas_cc'



And then execute:



    $ bundle



Or install it yourself as:



    $ gem install canvas_cc



## Usage

The Gem will convert content to a Canvas course, so a Course should be the first object created.



###Course



     course = CanvasCc::CanvasCC::Models::Course.new



Once a course is created it can be converted to an .imscc file as follows:



    dir = Dir.mktmpdir

    output_dir = CanvasCc::CanvasCC::CartridgeCreator.new(course).create(dir)



The output_dir will contain the .imscc file.  This file can then be uploaded to Canvas.



The following are attributes available on the Course object.

* **identifier** - unique identifier for the course

* **title** - the title of the course

* **course_code** - the course_code for the course

* **start_at** - the start at date for the course

* **conclude_at** - the conclude at date for the course

* **is_public** - whether the course is public or no

* **allow_student_wiki_edits** - Allow students to edit wiki pages

* **allow_student_forum_attachments** -Allow the student to attach files to discussion topics

* **default_wiki_editing_roles** - default value for who can edit wiki pages one of the following('teachers', 'teachers,students', 'anyone')

* **allow_student_organized_groups** - Allow students to create their own groups

* **show_all_discussion_entries** -

* **open_enrollment** - allow open enrollment in this course

* **allow_wiki_comments** - allow comments on wiki posts

* **self_enrollment** - Allow self enrollments in the course

* **turnitin_comments** - Allow turnitin comments

* **locale** - the locale of the course

* **hide_final_grade** - hide final grade from students

* **storage_quota** - the storage quota of the course in MB, for example 5000 is 5GB



###Assignments

    assignment = CanvasCc::CanvasCC::Models::Assignment.new

    #set attributes

    course.assignments << assignment



The following are attributes available on the Assignment object.

* **identifier** - unique identifier for the Assignment

* **title** - title of assignment

* **body** - details of assignment

* **due_at** - due_date of assignment

* **lock_at** - lock at date of assignment

* **unlock_at** - unlock date of assignment

* **workflow_state** - initial workflow state of assignment('active', 'unpublished')

* **points_possible** - points possible for assignment

* **assignment_group_identifier_ref** - identifier from AssignmentGroup, that this assignment should be grouped in.

* **muted** - whether or not the assignment is muted

* **turnitin_enabled** - whether or not turn it in is enabled for this assignment

* **submission_types** - valid submissions types for this assignment, this is an array of the following values('online_text_entry', 'online_upload', 'on_paper', 'discussion_topic', 'online_quiz')



        assignment.submission_types << 'online_quiz'

* **grading_type** - the grading type for the assignment, one of the following: ('letter_grade', 'points', 'percentage', 'pass_fail')



###Assessments

     assessment = CanvasCc::CanvasCC::Models::Assessment.new

     #set assessment attributes

     course.assessments << assessment

The following are attributes associated with the Assessment object.

* **identifier** - unique identifier for the Assessment

* **title** - the title of the quiz

* **description** - the description of the quiz

* **workflow_state** -  initial workflow state of the quiz ('active', 'unpublished')

* **assignment** - the assignment this quiz is associated with

* **lock_at** - lock at date of quiz

* **unlock_at** - unlock at date of quiz

* **due_at** - due at date for quiz

* **allowed_attempts** - allowed attempts on the quiz

* **access_code** - access code to unlock quiz

* **ip_filter** - ip filter to restrict quiz access

* **quiz_type** - the type of the quiz, one of the following('practice_quiz', 'assignment', 'survey', 'graded_survey')

* **shuffle_answers** - true to shuffle quiz answers

* **items** - items associated with the quiz such as questions or question banks.  See Questions below

* **time_limit** - The time limit for the quiz in minutes

* **anonymous_submissions** - allow anonymous submissions for the quiz

* **one_question_at_a_time** - show one question at a time for the quiz

* **cant_go_back** - allow the user to go back to previous questions on the quiz

* **hide_results** - hide quiz results

* **show_correct_answers** - show correct answers to quiz

* **show_correct_answers_at** - show correct answers on the following date

* **points_possible** - points possible on the quiz



###Questions

    question = CanvasCc::CanvasCC::Models::Question.create('')

    assessment.items << question



The following are attributes associated with the Question object.

* **question_type** - the type of question, passed into constructor when creating question.  One of the following('text_only_question', 'true_false_question', 'numerical_question', 'multiple_choice_question', 'multiple_answers_question', 'matching_question', 'fill_in_multiple_blanks_question, 'file_upload_question', 'essay_question')

* **identifier** - unique identifier for question

* **original_identifier** - foreign id for question

* **points_possible** - points possible for question

* **title** - the title of the question

* **material** - the question material

* **general_feedback** - the general feedback to be shown on the question

* **general_correct_feedback** - the feedback to show when answer is correct

* **general_incorrect_feedback** - the feedback to show when the answer is incorrect

* **answers** - array of answers for question.  See Answers section below



Some question types have additional attributes as noted below

* **matching_question**

  * **matches** - the matches for the question, this is a hash as follows:



        question.matches << {

          :id => unique_id,

          :question_text => the text for the question,

          :question_text_format => '1',

          :answer_text => the text for the answer,

          :answer_feedback => feedback for the question

        }

  * **distractors** - the distractors for the question, this is an array of answers to use as distractors

* **numerical_question**

  * **ranges** - the range of acceptable answers for this question.  Ranges are set as follows:

        range = CanvasCc::CanvasCC::Models::Range.new

        range.low_range = 5

        range.high_range = 10

        question.ranges[answer.id] = range



###Answers

    answer = CanvasCc::CanvasCC::Models::Answer.new()

    question.answers << answer



The following are attributes associated with Answer object.

* **id** - unique id for answer

* **answer_text** - the text for the answer

* **resp_ident** - used as a response identifier on some question types.

* **fraction** - the fraction this answer contributes to question points(0.0 - 1.0)

* **feedback** - feedback or answer



Depending on the type of question the answer_text will be formatted as follows:

* **true_false_question** - 'True' or 'False'

* **fill_in_multiple_blanks_question**

  * **answer_text** - the answer text for this blank

  * **resp_ident** - this attribute should be set to a unique_id for this answer.  In addition the material or the question should have blanks setup with the value of resp_ident in brackets.  For example 'the dog was [answer_1]', and the value of the answer resp_ident would be 'answer_1' and the answer text could be 'brown'.

* **multiple_choice_question**

  * **fraction** - this is set to 1.0 if it is the correct answer, 0.0 if incorrect answer.



###Question Banks

Question bank allow for creating a pool of questions that can be pulled from for a quiz.  They can be created as follows.



    question_bank = CanvasCc::CanvasCC::Models::QuestionBank.new

    question_bank.identifier = identifier # unique identifier for the bank

    question_bank.title = title # title of the question bank

    question_bank.questions = questions # array of questions in the question bank

    course.question_banks << question_bank



Once a question bank is setup a quiz can be set to pull questions from the bank by using QuestionGroups.  Question groups have the following attributes and can be created as follows

* **selection_number** - the number fo questions to select from the pool.

* **points_per_item** - the number of points to give each question selected.

* **identifier** - unique identifier for the Question Group

* **sourcebank_ref** - the identifier for the QuestionBank to associate with this group



    question_group = CanvasCc::CanvasCC::Models::QuestionGroup.new

    question_bank.question_groups << question_group # associate this group with the bank

    assessment.items << question_group # add gropu to assesment items



###Canvas Modules

A Canvas Module can be created as follows

    module = CanvasCc::CanvasCC::Models::CanvasModule.new

    course.canvas_modules << module



The following attributes are associated with the Module object.

* **identifier** - the unique identifier for the module object

* **title** - the title for the module

* **unlock_at** - the unlock at date for the module

* **workflow_state** - the initial workflow state for the module, either 'active' or 'unpublished'

* **module_items** - array of ModuleItems for the module.



###Module Item

A Module Item represents an item within a module, this can be one of serveral types as described below.  A ModuleItem can be crated as follows



    module_item = CanvasCc::CanvasCC::Models::ModuleItem.new

    module.items << module_item



The following attributes are associated with a ModuleItem

* **title** - the title of the ModuleItem

* **identifier** - unique identifier for the ModuleItem

* **workflow_state** - the initial workflow state for the module, either 'active' or 'unpublished'

* **content_type** - one of the following based on the content this ModuleItem contains

  * **WikiPage** - when using a page

  * **Attachment** - when referencing a file

  * **ContextModuleSubHeader** - when referencing a submodule

  * **DiscussionTopic** - when referencing a Discussion

  * **Assignment** - when referencing an Assignment

  * **Quizzes::Quiz** - when referencing an Assessment

  * **ExternalUrl** - when referencing an external url



###Module Completion Requirements

In Canvas modules can have completion req. associated with them, these can be setup in the content package as follows



    completion_requirement = CanvasCc::CanvasCC::Models::ModuleCompletionRequirement.new

    module.completion_requirements << completion_requirment



The following attributes are associated with the ModuleCompletionRequirement object.

* **identifierref** - the identifier for the module item that this completion req. is associated with

* **type** - the type of completion requirement, can be one of the following

  * **must_view** - user must view the content

  * **must_submit** - user must submit the content

  * **min_score** - user must achieve a minimum score on the content **note the following attribute must also be set when using min_score 'min_score', with a value of the minimum score**

  * **must_contribute** - user must contribute to the content



###Module Prerequisites

In Canvas modules can have prerequisites as requirements, these can be setup in the content package as follows



    module_pre_requisite = CanvasCc::CanvasCC::Models::ModulePrerequisite.new

    module.prerequisites << module_pre_requisite



The following attributes are associated with the ModulePrerequisite object

* **identifierref** - the identifier of the prerequisite object(currently should be set to another module)

* **title** - the title of the prerequisite

* **type** - should be set to 'context_module'



###Folders

A folders used to group files under the files section in Canvas, a folder can be created as follows



    folder = CanvasCc::CanvasCC::Models::CanvasFolder.new

    course.folders << folder



A Folder can have the following attributes

* **folder_location** - The location of the folder, this is a path to the folder such as '/assignments/files'

* **hidden** - whether or not the folder should be hidden.  true or false

* **locked** - whether or not the folder should be locked.  true or false



###Files

A file is a resource that is placed in the Canvas files section.  A File can be created as follows



    file = CanvasCc::CanvasCC::Models::CanvasFile.new

    course.files << file



A File can have the following attributes

* **identifier** - a unique identifier for this file

* **file_path** - the path of the file including the file name, for example '/assignments/files/test.png'

* **file_location** - the location on the filesystem for the file, for example '/tmp/files/assignments/files/test.png'

* **hidden** - whether or not this file is hidden.  true or false

* **usage_rights** - copyright information.  Valid options: "own_copyright"|"used_by_permission"|"fair_use"|"public_domain"|"creative_commons".  See [File Usage Rights](https://canvas.instructure.com/doc/api/files.html#method.usage_rights.set_usage_rights)



To reference a file inside of html content within pages, quizzes, assignments, discussions or other html content, the link can be written in the following format.  When imported the references will be correctly updated to the file path of the content within Canvas.



    Cool Image



**NOTE: to place a file in a folder, make sure the file_path is the same as the folder_location**



###Pages

A Page can be created in Canvas as follows

    page = CanvasCc::CanvasCC::Models::Page.new

    course.pages << page



A Page can have the following attributes

* **identifier** - a unique identifier for the page

* **workflow_state** - the initial workflow state for the page, either 'active' or 'unpublished'

* **page_name** - the name of the page

* **body** - the content of the page



###Discussions

A Discussion can be created in Canvas as follows



    discussion = CanvasCc::CanvasCC::Models::Discussion.new

    course.discussions << discussion



A Discussion can have the following attributes

* **identifier** - a unique identifier for the discussion

* **title** - the title of the discussion

* **text** - the text of the discussion

* **require_initial_post** - whether an initial post is required on this discussion

* **discussion_type** - the type of discussion 'threaded' or 'side_comment'

* **position** - used to control the ordering of discussions



###Assignment_groups

An AssignmentGroup can be created in Canvas as follows



    assignment_group = CanvasCc::CanvasCC::Models::AssignmentGroup.new

    course.assignment_groups << assignment_group



An AssignmentGroup can have the following attributes

* **identifier** - unique identifier for the AssignmentGroup

* **title** - the title of the AssignmentGroup

* **position** - the position of the AssignmentGroup in relation to other AssignmentGroups, used for ordering

* **group_weight** - the weight of this AssignmentGroup if weighting is desired

* **rules** - This is a hash of rules that can be applied to the AssignmentGroup.  The following rules are available

  * **drop_type** - this can be 'drop_highest', or 'drop_lowest'

  * **drop_count** - the number to drop.



        assignment_group.rules << {drop_type: 'drop_lowest', drop_count: 2}



## Contributing



1. Fork it ( http://github.com//canvas_cc/fork )

2. Create your feature branch (`git checkout -b my-new-feature`)

3. Commit your changes (`git commit -am 'Add some feature'`)

4. Push to the branch (`git push origin my-new-feature`)

5. Create new Pull Request